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

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

Обзор

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

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

Ниже приведён пример записи вызова команды FETCH для получения X-GM-MSGID сообщения:

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 SEARCH для получения UID сообщения:

a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)

Доступ к ветке обсуждения в Gmail: ID: X-GM-THRID

Gmail предоставляет идентификаторы веток для связывания групп сообщений аналогично веб-интерфейсу Gmail. Получение этого идентификатора ветки поддерживается с помощью атрибута X-GM-THRID в команде FETCH . Идентификатор ветки представляет собой 64-битное беззнаковое целое число и является десятичным эквивалентом шестнадцатеричной строки идентификатора, используемой в веб-интерфейсе и API Gmail .

Ниже приведён пример записи вызова команды FETCH для получения X-GM-THRID нескольких сообщений (в двух потоках):

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 SEARCH для получения UID нескольких сообщений:

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.

Ниже приведён пример записи вызова команды FETCH для получения X-GM-LABELS нескольких сообщений:

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)

Ссылки