Rozszerzenia IMAP

Ten dokument opisuje rozszerzenia protokołu IMAP udostępniane przez Gmaila i sposób, w jaki mogą być wykorzystywane przez programistów. Zakładamy, że znasz protokół IMAP.

Przegląd

Gmail udostępnia zestaw rozszerzeń IMAP, które umożliwiają autorom klientów IMAP zapewnienie użytkownikom większej liczby funkcji podobnych do tych w Gmailu. Deweloperzy, którzy chcą zintegrować funkcje Gmaila z aplikacjami internetowymi lub mobilnymi, mogą zamiast tego użyć interfejsu API RESTful Gmail API.

Rozszerzenia mogą być używane podczas uzyskiwania dostępu do Gmaila za pomocą standardowego protokołu IMAP lub podczas łączenia się przez OAuth.

Sprawdzanie obecności rozszerzeń

Gmail informuje o obsłudze rozszerzeń w odpowiedzi na polecenie CAPABILITY. Obsługa rozszerzeń w tym dokumencie jest oznaczona symbolem X-GM-EXT-1 na liście obsługiwanych funkcji.

Zdecydowanie zalecamy, aby klienci przedstawiali się za pomocą polecenia IMAP ID (RFC 2971) i podawali adres kontaktowy na wypadek konieczności wprowadzenia zmian w tych rozszerzeniach.

Oto przykład uzgadniania połączenia i użycia polecenia CAPABILITY w punkcie końcowym IMAP Gmaila:

* 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

Rozszerzenie polecenia LIST do specjalnego zastosowania

Gmail obsługuje rozszerzenie IMAP LIST dla skrzynek pocztowych specjalnego przeznaczenia, które udostępnia nowe atrybuty dla folderów specjalnych. Te atrybuty informują klienta, które foldery są specjalne (np. \All). Obecna lista folderów specjalnych obejmuje: Oznaczone gwiazdką, Ważne, Wysłane, Wersje robocze, Spam, Wszystkie i Kosz. Wszystkie odpowiedzi LIST zawierają te atrybuty specjalnego zastosowania. Nie jest to nowa CAPABILITY ani coś, co musi być ENABLEd przez klientów.

Poniżej znajdziesz przykładową transkrypcję rozmowy z 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

Odpowiedź jest zgodna ze standardem Special-Use z dodatkowym atrybutem \Important dodanym dla Priorytetów w Gmailu (czyli "[Gmail]/Important").

XLIST jest wycofany

Polecenie XLIST specyficzne dla Gmaila zostało wycofane w 2013 r. na rzecz standardu listy specjalnego zastosowania IMAP. Zachęcamy klientów do jak najszybszego przejścia z XLIST na standard branżowy Special-Use. Pamiętaj, że nazwy atrybutów standardowych do specjalnego użytku są podobne do nazw starszych atrybutów XLIST, ale nie są z nimi identyczne.

Rozszerzenie polecenia SEARCH: X-GM-RAW

Aby zapewnić dostęp do pełnej składni wyszukiwania w Gmailu, Gmail udostępnia atrybut wyszukiwania X-GM-RAW. Argumenty przekazywane wraz z atrybutem X-GM-RAW podczas wykonywania poleceń SEARCH lub UID SEARCH będą interpretowane w taki sam sposób jak w interfejsie internetowym Gmaila.

Oto przykładowy zapis rozmowy z SEARCH z użyciem atrybutu X-GM-RAW:

a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)

Dostęp do unikalnego identyfikatora wiadomości w Gmailu: X-GM-MSGID

Gmail przypisuje każdej wiadomości e-mail unikalny identyfikator, dzięki czemu można ją zidentyfikować w wielu folderach. Pobieranie tego identyfikatora wiadomości jest obsługiwane przez atrybut X-GM-MSGID w poleceniu FETCH. Identyfikator wiadomości to 64-bitowa liczba całkowita bez znaku, która jest dziesiętnym odpowiednikiem ciągu szesnastkowego identyfikatora używanego w interfejsie internetowym i interfejsie Gmail API.

Poniżej znajdziesz przykładowy zapis rozmowy, w której za pomocą polecenia FETCH pobierany jest X-GM-MSGID wiadomości:

a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)

Atrybut X-GM-MSGID może być też używany w poleceniach SEARCH lub UID SEARCH do znajdowania numerów sekwencyjnych lub UID wiadomości na podstawie jej identyfikatora w Gmailu. Oto przykładowy zapis rozmowy, w której za pomocą polecenia UID SEARCH pobierany jest UID wiadomości:

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

Dostęp do identyfikatora wątku Gmaila: X-GM-THRID

Gmail udostępnia identyfikator wątku, aby powiązać grupy wiadomości w taki sam sposób jak w interfejsie internetowym Gmaila. Pobieranie tego identyfikatora wątku jest obsługiwane za pomocą atrybutu X-GM-THRID w poleceniu FETCH. Identyfikator wątku to 64-bitowa liczba całkowita bez znaku, która jest dziesiętnym odpowiednikiem ciągu szesnastkowego identyfikatora używanego w interfejsie internetowym i interfejsie Gmail API.

Poniżej znajdziesz przykładowy zapis rozmowy, w której za pomocą polecenia FETCH pobierane są X-GM-THRID kilku wiadomości (w 2 wątkach):

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)

Atrybut X-GM-THRID może być też używany w poleceniach SEARCH lub UID SEARCH do znajdowania numerów sekwencyjnych lub UID wiadomości w danym wątku. Poniżej znajdziesz przykładowy zapis rozmowy, w której za pomocą polecenia UID SEARCH pobierane są UID kilku wiadomości:

a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)

Dostęp do etykiet Gmaila: X-GM-LABELS

Gmail traktuje etykiety jako foldery na potrzeby protokołu IMAP. Dlatego etykiety można modyfikować za pomocą standardowych poleceń IMAP: CREATE, RENAME i DELETE, które działają na foldery. Etykiety systemowe, czyli etykiety utworzone przez Gmaila, są zarezerwowane i na liście etykiet mają prefiks „[Gmail]” lub „[GoogleMail]”. Aby uzyskać pełną listę etykiet skrzynki pocztowej, użyj polecenia XLIST.

Etykiety dla danej wiadomości można pobrać za pomocą atrybutu X-GM-LABELS z poleceniem FETCH. Atrybut jest zwracany jako lista obiektów ASTRING zakodowanych w formacie UTF-7. ASTRING to atom lub ciąg znaków zgodnie z definicją w RFC.

Poniżej znajdziesz przykładowy zapis rozmowy, w której za pomocą polecenia FETCH pobierane są identyfikatory X-GM-LABELS kilku wiadomości:

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)

Etykiety można dodać do wiadomości za pomocą polecenia STORE w połączeniu z atrybutem X-GM-LABELS. Poniżej znajdziesz przykładowy zapis rozmowy, w którym dodano etykietę do wiadomości:

a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)

Atrybut X-GM-LABELS może być też używany w poleceniach SEARCH lub UID SEARCH do znajdowania numerów sekwencyjnych lub UID wszystkich wiadomości w folderze z daną etykietą. Oto przykładowy zapis rozmowy, w której za pomocą polecenia SEARCH pobierane są numery sekwencyjne kilku wiadomości:

a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)

Odniesienia