המסמך הזה מתאר את תוספי 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
של ההודעות בשרשור נתון. לפניכם תמליל לדוגמה של שיחה לאחזור UID
s של מספר הודעות באמצעות הפקודה 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)
קובצי עזר
- IMAP: RFC 3501: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
- מזהה IMAP: RFC 2971: תוסף מזהה IMAP4
- שימוש מיוחד ב-IMAP: RFC 6154: תוסף רשימת IMAP לתיבות דואר לשימוש מיוחד