Rozszerzenia IMAP

W tym dokumencie opisujemy rozszerzenia IMAP dostępne w Gmailu i opisujemy, jak deweloperzy mogą ich używać. W tym dokumencie zakładamy, że znamy protokół IMAP.

Opis

Gmail udostępnia zestaw rozszerzeń IMAP, dzięki którym autorzy klientów IMAP mogą korzystać z protokołu IMAP w sposób zbliżony do Gmaila. Deweloperzy integrujący funkcje Gmaila z aplikacjami internetowymi lub mobilnymi mogą zamiast tego korzystać z interfejsu Gmail API typu REST.

Z ich rozszerzeń można korzystać, gdy uzyskujesz dostęp do Gmaila za pomocą standardowego protokołu IMAP lub podczas łączenia się przez OAuth.

Sprawdzanie obecności rozszerzeń

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

Zdecydowanie zalecamy klientom podawanie się za pomocą polecenia identyfikatora IMAP (RFC 2971) i dodawanie adresu kontaktowego jako opcji zastępczej na wypadek, gdyby konieczne było wprowadzenie zmian w tych rozszerzeniach.

Poniżej znajdziesz przykładowe uzgadnianie połączenia i użycie 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 rozszerzenie polecenia LIST

Gmail obsługuje rozszerzenie LIST LIST for Special-Use Mailboxes, 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 do specjalnego zastosowania. To nie jest nowy obiekt CAPABILITY ani coś, co klienci muszą mieć atrybut ENABLEd.

Oto przykładowa transkrypcja połączenia do 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 zastosowań specyficznych przez dodanie do skrzynki Priorytety Gmaila dodatkowego atrybutu \Important (np. "[Gmail]/Important").

XLIST została wycofana

Polecenie XLIST związane z Gmailem zostało wycofane w 2013 roku i zastąpione standardem listy specjalnego użycia IMAP. Zdecydowanie zalecamy klientom jak najszybsze przejście z XLIST na standard branżowy specjalnego zastosowania. Nazwy standardowych atrybutów do specjalnego użytku są podobne do starszych nazw atrybutów XLIST, ale nie są takie same.

Rozszerzenie polecenia SEARCH: X-GM-RAW

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

Poniżej znajdziesz przykładową transkrypcję wywołania 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 Gmaila: X-GM-MSGID

Dla każdego e-maila Gmail używa unikalnego identyfikatora, dzięki czemu unikalna wiadomość może zostać zidentyfikowana w wielu folderach. Pobranie tego identyfikatora wiadomości jest możliwe przez atrybut X-GM-MSGID w poleceniu FETCH. Identyfikator wiadomości jest 64-bitową, nieoznaczoną liczbą całkowitą. Jest to dziesiętny odpowiednik ciągu szesnastkowego identyfikatora używanego w interfejsie internetowym i interfejsie Gmail API.

Poniżej znajdziesz przykładową transkrypcję połączenia służącego do pobrania wartości X-GM-MSGID wiadomości przy użyciu 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 i UID SEARCH do znajdowania numerów sekwencyjnych lub parametru UID wiadomości z określonym identyfikatorem wiadomości Gmaila. Poniżej znajdziesz przykładową transkrypcję połączenia służącego do pobrania wartości UID wiadomości przy użyciu polecenia UID SEARCH:

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

Dostęp do wątku Gmail o identyfikatorze: X-GM-THRID

Gmail udostępnia identyfikator wątku, który pozwala wią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 jest 64-bitową nieoznaczoną liczbą całkowitą. Jest to dziesiętny odpowiednik ciągu szesnastkowego identyfikatora używanego w interfejsie internetowym i interfejsie Gmail API.

Poniżej znajdziesz przykładową transkrypcję połączenia służącego do pobrania wartości X-GM-THRID kilku wiadomości (w 2 wątkach) przy użyciu 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 i UID SEARCH do znajdowania numerów sekwencyjnych lub UID wiadomości w danym wątku. Poniżej znajduje się przykładowa transkrypcja połączenia, które ma na celu pobranie UID kilku wiadomości przy użyciu 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-LABELS

Gmail traktuje etykiety jako foldery na potrzeby protokołu IMAP. Z tego względu etykiety można modyfikować za pomocą standardowych poleceń IMAP (CREATE, RENAME i DELETE), które działają w odniesieniu do folderów. Etykiety systemowe, czyli etykiety utworzone przez Gmaila, są zarezerwowane i mają na liście przedrostek „[Gmail]” lub „[GoogleMail]”. Aby uzyskać całą listę etykiet skrzynki pocztowej, użyj polecenia XLIST.

Etykiety danej wiadomości można pobrać przy użyciu atrybutu X-GM-LABELS z poleceniem FETCH. Atrybut jest zwracany w postaci listy elementów ASTRING zakodowanych w odpowiednim formacie UTF-7. ASTRING to atom lub ciąg znaków zdefiniowany w dokumencie RFC.

Poniżej znajdziesz przykładową transkrypcję połączenia służącego do pobrania wartości X-GM-LABELS kilku wiadomości przy użyciu 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 znajdziesz przykładową transkrypcję pokazującą dodanie etykiety 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żyć w poleceniach SEARCH i UID SEARCH do znalezienia numerów sekwencyjnych lub UID wszystkich wiadomości w folderze z daną etykietą. Poniżej znajdziesz przykładową transkrypcję połączenia służącego do pobierania numerów sekwencyjnych z użyciem polecenia SEARCH:

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

Odniesienia