IMAP-Erweiterungen

In diesem Dokument werden die von Gmail bereitgestellten IMAP-Erweiterungen und die Verwendungsmöglichkeiten für 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 Mobil-Apps einbinden möchten, sollten stattdessen die RESTful Gmail API verwenden.

Sie können die Erweiterungen verwenden, wenn Sie über das Standard-IMAP-Protokoll auf Gmail zugreifen oder eine Verbindung mit OAuth herstellen.

Prüfen, ob Erweiterungen vorhanden sind

Gmail bewirbt die Unterstützung von Erweiterungen in der Antwort auf den Befehl CAPABILITY. Das Vorhandensein von X-GM-EXT-1 in der Liste der unterstützten Funktionen weist auf die Unterstützung der in diesem Dokument beschriebenen Erweiterungen hin.

Wir empfehlen dringend, dass sich Clients mit dem IMAP-Befehl ID (RFC 2971) anmelden und eine Kontaktadresse als Fallback angeben, falls Änderungen an diesen Erweiterungen erforderlich sind.

Das Folgende ist ein Beispiel für den Handshake und die Verwendung des CAPABILITY-Befehls 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. Mit diesen Attributen wird dem Client mitgeteilt, welche Ordner speziell sind, z. B. \All. Die aktuelle Liste der speziellen Ordner umfasst: „Markiert“, „Wichtig“, „Gesendete Elemente“, „Entwürfe“, „Spam“, „Alle E-Mails“ und „Papierkorb“. Alle LIST-Antworten enthalten diese Attribute für die spezielle Verwendung. Das ist keine neue CAPABILITY und muss nicht von Clients aktiviert 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. Für den sortierten Posteingang von Gmail wurde ein zusätzliches \Important-Attribut hinzugefügt ("[Gmail]/Important").

XLIST wird nicht mehr unterstützt

Der Gmail-spezifische Befehl XLIST wurde 2013 zugunsten des IMAP Special-Use List Standard eingestellt. Wir empfehlen Kunden dringend, so schnell wie möglich von XLIST auf den Branchenstandard für die spezielle Verwendung zu migrieren. Die Namen der Attribute für die Standardnutzung 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 mit dem Attribut X-GM-RAW übergeben werden, werden auf dieselbe Weise interpretiert wie in der Gmail-Weboberfläche.

Das Folgende ist ein Beispiel für 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 für jede E‑Mail eine eindeutige Nachrichten-ID bereit, damit Sie eine bestimmte Nachricht in mehreren Ordnern identifizieren können. Sie können diese Nachrichten-ID mit dem Attribut X-GM-MSGID des Befehls FETCH abrufen. Die Nachrichten-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.

Das folgende Beispiel zeigt 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)

Sie können das Attribut X-GM-MSGID auch in den Befehlen SEARCH oder UID SEARCH verwenden, um die Sequenznummern oder UID einer Nachricht anhand der Gmail-Nachrichten-ID zu finden. Im Folgenden sehen Sie ein Beispiel für ein Transkript eines Aufrufs 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. Sie können diese Thread-ID mit dem Attribut X-GM-THRID des Befehls FETCH abrufen. 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.

Das folgende Beispiel zeigt das 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)

Sie können das Attribut X-GM-THRID auch in den Befehlen SEARCH oder UID SEARCH verwenden, um die Sequenznummern oder UIDs von Nachrichten in einem bestimmten Thread zu finden. Im Folgenden sehen Sie ein Beispiel für ein Transkript eines Anrufs 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 für IMAP-Zwecke als Ordner behandelt. Daher können Sie Labels mit den Standard-IMAP-Befehlen für Ordner ändern: CREATE, RENAME und DELETE. 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 LIST, um die gesamte Liste der Labels für ein Postfach abzurufen.

Mit dem Attribut X-GM-LABELS und dem Befehl FETCH können Sie die Labels für eine bestimmte Nachricht abrufen. 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 im RFC definiert.

Das folgende Beispiel zeigt 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 Sie einer Nachricht Labels hinzufügen. Hier sehen Sie ein Beispiel für ein Transkript, in dem gezeigt wird, wie Sie einer Nachricht ein Label hinzufügen:

a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)

Sie können auch das Attribut X-GM-LABELS in den Befehlen SEARCH oder UID SEARCH verwenden, 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