إضافات IMAP

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

نظرة عامة

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

يمكنك استخدام الإضافات عند الوصول إلى Gmail من خلال بروتوكول IMAP العادي أو عند الربط باستخدام OAuth.

التحقّق من وجود إضافات

يعلن Gmail عن إمكانية استخدام الإضافات في رده على الأمر CAPABILITY. يشير ظهور X-GM-EXT-1 في قائمة الإمكانات المتوافقة إلى أنّ الجهاز يتيح استخدام الامتدادات الموضّحة في هذا المستند.

ننصح بشدة بأن تعرّف العملاء عن أنفسهم باستخدام الأمر ID في IMAP (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 إلى معيار Special-Use الصناعي في أقرب وقت ممكن. يُرجى العِلم أنّ أسماء سمات 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]" قبلها في قائمة التصنيفات. استخدِم الأمر LIST للحصول على القائمة الكاملة بالتصنيفات الخاصة بصندوق بريد.

يمكنك استرداد التصنيفات لرسالة معيّنة باستخدام السمة X-GM-LABELS مع الأمر FETCH. يتم عرض السمة كقائمة من ASTRINGs، مرمّزة بمعيار 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)

المراجع