IMAP Extensions

This document describes the IMAP extensions provided by Gmail and how developers can use them. This document assumes familiarity with the IMAP protocol.

Overview

Gmail provides a set of IMAP extensions to allow authors of IMAP clients to provide a more Gmail-like experience through IMAP. Developers integrating Gmail features into their web or mobile apps might instead want to use the RESTful Gmail API.

You can use the extensions when accessing Gmail through the standard IMAP protocol or when connecting with OAuth.

Checking for the presence of extensions

Gmail advertises its extension support in its response to the CAPABILITY command. The presence of X-GM-EXT-1 in the list of supported capabilities indicates support for the extensions described in this document.

We strongly recommend that clients announce themselves with the IMAP ID command (RFC 2971), and include a contact address as a fallback in case changes to these extensions are required.

The following is an example handshake and use of the CAPABILITY command on the Gmail IMAP endpoint:

* 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

Special-Use extension of the LIST command

Gmail supports the IMAP LIST Extension for Special-Use Mailboxes, which provides new attributes for special folders. These attributes let the client know which folders are special, such as \All. The current list of special folders consists of: Starred, Important, Sent Items, Drafts, Spam, All Mail, and Trash. All LIST responses contain these Special-Use attributes; this is not a new CAPABILITY or something that clients must enable.

The following is an example transcript of a call to 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

The response follows the Special-Use standard with an additional \Important attribute added for Gmail's Priority Inbox (that is, "[Gmail]/Important").

XLIST is deprecated

The Gmail-specific XLIST command was deprecated in 2013 in favor of the IMAP Special-Use List Standard. We strongly encourage clients to migrate from XLIST to the Special-Use industry standard as soon as possible. Note that the Special-Use standard attribute names are similar but not identical to the legacy XLIST attribute names.

Extension of the SEARCH command: X-GM-RAW

To provide access to the full Gmail search syntax, Gmail provides the X-GM-RAW search attribute. Arguments passed with the X-GM-RAW attribute when executing the SEARCH or UID SEARCH commands are interpreted in the same manner as in the Gmail web interface.

The following is an example transcript of a call to SEARCH using the X-GM-RAW attribute:

a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)

Access to the Gmail unique message ID: X-GM-MSGID

Gmail provides a unique message ID for each email so that you can identify a unique message across multiple folders. You can retrieve this message ID using the X-GM-MSGID attribute on the FETCH command. The message ID is a 64-bit unsigned integer and is the decimal equivalent for the ID hex string used in the web interface and the Gmail API.

The following is an example transcript of a call to retrieve the X-GM-MSGID of a message with the FETCH command:

a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)

You can also use the X-GM-MSGID attribute in the SEARCH or UID SEARCH commands to find the sequence numbers or UID of a message given Gmail's message ID. The following is an example transcript of a call to retrieve the UID of a message using the UID SEARCH command:

a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)

Access to the Gmail thread ID: X-GM-THRID

Gmail provides a thread ID to associate groups of messages in the same manner as in the Gmail web interface. You can retrieve this thread ID using the X-GM-THRID attribute on the FETCH command. The thread ID is a 64-bit unsigned integer and is the decimal equivalent for the ID hex string used in the web interface and the Gmail API.

The following is an example transcript of a call to retrieve the X-GM-THRID of several messages (in two threads) with the FETCH command:

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)

You can also use the X-GM-THRID attribute in the SEARCH or UID SEARCH commands to find the sequence numbers or UIDs of messages in a given thread. The following is an example transcript of a call to retrieve the UIDs of several messages using the UID SEARCH command:

a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)

Access to Gmail labels: X-GM-LABELS

Gmail treats labels as folders for the purposes of IMAP. As such, you can modify labels using the standard IMAP commands that act on folders: CREATE, RENAME, and DELETE. System labels, which are labels created by Gmail, are reserved and prefixed by "[Gmail]" or "[GoogleMail]" in the list of labels. Use the LIST command to get the entire list of labels for a mailbox.

You can retrieve the labels for a given message using the X-GM-LABELS attribute with the FETCH command. The attribute is returned as a list of ASTRINGs, encoded in UTF-7 as appropriate. An ASTRING is an atom or a string as defined by the RFC.

The following is an example transcript of a call to retrieve the X-GM-LABELS of several messages with the FETCH command:

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)

You can add labels to a message using the STORE command in conjunction with the X-GM-LABELS attribute. The following is an example transcript demonstrating how to add a label to a message:

a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)

You can also use the X-GM-LABELS attribute in the SEARCH or UID SEARCH commands to find the sequence numbers or UIDs of all messages in the folder with a given label. The following is an example transcript of a call to retrieve the sequence numbers of several messages using the SEARCH command:

a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)

References