إضافات IMAP

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

نظرة عامة

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

يمكن استخدام الإضافات عند الوصول إلى 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 مع إضافة LIST لبروتوكول 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

يتّبع الردّ معيار Special-Use مع إضافة السمة \Important لـ "البريد الوارد المهم" في Gmail (أي "[Gmail]/Important").

تم إيقاف XLIST نهائيًا

تم إيقاف الأمر XLIST الخاص بـ Gmail نهائيًا في عام 2013 لصالح معيار قائمة الاستخدام الخاص ببروتوكول IMAP. ننصح العملاء بشدة بنقل البيانات من XLIST إلى معيار Special-Use المتّبَع في المجال في أقرب وقت ممكن. يُرجى العِلم أنّ أسماء السمات العادية ذات الاستخدام الخاص تتشابه مع أسماء سمات 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)

المراجع