תוספי IMAP

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

סקירה

Gmail מספק קבוצה של תוספי IMAP כדי לאפשר למחברים של לקוחות IMAP לספק חוויה שדומה יותר ל-Gmail באמצעות IMAP. ייתכן שמפתחים שמשלבים תכונות של Gmail באפליקציות לאינטרנט או לנייד ירצו להשתמש ב-API של Gmail ל-RESTful.

ניתן להשתמש בתוספים במהלך גישה ל-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 לתיבות דואר לשימוש מיוחד, שמספק מאפיינים חדשים לתיקיות מיוחדות. המאפיינים האלה מאפשרים ללקוח לדעת אילו תיקיות מיוחדות (למשל, \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

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

XLIST הוצא משימוש

ב-2013, הפקודה XLIST הספציפית ל-Gmail הוצאה משימוש לטובת IMAP Special-Use List Standard. אנחנו ממליצים בחום ללקוחות לעבור בהקדם האפשרי מ-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. מזהה ההודעה הוא מספר שלם לא חתום (unsigned integer) בגרסת 64 ביט, והוא שווה ערך עשרוני למחרוזת ה-hex של המזהה שמשמשת בממשק האינטרנט וב-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. מזהה ה-thread הוא מספר שלם לא חתום בגרסת 64 ביט. זהו מספר שלם שווה ערך עשרוני למחרוזת ה-hex של המזהה שמשמשת בממשק האינטרנט וב-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 של ההודעות בשרשור נתון. לפניכם תמליל לדוגמה של שיחה לאחזור UIDs של מספר הודעות באמצעות הפקודה UID SEARCH:

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

גישה לתוויות Gmail: X-GM- קיימת

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

ניתן לאחזר את התוויות של הודעה מסוימת באמצעות המאפיין X-GM-LABELS עם הפקודה FETCH. המאפיין מוחזר כרשימה של תווי ASTRING, ומקודדים ב-UTF-7 בהתאם. ASTRING הוא atom או מחרוזת כפי שהוגדר ב-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)

קובצי עזר