IMAP-расширения

В этом документе описываются расширения IMAP, предоставляемые Gmail, и способы их использования разработчиками. Предполагается, что читатель знаком с протоколом IMAP .

Обзор

Gmail предоставляет набор расширений IMAP, позволяющих разработчикам IMAP-клиентов создавать более похожий на Gmail интерфейс. Разработчикам, интегрирующим функции Gmail в свои веб- или мобильные приложения, может быть полезен RESTful Gmail API .

Расширения могут использоваться при доступе к 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 поддерживает расширение 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 устарел

Специфическая для Gmail команда XLIST была упразднена в 2013 году в пользу стандарта IMAP Special-Use List Standard . Клиентам настоятельно рекомендуется как можно скорее перейти с 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-битное беззнаковое целое число и является десятичным эквивалентом шестнадцатеричной строки идентификатора, используемой в веб-интерфейсе и API Gmail .

Ниже приведен пример расшифровки вызова для извлечения 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-битное беззнаковое целое число и является десятичным эквивалентом шестнадцатеричной строки идентификатора, используемой в веб-интерфейсе и API Gmail .

Ниже приведен пример расшифровки вызова для извлечения 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)

Ссылки