يصف هذا المستند إضافات بروتوكول 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)
المراجع
- بروتوكول IMAP: RFC 3501: بروتوكول الوصول إلى رسائل الإنترنت، الإصدار 4rev1
- رقم تعريف IMAP: RFC 2971: IMAP4 ID EXTENSION
- الاستخدام الخاص ببروتوكول IMAP: RFC 6154: إضافة IMAP LIST لمستودعات البريد ذات الاستخدام الخاص