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 и не то, что клиенты должны включать.

Ниже приведен пример стенограммы звонка в 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]" в списке меток. Используйте команду LIST , чтобы получить полный список меток для почтового ящика.

Метки для заданного сообщения можно получить с помощью атрибута 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)

Ссылки