Extensions IMAP

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 ASTRINGs, 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