إضافات 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 LIST لصناديق البريد المخصّصة للاستخدام الخاص، والتي توفّر سمات جديدة للمجلدات الخاصة. تتيح هذه السمات للعميل معرفة المجلدات الخاصة (مثل \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 هو عنصر أو سلسلة كما هو محدّد في 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)

المراجع