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

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

Обзор

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

Расширения можно использовать при доступе к Gmail через стандартный протокол IMAP или при подключении через OAuth .

Проверка наличия расширений

Gmail объявляет о поддержке расширений в ответ на команду CAPABILITY . Поддержка расширений в этом документе обозначается наличием X-GM-EXT-1 в списке поддерживаемых возможностей.

Клиентам настоятельно рекомендуется объявлять себя с помощью команды IMAP ID ( RFC 2971 ) и включать контактный адрес в качестве запасного варианта на случай, если потребуются изменения в этих расширениях.

Ниже приведен пример установления связи и использования команды CAPABILITY на конечной точке IMAP Gmail:

* 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 на отраслевой стандарт специального назначения. Обратите внимание, что имена стандартных атрибутов специального использования похожи, но не идентичны именам устаревших атрибутов 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)

Ссылки