Extensions IMAP

Ce document décrit les extensions IMAP fournies par Gmail et la manière dont les développeurs peuvent les utiliser. Il suppose que vous connaissez 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 dans leurs applications Web ou mobiles peuvent préférer utiliser l'API RESTful Gmail.

Les extensions peuvent être utilisées lorsque vous accédez à Gmail via le protocole IMAP standard ou lorsque vous vous connectez via OAuth.

Vérifier la présence d'extensions

Gmail annonce la prise en charge des extensions dans sa réponse à la commande CAPABILITY. La prise en charge 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 avec la commande IMAP ID (RFC 2971) et d'inclure une adresse de contact de secours au cas où des modifications seraient nécessaires pour 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 Special-Use de la commande LIST

Gmail est compatible avec l'extension IMAP LIST pour les boîtes aux lettres Special-Use, 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 : Messages suivis, Important, Éléments envoyés, Brouillons, Spam, Tous les messages et Corbeille. Toutes les réponses LIST contiennent ces attributs Special-Use. Il ne s'agit pas d'une nouvelle 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 Special-Use 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 la norme Special-Use du secteur dès que possible. Notez que les noms d'attributs de la norme Special-Use sont similaires, mais pas identiques aux noms d'attributs XLIST hérités.

Extension de la commande SEARCH : X-GM-RAW

Pour fournir un 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 sont 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 afin qu'un message unique puisse être identifié dans plusieurs dossiers. La récupération de cet ID de message est compatible avec l'attribut X-GM-MSGID de la commande FETCH. L'ID de message est un entier non signé de 64 bits et correspond à l'équivalent décimal de la chaîne hexadécimale d'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é à l'aide de l'ID de message 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 de 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 Gmail. La récupération de cet ID de fil de discussion est compatible avec l'attribut X-GM-THRID de la commande FETCH. L'ID de fil de discussion est un entier non signé de 64 bits et correspond à l'équivalent décimal de la chaîne hexadécimale d'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-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 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 traite les libellés comme des dossiers aux fins d'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 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.

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 d'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 les 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)

Des libellés peuvent être ajouté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