Rozszerzenia IMAP

W tym dokumencie opisujemy rozszerzenia IMAP dostępne w Gmailu i sposoby ich wykorzystania przez programistów. Ten dokument zakłada, że znasz protokół IMAP.

Omówienie

Gmail udostępnia zestaw rozszerzeń IMAP, aby umożliwić autorom klientów IMAP tworzenie aplikacji IMAP bardziej zbliżonych do Gmaila. Deweloperzy integrujący funkcje Gmaila w aplikacji internetowej lub mobilnej mogą zamiast tego użyć interfejsu Gmail API w formacie REST.

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

Sprawdzanie obecności rozszerzeń

Gmail reklamuje obsługę 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.

Klienci powinni koniecznie podawać swój identyfikator za pomocą polecenia IMAP ID (RFC 2971) i uwzględniać adres kontaktowy jako adres zapasowy na wypadek, gdyby konieczne było wprowadzenie zmian w tych rozszerzeniach.

Poniżej przedstawiamy przykładowy proces nawiązywania połączenia i używania polecenia CAPABILITY w przypadku punktu końcowego 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 LIST IMAP dla skrzynek pocztowych do użytku specjalnego, 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 foldery: Oznaczone gwiazdką, Ważne, Elementy wysłane, Wersje robocze, Spam, Wszystkie wiadomości i Kosz. Wszystkie odpowiedzi LIST zawierają te atrybuty specjalne. Nie jest to nowy atrybut CAPABILITY ani coś, co ENABLEd musi być wymagane przez klientów.

Oto przykład transkrypcji 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 użycia specjalnego, a do skrzynki Priorytety Gmaila dodano dodatkowy atrybut \Important (na przykład "[Gmail]/Important").

Pole XLIST zostało wycofane

W 2013 roku polecenie XLIST w Gmailu zostało wycofane i zastąpione listą specjalnych zastosowań IMAP. Zachęcamy klientów do jak najszybszego przejścia z wersji XLIST na standard branżowy dotyczący treści przeznaczonych do użytku specjalnego. Pamiętaj, że nazwy standardowych atrybutów specjalnych są podobne, ale nie identyczne ze starszymi nazwami 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 w taki sam sposób jak w interfejsie internetowym Gmaila.

Oto przykładowy zapis wywołania funkcji 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 Gmail: X-GM-MSGID

Gmail przypisuje unikalny identyfikator do każdej wiadomości, aby można było ją zidentyfikować w wielu folderach. Pobranie tego identyfikatora wiadomości jest obsługiwane 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 znaków szesnastkowych identyfikatora używanego w interfejsie internetowym i interfejsie Gmail API.

Oto przykładowy zapis wywołania do pobrania X-GM-MSGID 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 sekwencyjnych lub UID wiadomości o podanym identyfikatorze w Gmailu. Oto przykładowy zapis wywołania 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 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.

Oto przykładowy zapis wywołania funkcji 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 przypadku poleceń SEARCH lub UID SEARCH, aby znaleźć numery sekwencji lub UID wiadomości w danym wątku. Poniżej znajdziesz przykładową transkrypcję wywołania, które ma pobrać 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

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

Etykiety danej wiadomości można pobrać, używając atrybutu X-GM-LABELS z poleceniem FETCH. Atrybut jest zwracany jako lista elementów ASTRING zakodowana odpowiednio w formacie UTF-7. Wartość ASTRING to atom lub ciąg znaków zdefiniowany w dokumencie RFC.

Poniżej znajdziesz przykładową transkrypcję połączenia, które ma pobrać 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 znajduje się przykładowy zapis, który pokazuje dodawanie 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żywać w przypadku poleceń SEARCH lub UID SEARCH, aby znaleźć numery sekwencji lub UID wszystkich wiadomości w folderze z określoną etykietą. Oto przykładowy zapis wywołania polecenia SEARCH służącego do pobierania numerów sekwencji kilku wiadomości:

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

Pliki referencyjne