Extensions IMAP

Ce document décrit les extensions IMAP fournies par Gmail et la façon dont les développeurs peuvent les utiliser. Dans ce document, nous partons du principe que vous connaissez bien le protocole IMAP.

Présentation

Gmail fournit un ensemble d'extensions IMAP pour permettre aux auteurs de clients IMAP d'offrir une expérience plus semblable à celle de Gmail via IMAP. Les développeurs qui intègrent des fonctionnalités Gmail à leurs applications Web ou mobiles peuvent préférer utiliser l'API Gmail RESTful.

Les extensions peuvent être utilisées pour accéder à Gmail via le protocole IMAP standard ou pour se connecter via OAuth.

Vérifier la présence d'extensions

Gmail indique la 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.

Il est vivement recommandé aux clients de s'annoncer avec la commande IMAP ID (RFC 2971) et d'inclure une adresse de contact en cas de modification de ces extensions.

Voici un exemple de handshake et d'utilisation de la commande CAPABILITY sur le point de terminaison IMAP 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). La liste actuelle des dossiers spéciaux comprend les éléments suivants : "Suivis", "Important", "É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'un nouveau CAPABILITY ni d'un élément que les clients doivent ENABLEd.

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é pour la boîte de réception prioritaire de Gmail (c'est-à-dire "[Gmail]/Important").

XLIST est obsolète

La commande XLIST spécifique à Gmail a été abandonnée en 2013 au profit de la norme IMAP Special-Use List. Nous encourageons vivement les clients à migrer de XLIST vers le standard de l'industrie à usage spécial dès que possible. Notez que les noms des attributs standards à usage spécial sont semblables, mais pas identiques à ceux de l'ancien attribut XLIST.

Extension de la commande SEARCH : X-GM-RAW

Pour permettre l'accès à la syntaxe de recherche Gmail complète, 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 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 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 de message est un entier non signé de 64 bits. Il s'agit de l'équivalent décimal de la chaîne hexadécimale de l'ID 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 avec 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 le UID d'un message donné à partir de son ID 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 à l'ID du fil de discussion Gmail : 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 fil de discussion est un entier non signé de 64 bits. Il s'agit de l'équivalent décimal de la chaîne hexadécimale de l'ID utilisée dans l'interface Web et l'API Gmail.

Voici un exemple de transcription d'un appel pour récupérer le X-GM-THRID de plusieurs messages (dans deux fils de discussion) avec 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)

L'attribut X-GM-THRID peut également être utilisé dans les commandes SEARCH ou UID SEARCH pour trouver les numéros de séquence ou les UID des messages d'un thread 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 traite les libellés comme des dossiers pour IMAP. Par conséquent, les libellés peuvent être modifiés à l'aide des commandes IMAP standards CREATE, RENAME et DELETE, qui agissent sur les dossiers. Les libellés système, qui sont 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.

Les libellés d'un message donné peuvent être récupérés à l'aide de l'attribut X-GM-LABELS avec la commande FETCH. L'attribut est renvoyé sous la forme d'une liste de ASTRING, encodée en UTF-7, le cas échéant. Un ASTRING est un atome ou une chaîne, tel que défini par la RFC.

Voici un exemple de transcription d'un appel permettant de récupérer le X-GM-LABELS de plusieurs messages avec 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 associée à l'attribut X-GM-LABELS. Voici un exemple de transcription montrant 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)

L'attribut X-GM-LABELS peut également être utilisé dans les commandes SEARCH ou UID SEARCH pour trouver les numéros de séquence ou les UID de tous les messages du dossier portant 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