תוספי IMAP

במסמך הזה מתוארים תוספי IMAP ש-Gmail מספקת, ומוסבר איך מפתחים יכולים להשתמש בהם. במסמך הזה אנחנו מניחים שאתם מכירים את פרוטוקול IMAP.

סקירה כללית

‫Gmail מספקת קבוצה של תוספים ל-IMAP כדי לאפשר למפתחים של תוכנות אימייל מסוג IMAP לספק חוויה שדומה יותר ל-Gmail דרך IMAP. מפתחים שמשלבים תכונות של Gmail באפליקציות האינטרנט או באפליקציות לנייד שלהם יכולים להשתמש במקום זאת ב-Gmail API מבוסס REST.

אפשר להשתמש בתוספים כשניגשים ל-Gmail דרך פרוטוקול IMAP הרגיל או כשמתחברים דרך OAuth.

בדיקה אם יש תוספים

‫Gmail מפרסם את התמיכה שלו בתוספים בתגובה שלו לפקודה CAPABILITY. התמיכה בתוספים במסמך הזה מסומנת בנוכחות הסמל X-GM-EXT-1 ברשימת היכולות הנתמכות.

מומלץ מאוד ללקוחות להזדהות באמצעות הפקודה IMAP ID ‏ (RFC 2971), ולכלול כתובת ליצירת קשר כגיבוי למקרה שיידרשו שינויים בתוספים האלה.

בדוגמה הבאה מוצג תהליך לחיצת היד ושימוש בפקודה CAPABILITY בנקודת הקצה של Gmail IMAP:

* OK Gimap ready for requests from 127.0.0.1 k2if6111336rvb.0
a001 LOGIN username@gmail.com password
a001 OK username@gmail.com authenticated (Success)
a001 OK Login successful
a002 CAPABILITY
* CAPABILITY IMAP4rev1 UNSELECT LITERAL+ IDLE NAMESPACE QUOTA ID XLIST CHILDREN X-GM-EXT-1
a002 OK Success
a003 ID ("name" "clientname" "version" "1.2.3" "vendor" "companyname" "contact" "foo@example.com")
* ID ("name" "GImap" "vendor" "Google, Inc." "support-url" "http://mail.google.com/support" "remote-host" "127.0.0.1")
a003 OK Success

תוסף לשימוש מיוחד של הפקודה LIST

‫Gmail תומך בתוסף IMAP LIST לתיבות דואר לשימוש מיוחד, שמספק מאפיינים חדשים לתיקיות מיוחדות. המאפיינים האלה מאפשרים ללקוח לדעת אילו תיקיות הן מיוחדות (למשל, \All). הרשימה הנוכחית של תיקיות מיוחדות כוללת את התיקיות הבאות: מסומנות בכוכב, חשובות, פריטים שנשלחו, טיוטות, ספאם, כל הדואר ואשפה. כל התשובות של LIST מכילות את המאפיינים האלה לשימוש מיוחד. זה לא CAPABILITY חדש או משהו שצריך ENABLEd על ידי לקוחות.

הנה דוגמה לתמליל של שיחה עם LIST:

a004 LIST "" "*"
* LIST (\HasNoChildren) "/" "INBOX"
* LIST (\Noselect \HasChildren) "/" "[Gmail]"
* LIST (\HasNoChildren \All) "/" "[Gmail]/All Mail"
* LIST (\HasNoChildren \Drafts) "/" "[Gmail]/Drafts"
* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important"
* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail"
* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam"
* LIST (\HasNoChildren \Flagged) "/" "[Gmail]/Starred"
* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash"
a004 OK Success

התשובה עומדת בתקן Special-Use, עם מאפיין נוסף \Important שנוסף למיון הדואר ב-Gmail (כלומר "[Gmail]/Important").

הפקודה XLIST הוצאה משימוש

הפקודה XLIST הספציפית ל-Gmail הוצאה משימוש בשנת 2013, לטובת התקן של רשימת שימושים מיוחדים ב-IMAP. מומלץ מאוד ללקוחות לעבור מ-XLIST לתקן התעשייתי לשימוש מיוחד בהקדם האפשרי. שימו לב: שמות המאפיינים הרגילים לשימוש מיוחד דומים לשמות המאפיינים הקודמים XLIST, אבל לא זהים להם.

הרחבה של הפקודה SEARCH: X-GM-RAW

כדי לספק גישה לתחביר המלא של החיפוש ב-Gmail, ‏ Gmail מספק את מאפיין החיפוש X-GM-RAW. ארגומנטים שמועברים יחד עם מאפיין X-GM-RAW כשמריצים את הפקודות SEARCH או UID SEARCH יפורשו באותו אופן כמו בממשק האינטרנט של Gmail.

