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-ähnliche Benutzeroberfläche über IMAP bereitstellen können. Entwickler, die Gmail-Funktionen in ihre Web- oder mobilen Apps einbinden, sollten stattdessen die RESTful Gmail API verwenden.

Die Erweiterungen können beim Zugriff auf Gmail über das Standard-IMAP-Protokoll oder bei der Verbindung über OAuth verwendet werden.

Prüfen, ob Erweiterungen vorhanden sind

Gmail bewirbt seinen Erweiterungssupport 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 angezeigt.

Clients sollten sich mit dem IMAP-ID-Befehl (RFC 2971) ankündigen 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 am 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 LIST-Befehls für spezielle Zwecke

Gmail unterstützt die IMAP LIST-Erweiterung für Postfächer mit spezieller Verwendung, die neue Attribute für spezielle Ordner bietet. Anhand dieser Attribute weiß der Client, welche Ordner besonders sind (z. B. \All). Die aktuelle Liste der speziellen Ordner umfasst: „Mit Stern markiert“, „Wichtig“, „Gesendet“, „Entwürfe“, „Spam“, „Alle E-Mails“ und „Papierkorb“. Alle LIST-Antworten enthalten diese Attribute für den speziellen Gebrauch. Dies ist kein neues CAPABILITY und muss von Kunden nicht ENABLEd werden.

Im Folgenden finden Sie ein Beispiel für ein Transkript eines Aufrufs von 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 den speziellen Gebrauch. Für den Gmail-Prioritätsposteingang ("[Gmail]/Important") wurde das zusätzliche Attribut \Important hinzugefügt.

XLIST wird eingestellt

Der Gmail-spezifische Befehl XLIST wurde 2013 zugunsten des IMAP-Standards für Listen mit spezieller Verwendung eingestellt. Wir empfehlen Kunden dringend, so bald wie möglich von XLIST zum Branchenstandard für den speziellen Gebrauch zu migrieren. Die Namen der Standardattribute für den speziellen Gebrauch ähneln den Namen der bisherigen XLIST-Attribute, sind aber nicht identisch.

Erweiterung des Befehls „SEARCH“: 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 die gleiche Weise wie in der Gmail-Weboberfläche interpretiert.

Im Folgenden findest du ein Beispiel für einen SEARCH-Aufruf 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 weist jeder E-Mail eine eindeutige Nachrichten-ID zu, damit eine einzelne Nachricht in mehreren Ordnern identifiziert werden kann. Das Abrufen dieser Nachrichten-ID wird über das X-GM-MSGID-Attribut des FETCH-Befehls unterstützt. Die Nachrichten-ID ist eine 64-Bit-unsignierte Ganzzahl und entspricht dem Dezimalformat des Hexadezimalstrings für die ID, der in der Weboberfläche und in der Gmail API verwendet wird.

Im Folgenden finden Sie ein Beispiel für einen Aufruf, um mit dem Befehl FETCH die X-GM-MSGID einer Nachricht abzurufen:

a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)

Das X-GM-MSGID-Attribut kann auch in den Befehlen SEARCH oder UID SEARCH verwendet werden, um die Sequenznummern oder UID einer Nachricht anhand der Nachrichten-ID in Gmail zu ermitteln. Im Folgenden finden Sie ein Beispiel für einen Aufruf, um mit dem Befehl UID SEARCH die UID einer Nachricht abzurufen:

a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)

Zugriff auf die Gmail-Thread-ID: X-GM-THRID

In Gmail wird eine Thread-ID verwendet, um Nachrichtengruppen auf die gleiche Weise wie in der Gmail-Weboberfläche zuzuordnen. Das Abrufen dieser Thread-ID wird über das X-GM-THRID-Attribut des Befehls FETCH unterstützt. Die Thread-ID ist eine 64-Bit-unsignierte Ganzzahl und entspricht dem Dezimalformat des Hexadezimalstrings für die ID, der in der Weboberfläche und in der Gmail API verwendet wird.

Im Folgenden finden Sie ein Beispiel für einen Aufruf, um mit dem Befehl FETCH die X-GM-THRID mehrerer Nachrichten (in zwei Threads) abzurufen:

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 X-GM-THRID-Attribut kann auch in den Befehlen SEARCH oder UID SEARCH verwendet werden, um die Sequenznummern oder UIDs von Nachrichten in einem bestimmten Thread zu ermitteln. Im Folgenden finden Sie ein Beispiel für einen Aufruf, um mit dem Befehl UID SEARCH die UIDs mehrerer Nachrichten abzurufen:

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-Kontext als Ordner behandelt. Labels können daher mit den Standard-IMAP-Befehlen CREATE, RENAME und DELETE geändert werden, die auf Ordner angewendet werden. Systemlabels, also von Gmail erstellte Labels, sind reserviert und haben in der Liste der Labels das Präfix „[Gmail]“ oder „[GoogleMail]“. Verwenden Sie den Befehl XLIST, um die vollständige Liste der Labels für einen Posteingang 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. Eine ASTRING ist ein Atom oder ein String, wie in der RFC definiert.

Im Folgenden finden Sie ein Beispiel für einen Aufruf, um mit dem Befehl FETCH die X-GM-LABELS mehrerer Nachrichten abzurufen:

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 Beispiel wird gezeigt, 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 oder UIDs aller Nachrichten im Ordner mit einem bestimmten Label zu ermitteln. Im Folgenden finden Sie ein Beispiel für einen Aufruf, um mit dem Befehl SEARCH die Sequenznummern mehrerer Nachrichten abzurufen:

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

Verweise