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
- IMAP: RFC 3501: PROTOCOL DOSTĘPU W wiadomościach INTERNETOWYCH – WERSJA 4rev1
- Identyfikator IMAP: RFC 2971: ROZSZERZENIE identyfikatora IMAP
- IMAP Special-Use: RFC 6154: IMAP LIST Extension for Special-Use Mailboxes