Ce document décrit les extensions IMAP fournies par Gmail et explique comment les développeurs peuvent les utiliser. Ce document part du principe que vous connaissez le protocole IMAP.
Présentation
Gmail fournit un ensemble d'extensions IMAP permettant aux auteurs de clients IMAP d'offrir une expérience semblable à Gmail via IMAP. Les développeurs qui intègrent les fonctionnalités Gmail dans leurs applications Web ou mobiles peuvent utiliser à la place l'API Gmail RESTful.
Ces extensions peuvent être utilisées pour l'accès à Gmail via le protocole IMAP standard ou par le protocole OAuth.
Vérifier la présence d'extensions
Gmail mentionne sa compatibilité avec les extensions dans sa réponse à la commande CAPABILITY
. La compatibilité des extensions dans ce document est indiquée par la présence de X-GM-EXT-1
dans la liste des fonctionnalités compatibles.
Nous recommandons vivement aux clients de s'annoncer eux-mêmes à l'aide de la commande d'ID IMAP (RFC 2971) et d'inclure une adresse de contact comme solution de secours au cas où des modifications de ces extensions seraient nécessaires.
Voici un exemple de handshake et d'utilisation de la commande CAPABILITY
sur le point de terminaison IMAP de 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
Extension à usage spécial de la commande LIST
Gmail est compatible avec l'extension IMAP LIST pour les boîtes aux lettres à usage spécial, qui fournit de nouveaux attributs pour les dossiers spéciaux. Ces attributs permettent au client de savoir quels dossiers sont spéciaux (par exemple, \All
). Cette liste comprend actuellement les dossiers spéciaux suivants : "Suivis", "Importants", "Éléments envoyés", "Brouillons", "Spam", "Tous les messages" et "Corbeille". Toutes les réponses LIST
contiennent ces attributs à usage spécial. Il ne s'agit pas d'une nouvelle CAPABILITY
, ni d'un élément devant être ENABLEd
pour les clients.
Voici un exemple de transcription d'un appel à 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
La réponse suit la norme d'utilisation spéciale avec un attribut \Important
supplémentaire ajouté à la boîte de réception Prioritaire de Gmail (par exemple, "[Gmail]/Important"
).
XLIST est obsolète
La commande XLIST
spécifique à Gmail a été abandonnée en 2013 au profit de la commande IMAP Special-Use List Standard. Nous encourageons vivement les clients à passer de XLIST
à la norme du secteur "Usage spécial" dès que possible. Notez que les noms d'attributs standards à usage spécial sont semblables aux anciens noms d'attributs XLIST
, mais pas identiques.
Extension de la commande SEARCH: X-GM-RAW
Pour permettre l'accès à la syntaxe de recherche complète de Gmail, Gmail fournit l'attribut de recherche X-GM-RAW
. Les arguments transmis avec l'attribut X-GM-RAW
lors de l'exécution des commandes SEARCH
ou UID SEARCH
seront interprétés de la même manière que dans l'interface Web de Gmail.
Voici un exemple de transcription d'un appel à SEARCH
à l'aide de l'attribut X-GM-RAW
:
a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)
Accès à l'ID de message unique de Gmail: X-GM-MSGID
Gmail fournit un ID de message unique pour chaque e-mail, ce qui permet d'identifier un message unique dans plusieurs dossiers. La récupération de cet ID de message est possible via l'attribut X-GM-MSGID
de la commande FETCH
. L'ID du message est un entier non signé de 64 bits. Il s'agit de l'équivalent décimal de la chaîne hexadécimale utilisée dans l'interface Web et l'API Gmail.
Voici un exemple de transcription d'un appel permettant de récupérer le X-GM-MSGID
d'un message à l'aide de la commande FETCH
:
a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)
L'attribut X-GM-MSGID
peut également être utilisé dans les commandes SEARCH
ou UID SEARCH
pour trouver les numéros de séquence ou UID
d'un message en fonction de l'ID de message de Gmail. Voici un exemple de transcription d'un appel permettant de récupérer le UID
d'un message à l'aide de la commande UID SEARCH
:
a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)
Accès au fil de discussion Gmail associé à l'ID: X-GM-THRID
Gmail fournit un ID de fil de discussion pour associer des groupes de messages de la même manière que dans l'interface Web de Gmail. La récupération de cet ID de thread est possible via l'attribut X-GM-THRID
de la commande FETCH
. L'ID de thread est un entier non signé de 64 bits. Il s'agit de l'équivalent décimal de la chaîne hexadécimale utilisée dans l'interface Web et l'API Gmail.
Voici un exemple de transcription d'un appel permettant de récupérer le X-GM-THRID
de plusieurs messages (en deux threads) à l'aide de la commande 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)
Vous pouvez également utiliser l'attribut X-GM-THRID
dans les commandes SEARCH
ou UID SEARCH
pour trouver les numéros de séquence ou les UID
des messages d'un fil de discussion donné. Voici un exemple de transcription d'un appel permettant de récupérer les UID
de plusieurs messages à l'aide de la commande UID SEARCH
:
a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)
Accès aux libellés Gmail: X-GM-LABELS
Gmail considère les libellés comme des dossiers dans le cadre du protocole IMAP. Vous pouvez donc modifier les libellés à l'aide des commandes IMAP standards, CREATE
, RENAME
et DELETE
, qui agissent sur les dossiers. Les libellés système, qui sont des libellés créés par Gmail, sont réservés et précédés de "[Gmail]" ou "[GoogleMail]" dans la liste des libellés. Utilisez la commande XLIST
pour obtenir la liste complète des libellés d'une boîte aux lettres.
Vous pouvez récupérer les libellés d'un message donné en utilisant l'attribut X-GM-LABELS
avec la commande FETCH
. L'attribut est renvoyé sous la forme d'une liste de ASTRING
s, encodés au format UTF-7 le cas échéant. Un ASTRING
est un atom ou une chaîne, comme défini par le document RFC.
Voici un exemple de transcription d'un appel permettant de récupérer les X-GM-LABELS
de plusieurs messages à l'aide de la commande 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)
Vous pouvez ajouter des libellés à un message à l'aide de la commande STORE
conjointement avec l'attribut X-GM-LABELS
. Voici un exemple de transcription illustrant l'ajout d'un libellé à un message:
a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)
Vous pouvez également utiliser l'attribut X-GM-LABELS
dans les commandes SEARCH
ou UID SEARCH
pour trouver les numéros de séquence ou les UID
de tous les messages du dossier associés à un libellé donné. Voici un exemple de transcription d'un appel permettant de récupérer les numéros de séquence de plusieurs messages à l'aide de la commande SEARCH
:
a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)
Références
- IMAP: RFC 3501: PROTOCOLE D'ACCÈS AUX MESSAGES INTERNET – VERSION 4rev1
- ID IMAP: RFC 2971: IMAP4 ID EXTENSION
- IMAP à usage spécial: RFC 6154: Extension de liste IMAP pour les boîtes aux lettres à usage spécifique