IMAP-Erweiterungen

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 UIDs 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. UIDs 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