In diesem Dokument werden die von Gmail bereitgestellten IMAP-Erweiterungen und ihre Verwendung durch Entwickler beschrieben. In diesem Dokument wird davon ausgegangen, dass Sie mit dem IMAP-Protokoll vertraut sind.
Überblick
Gmail bietet eine Reihe von IMAP-Erweiterungen, mit denen Autoren von IMAP-Clients über IMAP eine Gmail-ähnliche Nutzererfahrung bieten können. Entwickler, die Gmail-Funktionen in ihre Web- oder mobilen Apps integrieren, sollten stattdessen die RESTful Gmail API verwenden.
Die Erweiterungen können beim Zugriff auf Gmail über das Standard-IMAP-Protokoll oder beim Herstellen einer Verbindung über OAuth verwendet werden.
Das Vorhandensein von Erweiterungen wird geprüft
Gmail gibt die Unterstützung der Erweiterung als Antwort auf den Befehl CAPABILITY
an. In diesem Dokument werden Erweiterungen unterstützt, die in der Liste der unterstützten Funktionen durch X-GM-EXT-1
gekennzeichnet sind.
Es wird dringend empfohlen, dass Clients sich mit dem IMAP-ID-Befehl (RFC 2971) anmelden und eine Kontaktadresse als Fallback angeben, falls Änderungen an diesen Erweiterungen erforderlich sind.
Im Folgenden finden Sie ein Beispiel für einen Handshake und die Verwendung des Befehls CAPABILITY
auf dem IMAP-Endpunkt von Gmail:
* 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
Erweiterung des Befehls LIST speziell für die Verwendung
Gmail unterstützt die Erweiterung „IMAP LIST Extension for Special-Use Mailboxes“ (IMAP-Listenerweiterung für Postfächer für besondere Zwecke) mit neuen Attributen für spezielle Ordner. Diese Attribute teilen dem Kunden mit, welche Ordner besonders sind (z. B. \All
). Die aktuelle Liste der speziellen Ordner umfasst Folgendes: „Markiert“, „Wichtig“, „Gesendete Elemente“, „Entwürfe“, „Spam“, „Alle E-Mails“ und „Papierkorb“. Alle LIST
-Antworten enthalten diese speziellen Attribute. Es handelt sich nicht um ein neues CAPABILITY
-Element oder etwas, das von Clients als ENABLEd
angegeben werden muss.
Hier ist ein Beispieltranskript eines Aufrufs an 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
Die Antwort entspricht dem Standard für spezielle Anwendungen und enthält ein zusätzliches \Important
-Attribut für den sortierten Eingang von Gmail (z.B. "[Gmail]/Important"
).
XLIST ist veraltet
Der Gmail-spezifische XLIST
-Befehl wurde 2013 zugunsten des IMAP Special-Use List Standard eingestellt. Kunden wird dringend empfohlen, so schnell wie möglich von XLIST
zum Branchenstandard für spezielle Verwendungen zu migrieren. Beachten Sie, dass die Namen der Standardattribute für spezielle Verwendungen den alten XLIST
-Attributnamen ähneln, aber nicht identisch sind.
Erweiterung des Befehls „SEARCH“: X-GM-RAW
Um Zugriff auf die vollständige Gmail-Suchsyntax zu erhalten, bietet Gmail das Suchattribut X-GM-RAW
. Argumente, die beim Ausführen der Befehle SEARCH
oder UID SEARCH
mit dem Attribut X-GM-RAW
übergeben werden, werden genauso interpretiert wie in der Gmail-Weboberfläche.
Das folgende Beispiel zeigt ein Transkript eines Aufrufs von SEARCH
mit dem Attribut X-GM-RAW
:
a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)
Zugriff auf die eindeutige Gmail-Nachrichten-ID: X-GM-MSGID
Gmail stellt jeder E-Mail eine eindeutige Nachrichten-ID zur Verfügung, sodass eine eindeutige Nachricht über mehrere Ordner hinweg identifiziert werden kann. Das Abrufen dieser Nachrichten-ID wird über das Attribut X-GM-MSGID
im Befehl FETCH
unterstützt. Die Nachrichten-ID ist eine vorzeichenlose 64-Bit-Ganzzahl und die dezimale Entsprechung für den hexadezimalen ID-String, der in der Weboberfläche und der Gmail API verwendet wird.
Das folgende Beispiel zeigt ein Transkript eines Aufrufs zum Abrufen des X-GM-MSGID
einer Nachricht mit dem Befehl FETCH
:
a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)
Das Attribut X-GM-MSGID
kann auch in den Befehlen SEARCH
oder UID SEARCH
verwendet werden, um die Sequenznummern oder UID
einer Nachricht anhand der Gmail-Nachrichten-ID zu finden. Das folgende Beispiel zeigt ein Transkript eines Aufrufs zum Abrufen des UID
einer Nachricht mit dem Befehl UID SEARCH
:
a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)
Zugriff auf die Gmail-Thread-ID: X-GM-THRID
Gmail stellt eine Thread-ID bereit, um Gruppen von Nachrichten auf dieselbe Weise wie in der Gmail-Weboberfläche zu verknüpfen. Das Abrufen dieser Thread-ID wird über das Attribut X-GM-THRID
im Befehl FETCH
unterstützt. Die Thread-ID ist eine vorzeichenlose 64-Bit-Ganzzahl. Sie ist das dezimale Äquivalent für den hexadezimalen ID-String, der in der Weboberfläche und der Gmail API verwendet wird.
Das folgende Beispiel zeigt ein Transkript eines Aufrufs zum Abrufen der X-GM-THRID
mehrerer Nachrichten (in zwei Threads) mit dem Befehl 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)
Das Attribut X-GM-THRID
kann auch in den Befehlen SEARCH
oder UID SEARCH
verwendet werden, um die Sequenznummern oder UID
von Nachrichten in einem bestimmten Thread zu finden. Im Folgenden finden Sie ein Beispieltranskript eines Aufrufs zum Abrufen der UID
s mehrerer Nachrichten mit dem Befehl UID SEARCH
:
a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)
Zugriff auf Gmail-Labels: X-GM-LABELS
In Gmail werden Labels im IMAP-Zugriff wie Ordner behandelt. Labels können also mit den IMAP-Standardbefehlen CREATE
, RENAME
und DELETE
geändert werden, die für Ordner gelten. Systemlabels sind Labels, die von Gmail erstellt werden. Sie sind reserviert und in der Labelliste mit dem Präfix "[Gmail]" oder "[GoogleMail]" vorangestellt. Verwenden Sie den Befehl XLIST
, um die gesamte Liste der Labels für ein Postfach abzurufen.
Die Labels für eine bestimmte Nachricht können mithilfe des Attributs X-GM-LABELS
mit dem Befehl FETCH
abgerufen werden. Das Attribut wird als Liste von ASTRING
-Werten zurückgegeben, die gegebenenfalls in UTF-7 codiert sind. Ein ASTRING
ist ein atom oder ein String gemäß der Definition in RFC.
Das folgende Beispiel zeigt ein Transkript eines Aufrufs zum Abrufen des X-GM-LABELS
mehrerer Nachrichten mit dem Befehl 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)
Labels können einer Nachricht mit dem Befehl STORE
in Verbindung mit dem Attribut X-GM-LABELS
hinzugefügt werden. Im Folgenden finden Sie ein Beispieltranskript, das zeigt, wie einer Nachricht ein Label hinzugefügt wird:
a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)
Das Attribut X-GM-LABELS
kann auch in den Befehlen SEARCH
oder UID SEARCH
verwendet werden, um die Sequenznummern bzw. UID
s aller Nachrichten im Ordner mit einem bestimmten Label zu finden. Das folgende Beispiel zeigt ein Transkript eines Aufrufs, mit dem mit dem Befehl SEARCH
die Sequenznummern mehrerer Nachrichten abgerufen werden:
a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)
Verweise
- IMAP: RFC 3501: INTERNET MESSAGE ACCESS PROTOCOL – VERSION 4rev1
- IMAP-ID: RFC 2971: IMAP4-ID-ERWEITERUNG
- IMAP – spezielle Verwendung: RFC 6154: IMAP LIST Extension for Special-Use Mailboxes