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

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

نمای کلی

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

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

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

جیمیل در پاسخ به دستور CAPABILITY پشتیبانی از افزونه‌های خود را تبلیغ می‌کند. پشتیبانی از افزونه‌ها در این سند با وجود X-GM-EXT-1 در فهرست قابلیت‌های پشتیبانی‌شده مشخص شده است.

به کاربران اکیداً توصیه می‌شود که خود را با دستور IMAP ID ( RFC 2971 ) معرفی کنند و یک آدرس تماس را به عنوان جایگزین در صورت نیاز به تغییر در این افزونه‌ها قرار دهند.

در زیر مثالی از handshake و استفاده از دستور 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

جیمیل از افزونه 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]/Important" ).

XLIST منسوخ شده است

دستور XLIST مخصوص جیمیل در سال ۲۰۱۳ به نفع استاندارد فهرست ویژه IMAP منسوخ شد. به مشتریان اکیداً توصیه می‌شود در اسرع وقت از XLIST به استاندارد صنعتی ویژه مهاجرت کنند. توجه داشته باشید که نام‌های ویژگی استاندارد ویژه مشابه نام‌های ویژگی XLIST قدیمی هستند اما یکسان نیستند.

پسوند دستور SEARCH: X-GM-RAW

برای دسترسی به سینتکس کامل جستجوی جیمیل، جیمیل ویژگی جستجوی X-GM-RAW را ارائه می‌دهد. آرگومان‌هایی که همراه با ویژگی X-GM-RAW هنگام اجرای دستورات SEARCH یا UID SEARCH ارسال می‌شوند، به همان روشی که در رابط وب جیمیل تفسیر می‌شوند، تفسیر خواهند شد.

در زیر نمونه‌ای از فراخوانی تابع 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

جیمیل برای هر ایمیل یک شناسه پیام منحصر به فرد ارائه می‌دهد تا یک پیام منحصر به فرد بتواند در چندین پوشه شناسایی شود. بازیابی این شناسه پیام از طریق ویژگی X-GM-MSGID در دستور FETCH پشتیبانی می‌شود. شناسه پیام یک عدد صحیح بدون علامت ۶۴ بیتی است و معادل اعشاری رشته هگز شناسه مورد استفاده در رابط وب و 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)

دسترسی به شناسه‌ی رشته‌ی جیمیل: X-GM-THRID

جیمیل یک شناسه رشته برای مرتبط کردن گروه‌های پیام‌ها به همان روشی که در رابط وب جیمیل وجود دارد، ارائه می‌دهد. بازیابی این شناسه رشته از طریق ویژگی X-GM-THRID در دستور FETCH پشتیبانی می‌شود. شناسه رشته یک عدد صحیح بدون علامت ۶۴ بیتی است و معادل اعشاری رشته هگز شناسه مورد استفاده در رابط وب و API جیمیل است.

در زیر نمونه‌ای از یک فراخوانی برای بازیابی X-GM-THRID چندین پیام (در دو thread) با دستور 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)

دسترسی به برچسب‌های جیمیل: X-GM-LABELS

جیمیل برای اهداف IMAP، برچسب‌ها را به عنوان پوشه در نظر می‌گیرد. به همین ترتیب، برچسب‌ها را می‌توان با استفاده از دستورات استاندارد IMAP، یعنی CREATE ، RENAME و DELETE ، که روی پوشه‌ها عمل می‌کنند، تغییر داد. برچسب‌های سیستمی، که برچسب‌های ایجاد شده توسط جیمیل هستند، رزرو شده و با پیشوند "[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)

منابع