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.

Übersicht

Gmail bietet eine Reihe von IMAP-Erweiterungen, mit denen Entwickler von IMAP-Clients eine Gmail-ähnlichere Erfahrung über IMAP ermöglichen können. Entwickler, die Gmail-Funktionen in ihre Web- oder mobilen Apps einbinden möchten, sollten stattdessen die RESTful Gmail API verwenden.

Die Erweiterungen können verwendet werden, wenn über das Standard-IMAP-Protokoll auf Gmail zugegriffen wird oder wenn eine Verbindung über OAuth hergestellt wird.

Prüfen, ob Erweiterungen vorhanden sind

Gmail bewirbt die Unterstützung von Erweiterungen in der Antwort auf den Befehl CAPABILITY. Die Unterstützung von Erweiterungen in diesem Dokument wird durch das Vorhandensein von X-GM-EXT-1 in der Liste der unterstützten Funktionen angegeben.

Clients wird dringend empfohlen, sich mit dem IMAP-ID-Befehl (RFC 2971) zu melden und eine Kontaktadresse als Fallback anzugeben, falls Änderungen an diesen Erweiterungen erforderlich sind.

Im Folgenden finden Sie ein Beispiel für den Handshake und die Verwendung des Befehls CAPABILITY am Gmail-IMAP-Endpunkt:

* 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

Sonderverwendung der Erweiterung des LIST-Befehls

Gmail unterstützt die IMAP LIST Extension for Special-Use Mailboxes, die neue Attribute für spezielle Ordner bietet. Mithilfe dieser Attribute kann der Client erkennen, welche Ordner besonders sind (z. B. \All). Die aktuelle Liste der speziellen Ordner umfasst: „Markiert“, „Wichtig“, „Gesendete Objekte“, „Entwürfe“, „Spam“, „Alle E-Mails“ und „Papierkorb“. Alle LIST-Antworten enthalten diese Attribute für die spezielle Nutzung. Das ist kein neues CAPABILITY und muss nicht von Clients ENABLEd werden.

Das folgende Beispiel zeigt ein Transkript eines Anrufs 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 die besondere Verwendung und enthält das zusätzliche Attribut \Important für den sortierten Posteingang von Gmail (d.h. "[Gmail]/Important").

XLIST wurde eingestellt

Der Gmail-spezifische XLIST-Befehl wurde 2013 zugunsten des IMAP Special-Use List Standard eingestellt. Wir empfehlen Kunden dringend, so bald wie möglich von XLIST auf den Branchenstandard für die spezielle Nutzung zu migrieren. Die Namen der Standardattribute für die eingeschränkte Nutzung sind ähnlich, aber nicht identisch mit den Namen der alten XLIST-Attribute.

Erweiterung des SEARCH-Befehls: X-GM-RAW

Um Zugriff auf die vollständige Gmail-Suchsyntax zu ermöglichen, bietet Gmail das Suchattribut X-GM-RAW. Argumente, die beim Ausführen der Befehle SEARCH oder UID SEARCH zusammen mit dem Attribut X-GM-RAW übergeben werden, werden auf dieselbe Weise interpretiert wie in der Gmail-Weboberfläche.

Das folgende Beispiel zeigt das Transkript eines Anrufs 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 für jede E‑Mail eine eindeutige Nachrichten-ID bereit, damit eine eindeutige Nachricht in mehreren Ordnern 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 64-Bit-Ganzzahl ohne Vorzeichen und entspricht dem Dezimaläquivalent des ID-Hexadezimalstrings, der in der Weboberfläche und der Gmail API verwendet wird.

Im Folgenden sehen Sie ein Beispiel für das Transkript eines Anrufs zum Abrufen der 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 Nachrichten-ID von Gmail zu finden. Im Folgenden finden Sie ein Beispiel für ein Transkript eines Anrufs zum Abrufen der 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 zur Verfügung, um Nachrichtengruppen 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 64-Bit-Ganzzahl ohne Vorzeichen und entspricht dem Dezimalwert des ID-Hexadezimalstrings, der in der Weboberfläche und der Gmail API verwendet wird.

Im Folgenden sehen Sie ein Beispiel für 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 UIDs von Nachrichten in einem bestimmten Thread zu finden. Im Folgenden sehen Sie ein Beispiel für ein Transkript eines Aufrufs zum Abrufen der UID 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 für IMAP-Zwecke als Ordner behandelt. Daher können Labels mit den Standard-IMAP-Befehlen CREATE, RENAME und DELETE geändert werden, die für Ordner gelten. Systemlabels, die von Gmail erstellt werden, sind reserviert und haben in der Liste der Labels das Präfix „[Gmail]“ oder „[GoogleMail]“. 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 mit dem Attribut X-GM-LABELS und dem Befehl FETCH abgerufen werden. Das Attribut wird als Liste von ASTRINGs zurückgegeben, die entsprechend in UTF-7 codiert sind. Ein ASTRING ist ein Atom oder ein String, wie in der RFC definiert.

Das Folgende ist ein Beispiel für ein Transkript eines Aufrufs zum Abrufen der 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)

Mit dem Befehl STORE in Verbindung mit dem Attribut X-GM-LABELS können Nachrichten Labels hinzugefügt werden. Hier sehen Sie ein Beispiel für ein Transkript, in dem 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 oder UIDs aller Nachrichten im Ordner mit einem bestimmten Label zu finden. Das Folgende ist ein Beispiel für ein Transkript eines Aufrufs zum Abrufen der Sequenznummern mehrerer Nachrichten mit dem Befehl SEARCH:

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

Verweise