Rozszerzenia IMAP

Ten dokument opisuje rozszerzenia IMAP udostępniane przez Gmaila i sposób, w jaki deweloperzy mogą z nich korzystać. Zakładamy, że znasz protokół IMAP.

Przegląd

Gmail udostępnia zestaw rozszerzeń IMAP, które umożliwiają autorom klientów IMAP zapewnienie bardziej podobnego do Gmaila środowiska za pomocą IMAP. Deweloperzy, którzy chcą zintegrować funkcje Gmaila z aplikacjami internetowymi lub mobilnymi, mogą zamiast tego używać interfejsu Gmail API opartego na architekturze REST.

Możesz używać rozszerzeń, gdy uzyskujesz dostęp do Gmaila za pomocą standardowego protokołu IMAP lub gdy łączysz się z OAuth.

Sprawdzanie obecności rozszerzeń

Gmail informuje o obsłudze rozszerzeń w odpowiedzi na polecenie CAPABILITY. Obecność symbolu X-GM-EXT-1 na liście obsługiwanych funkcji oznacza obsługę rozszerzeń opisanych w tym dokumencie.

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

Poniżej znajdziesz przykład uzgadniania połączenia i użycia polecenia CAPABILITY na 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 klienci muszą włączyć.

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 standardu specjalnego zastosowania są podobne, ale nie identyczne z nazwami atrybutów starszego typu XLIST.

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 za pomocą atrybutu X-GM-RAW podczas wykonywania poleceń SEARCH lub UID SEARCH są 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żesz zidentyfikować unikalną wiadomość w wielu folderach. Identyfikator wiadomości możesz pobrać za pomocą atrybutu 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)

Możesz też użyć atrybutu X-GM-MSGID w poleceniach SEARCH lub UID SEARCH, aby znaleźć numery sekwencyjne lub UID wiadomości na podstawie identyfikatora wiadomości 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. Ten identyfikator wątku możesz pobrać 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 znaków szesnastkowych identyfikatora używanego w interfejsie internetowym i interfejsie Gmail API.

Poniżej znajduje się 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)

Możesz też użyć atrybutu X-GM-THRID w poleceniach SEARCH lub UID SEARCH, aby znaleźć numery sekwencyjne 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 możesz modyfikować etykiety za pomocą standardowych poleceń IMAP, które działają na foldery: CREATE, RENAME i DELETE. Etykiety systemowe, czyli etykiety utworzone przez Gmaila, są zarezerwowane i poprzedzone w liście etykiet ciągiem „[Gmail]” lub „[GoogleMail]”. Użyj polecenia LIST, aby uzyskać pełną listę etykiet skrzynki pocztowej.

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

Poniżej znajdziesz przykładowy zapis rozmowy, w której za pomocą polecenia FETCH pobierane są 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)

Możesz dodać etykiety do wiadomości za pomocą polecenia STORE w połączeniu z atrybutem X-GM-LABELS. Oto przykład transkrypcji pokazującej, jak dodać 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)

Możesz też użyć atrybutu X-GM-LABELS w poleceniach SEARCH lub UID SEARCH, aby znaleźć numery sekwencyjne 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