إضافات IMAP

يوضح هذا المستند إضافات بروتوكول IMAP التي توفرها Gmail وكيف يمكن للمطورين استخدامها. يفترض هذا المستند معرفة بروتوكول IMAP.

نظرة عامة

توفر خدمة Gmail مجموعة من إضافات الوصول عبر IMAP للسماح لمؤلفي برامج الوصول عبر IMAP بتقديم تجربة تشبه Gmail من خلال الوصول عبر IMAP. قد يريد المطوّرون الذين يدمجون ميزات Gmail في تطبيقات الويب أو الأجهزة الجوّالة استخدام واجهة برمجة تطبيقات Gmail المستندة إلى بروتوكول 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. رقم تعريف سلسلة المحادثات هو عدد صحيح غير موقَّع بحجم 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 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)

المراجع