תוספי 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 בנקודת הקצה של IMAP ב-Gmail:

* 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 הוצא משימוש

הפקודה 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. מזהה ה-thread הוא מספר שלם לא חתום בגודל 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 בכמה הודעות באמצעות הפקודה UID SEARCH:

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)

קובצי עזר