הדוגמה הבאה היא תמליל של שיחה עם SEARCH באמצעות המאפיין X-GM-RAW:

a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)

גישה למזהה ההודעה הייחודי ב-Gmail: X-GM-MSGID

‫Gmail מספק מזהה הודעה ייחודי לכל אימייל, כדי שאפשר יהיה לזהות הודעה ייחודית בכמה תיקיות. אפשר לאחזר את מזהה ההודעה הזו באמצעות המאפיין X-GM-MSGID בפקודה FETCH. מזהה ההודעה הוא מספר שלם לא מסומן של 64 ביט, והוא שווה ערך עשרוני למחרוזת ההקסדצימלית של המזהה שמשמש בממשק האינטרנט וב-Gmail API.

דוגמה לתמליל של שיחה להצגת X-GM-MSGID של הודעה באמצעות הפקודה FETCH:

a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)

אפשר להשתמש במאפיין X-GM-MSGID גם בפקודות SEARCH או UID SEARCH כדי למצוא את מספרי הרצף או את UID של הודעה מסוימת, בהינתן מזהה ההודעה ב-Gmail. בדוגמה הבאה מוצג תמליל של שיחה לאחזור UID של הודעה באמצעות הפקודה UID SEARCH:

a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)

גישה למזהה השרשור ב-Gmail: X-GM-THRID

‫Gmail מספק מזהה שרשור כדי לשייך קבוצות של הודעות באותו אופן כמו בממשק האינטרנט של Gmail. אפשר לאחזר את מזהה השרשור הזה באמצעות המאפיין X-GM-THRID בפקודה FETCH. מזהה השרשור הוא מספר שלם לא מסומן של 64 ביט, והוא שווה ערך עשרוני למחרוזת ההקסדצימלית של המזהה שמשמשת בממשק האינטרנט וב-Gmail API.

דוגמה לתמליל של שיחה לאחזור של X-GM-THRID של כמה הודעות (בשני שרשורים) באמצעות הפקודה FETCH:

a008 FETCH 1:4 (X-GM-THRID)
* 1 FETCH (X-GM-THRID 1278455344230334865)
* 2 FETCH (X-GM-THRID 1266894439832287888)
* 3 FETCH (X-GM-THRID 1266894439832287888)
* 4 FETCH (X-GM-THRID 1266894439832287888)
a008 OK FETCH (Success)

אפשר להשתמש במאפיין X-GM-THRID גם בפקודות SEARCH או UID SEARCH כדי למצוא את מספרי הרצף או את UID של הודעות בשרשור נתון. התמליל הבא הוא דוגמה לשיחה להצגת מזהי ההודעות של כמה הודעות באמצעות הפקודה UID SEARCH:UID

a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)

גישה לתוויות ב-Gmail: X-GM-LABELS

‫Gmail מתייחס לתוויות כאל תיקיות לצורך IMAP. לכן, אפשר לשנות תוויות באמצעות פקודות IMAP רגילות, CREATE, RENAME ו-DELETE, שפועלות על תיקיות. תוויות מערכת, שהן תוויות שנוצרו על ידי Gmail, הן שמורות ומופיע לפניהן [Gmail] או [GoogleMail] ברשימת התוויות. כדי לקבל את כל רשימת התוויות של תיבת דואר, משתמשים בפקודה XLIST.

אפשר לאחזר את התוויות של הודעה מסוימת באמצעות המאפיין X-GM-LABELS עם הפקודה FETCH. המאפיין מוחזר כרשימה של ASTRING, בקידוד UTF-7 לפי הצורך. ‫ASTRING הוא אטום או מחרוזת כפי שמוגדר ב-RFC.

לפניכם תמליל לדוגמה של שיחה להצגת X-GM-LABELS של כמה הודעות באמצעות הפקודה FETCH:

a010 FETCH 1:4 (X-GM-LABELS)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante"))
* 2 FETCH (X-GM-LABELS (foo))
* 3 FETCH (X-GM-LABELS ())
* 4 FETCH (X-GM-LABELS (\Drafts))
a010 OK FETCH (Success)

אפשר להוסיף תוויות להודעה באמצעות הפקודה STORE בשילוב עם המאפיין X-GM-LABELS. זו דוגמה לתמליל שמראה איך מוסיפים תווית להודעה:

a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)

אפשר להשתמש במאפיין X-GM-LABELS גם בפקודות SEARCH או UID SEARCH כדי למצוא את מספרי הרצף או את UID של כל ההודעות בתיקייה עם תווית נתונה. הנה תמליל לדוגמה של שיחה להצגת מספרי הרצף של כמה הודעות באמצעות הפקודה SEARCH:

a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)

קובצי עזר