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 le protocole IMAP.

Présentation

Gmail fournit un ensemble d'extensions IMAP permettant aux auteurs de clients IMAP de proposer une expérience plus proche 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 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.

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

Voici un exemple d'établissement de la liaison 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 indiquent au client quels dossiers sont spéciaux (par exemple, \All). La liste actuelle des dossiers spéciaux comprend les dossiers "Suivis", "Importants", "Envoyés", "Brouillons", "Courrier indésirable", "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 qui doit être ENABLEd par 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é pour la boîte de réception prioritaire de Gmail ("[Gmail]/Important").

XLIST est obsolète

La commande XLIST spécifique à Gmail a été abandonnée en 2013 au profit de la norme IMAP pour les listes à usage spécial. Nous encourageons vivement les clients à passer de XLIST à la norme du secteur pour les utilisations spéciales dès que possible. Notez que les noms d'attributs standards à usage spécial sont similaires, mais pas identiques aux anciens noms d'attributs XLIST.

Extension de la commande SEARCH: X-GM-RAW

Pour permettre d'accéder à 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 à chaque e-mail, ce qui permet d'identifier un message unique dans plusieurs dossiers. Vous pouvez récupérer cet ID de message via l'attribut X-GM-MSGID de la commande FETCH. L'ID de message est un entier non signé 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 à 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 donné 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 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 thread est un entier non signé de 64 bits. Il s'agit de 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 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)

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 à des fins 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 portent le préfixe "[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é à 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 si nécessaire. Un ASTRING est un atome ou une chaîne, comme 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 à 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 et de l'attribut X-GM-LABELS. Voici un exemple de transcription montrant comment ajouter 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 avec un libellé donné. Vous trouverez ci-dessous 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