إضافات IMAP

يصف هذا المستند إضافات IMAP المُقدمة من Gmail وكيف يمكن أن يستخدمها المطورون. يفترض هذا المستند الإلمام ببروتوكول IMAP.

نظرة عامة

يوفّر Gmail مجموعة من إضافات بروتوكول IMAP للسماح لمؤلفي برامج IMAP بتقديم تجربة أقرب إلى Gmail من خلال بروتوكول IMAP. بدلاً من ذلك، قد يرغب مطوّرو البرامج الذين يدمجون ميزات Gmail في تطبيقات الويب أو التطبيقات المتوافقة مع الأجهزة الجوّالة في استخدام واجهة برمجة تطبيقات Gmail RESTful.

يمكن استخدام الإضافات عند الدخول إلى 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. يتم عرض السمة كقائمة من ASTRINGs، مع ترميزها بالترميز 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)

المراجع