برنامه های افزودنی IMAP

این سند افزونه های IMAP ارائه شده توسط Gmail و نحوه استفاده از آنها توسط توسعه دهندگان را شرح می دهد. این سند آشنایی با پروتکل IMAP را فرض می کند.

نمای کلی

Gmail مجموعه‌ای از برنامه‌های افزودنی IMAP را ارائه می‌کند تا به نویسندگان سرویس گیرنده‌های IMAP اجازه دهد تجربه‌ای شبیه به Gmail را از طریق IMAP ارائه دهند. برنامه‌نویسانی که ویژگی‌های Gmail را در برنامه‌های وب یا تلفن همراه خود ادغام می‌کنند، ممکن است بخواهند از RESTful Gmail API استفاده کنند.

برنامه‌های افزودنی ممکن است هنگام دسترسی به Gmail از طریق پروتکل استاندارد IMAP یا هنگام اتصال از طریق OAuth استفاده شوند.

بررسی وجود برنامه های افزودنی

جی‌میل پشتیبانی برنامه‌های افزودنی خود را در پاسخ به فرمان 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 از برنامه افزودنی 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 به استاندارد صنعت استفاده ویژه مهاجرت کنند. توجه داشته باشید که نام‌های ویژگی استاندارد 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)

مراجع