תוספי 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 חדש או משהו שהלקוחות צריכים להפעיל.

התמליל הבא הוא דוגמה לשיחה עם 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, אבל לא זהים להם.

הרחבה של פקודת החיפוש: 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 SEARCH כדי לאחזר את UID של הודעה:

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 של כמה הודעות באמצעות הפקודה 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]‎ ברשימת התוויות. כדי לקבל את כל רשימת התוויות של תיבת דואר, משתמשים בפקודה LIST.

אפשר לאחזר את התוויות של הודעה מסוימת באמצעות המאפיין 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)

קובצי עזר