Rozszerzenia IMAP

Ten dokument opisuje rozszerzenia IMAP dostarczane przez Gmaila oraz sposób ich użycia przez programistów. Zakładamy, że znasz protokół IMAP.

Omówienie

Gmail udostępnia zestaw rozszerzeń IMAP, dzięki którym autorzy klientów IMAP mogą korzystać z protokołu IMAP podobnie do użytkowników Gmaila. Deweloperzy integrujący funkcje Gmaila ze swoimi aplikacjami internetowymi lub aplikacjami mobilnymi mogą chcieć korzystać z interfejsu API RESTowego Gmail API.

Rozszerzenia mogą być używane podczas uzyskiwania dostępu do Gmaila za pomocą standardowego protokołu IMAP lub podczas nawiązywania połączenia przy użyciu OAuth.

Sprawdzam, czy są rozszerzenia

Gmail wspiera obsługę rozszerzenia w odpowiedzi na polecenie CAPABILITY. Obsługa rozszerzeń w tym dokumencie oznacza obecność atrybutu X-GM-EXT-1 na liście obsługiwanych funkcji.

Zdecydowanie zalecamy klientom, aby wypowiadali się przy użyciu polecenia IMAP ID (RFC 2971) i podawali adres kontaktowy na wypadek, gdyby trzeba było zmienić te rozszerzenia.

Poniżej znajduje się przykład uzgadniania użycia 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

Specjalne zastosowanie rozszerzenia LIST

Gmail obsługuje rozszerzenie IMAP LIST do specjalnych skrzynek pocztowych, które udostępnia nowe atrybuty do folderów specjalnych. Te atrybuty informują klienta, które foldery są wyjątkowe (np. \All). Bieżąca lista folderów specjalnych zawiera: Oznaczone gwiazdką, Ważne, Wysłane elementy, Wersje robocze, Spam, Wszystkie oraz Kosz. Wszystkie odpowiedzi LIST zawierają te atrybuty specjalnego zastosowania. Nie są to nowe atrybuty CAPABILITY ani elementy, które muszą zostać ENABLEd.

Poniżej znajdziesz przykład transkrypcji rozmowy 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 Specjalne zastosowanie z dodatkowym atrybutem \Important dodanym do Priorytetów w Gmailu (tj. "[Gmail]/Important").

Usługa XLIST została wycofana

Polecenie XLIST dotyczące Gmaila zostało wycofane w 2013 roku na rzecz standardowego listy IMAP. Zdecydowanie zalecamy jak najszybsze przejście z XLIST na specjalny standard branżowy. Zwróć uwagę, że nazwy atrybutów standardowych są do siebie podobne, ale nie są takie same jak starsze nazwy atrybutów 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 wraz z atrybutem X-GM-RAW podczas wykonywania poleceń SEARCH lub UID SEARCH będą interpretowane tak samo jak w interfejsie internetowym Gmaila.

Poniżej znajduje się przykład transkrypcji wywołania SEARCH przy użyciu 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 Gmaila: X-Gm-MSGID

W przypadku każdego e-maila Gmail ma unikalny identyfikator, dzięki któremu ta wiadomość może być identyfikowana 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 niepodpisana liczba całkowita, która jest dziesiętnym odpowiednikiem ciągu szesnastkowego identyfikatora używanego w interfejsie internetowym i interfejsie interfejsu Gmail API.

Poniżej znajdziesz przykładową transkrypcję wywołania X-GM-MSGID umożliwiającego pobranie wiadomości za pomocą polecenia FETCH:

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

Atrybutu X-GM-MSGID można też używać w poleceniach SEARCH lub UID SEARCH do znajdowania numerów sekwencji lub UID wiadomości z podanym identyfikatorem wiadomości w Gmailu. Poniżej znajduje się przykład transkrypcji rozmowy służącej do pobrania UID wiadomości za pomocą polecenia UID SEARCH:

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 przez atrybut X-GM-THRID w poleceniu FETCH. Identyfikator wątku to 64-bitowa niepodpisana liczba całkowita, która jest dziesiętnym odpowiednikiem ciągu szesnastkowego identyfikatora używanego w interfejsie internetowym i interfejsie Gmail API.

Poniżej znajduje się przykład transkrypcji rozmowy służącej do pobrania X-GM-THRID kilku wiadomości (w 2 wątkach) za pomocą polecenia 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)

Atrybutu X-GM-THRID można też używać w poleceniach SEARCH lub UID SEARCH do znajdowania numerów sekwencji lub UID wiadomości z danego wątku. Poniżej znajduje się przykład transkrypcji rozmowy służącej do pobrania UID kilku wiadomości za pomocą polecenia UID SEARCH:

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

Dostęp do etykiet Gmaila: X-Gm-LABEL

W przypadku protokołu IMAP Gmail traktuje etykiety jako foldery. W związku z tym etykiety można modyfikować przy użyciu standardowych poleceń IMAP (CREATE, RENAME i DELETE), które działają w folderach. Etykiety systemowe utworzone przez Gmaila są rezerwowane i poprzedzone ciągiem „[Gmail]” lub „[GoogleMail]” na liście etykiet. Użyj polecenia XLIST, aby pobrać całą listę etykiet skrzynki pocztowej.

Etykiety dla danej wiadomości można pobrać przy użyciu atrybutu X-GM-LABELS za pomocą polecenia FETCH. Wartość jest zwracana jako lista atrybutów ASTRING z kodowaniem UTF-7. ASTRING to atom lub ciąg znaków zgodnie z definicją RFC.

Poniżej znajduje się przykład transkrypcji rozmowy służącej do pobrania X-GM-LABELS kilku wiadomości za pomocą polecenia 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)

Etykiety można dodawać do wiadomości za pomocą polecenia STORE w połączeniu z atrybutem X-GM-LABELS. Poniżej znajduje się przykładowy zapis pokazujący, 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)

Atrybutu X-GM-LABELS można też używać w poleceniach SEARCH lub UID SEARCH do znajdowania numerów sekwencji lub UID wiadomości ze wszystkimi wiadomościami w folderze o danej etykiecie. Poniżej znajduje się przykład transkrypcji rozmowy służącej do pobrania numerów sekwencji kilku wiadomości za pomocą polecenia SEARCH:

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

Odsyłacze