This document describes the XMPP extension where clients can query for email in their Gmail account.
Note: This extension will no longer be supported by Google XMPP servers as of July 18 2016, for API access to Gmail see the Gmail API documentation.
Table of Contents
Google Talk uses a custom extension to XMPP to enable users to query their Gmail account for emails. Because parts of the protocol are particular to Gmail and would not easily adapt to other email systems, this protocol will not be submitted as a XEP. However, you might want to enable this extension in your client to provide Gmail functionality.
Before attempting query for email, a client must first learn whether a server supports this extension by using service discovery. A client should send the following IQ stanza to discover what features the server supports.
Example 1. Client service discovery request
<iq type='get' to='gmail.com'> <query xmlns='http://jabber.org/protocol/disco#info'/> </iq>
If the server supports the Gmail extension, the reply will contain the appropriate feature, as shown here:
Example 2. Client service discovery response
<iq type='result' firstname.lastname@example.org' from='gmail.com'> <query xmlns='http://jabber.org/protocol/disco#info'> ... <feature var='google:mail:notify'/> ... </query> </iq>
To request mail information from the Google Talk server, a client sends
<query/> element qualified by the 'google:mail:notify'
Example 3. Client requests new mail
<iq type='get' email@example.com/orchard' firstname.lastname@example.org' id='mail-request-1'> <query xmlns='google:mail:notify' newer-than-time='1140638252542' newer-than-tid='11134623426430234' /> </iq>
<query/> element specifies which emails to retrieve
from Gmail. The
<query/> element defines the following
- newer-than-time (optional): The time of the oldest unread email to retrieve, in milliseconds since the UNIX epoch (00:00:00 UTC, January 1 1970). When querying for the first time, you should omit this attribute to return a set of the most recent unread mail. The sever will return only unread mail received after this time. If using this attribute, you should also use newer-than-tid for best results.
- newer-than-tid (optional): The highest thread number of messages to return, where higher numbers are more recent email threads. The server will return only threads newer than that specified by this attribute. If using this attribute, you should also use newer-than-time for best results. When querying for the first time, you should omit this value.
- q (optional): Specifies an optional search query string. This string uses the same syntax as the search box in Gmail, including supported operators. If this value is not specified, only unread messages from the inbox will be retrieved (that is, the default value for this property is "is:unread").
The response to this query is described in the next section.
In response to an email query, the server will respond with a
qualified by the 'google:mail:notify' namespace as shown here:
<iq type='result' email@example.com' firstname.lastname@example.org/orchard' id='mail-request-1'> <mailbox xmlns='google:mail:notify' result-time='1118012394209' url='http://mail.google.com/mail' total-matched='95' total-estimate='0'> <mail-thread-info tid='1172320964060972012' participation='1' messages='28' date='1118012394209' url='http://mail.google.com/mail?view=cv'> <senders> <sender name='Me' email@example.com' originator='1' /> <sender name='Benvolio' firstname.lastname@example.org' /> <sender name='Mercutio' email@example.com' unread='1'/> </senders> <labels>act1scene3</labels> <subject>Put thy rapier up.</subject> <snippet>Ay, ay, a scratch, a scratch; marry, 'tis enough. Where is my page? Go, villain, fetch...</snippet> </mail-thheheread-info> <mail-thread-info tid='1100823255310' participation='1' messages='28' date='342023456234'> ... </mail-thread-info> </mailbox> </iq>
The following table describes the elements and attributes in a query response.
|Element or Attribute||Description|
|<mailbox>||Outer wrapper element for all email information.|
|result-time||The time these results were generated, in milliseconds since the UNIX epoch. This value should be cached and sent as the newer-than-time attribute in the next email query.|
|total-matched||The number of emails that matched the q attribute search string in the email query, or the number of unread emails if no query was specified. If total-estimate is 1, this will be just an estimate of the number of emails retrieved.|
|total-estimate||A number indicating whether total-matched is just an estimate: 1 indicates it is; 0 or omitted indicates that it is not.|
|url||The URL of the Gmail inbox.|
|<mail-thread-info>||Element that wraps an email thread.|
|tid||The thread id of this thread.|
|participation||A number indicating the user's participation level in this thread: 0 indicates that the user has not participated; 1 indicates that the user is one of many recipients listed in the thread; 2 indicates that the user is the sole recipient for messages in this thread.|
|messages||The number of messages in the thread.|
|date||A timestamp of the most recent message, in milliseconds since the UNIX epoch.|
|url||The URL linking to this thread|
|<senders>||Contains one or more
|<sender>||Describes a single email.|
|address||The email address of the sender.|
|name||The display name of the sender.|
|originator||A number indicating whether this sender originated this thread: 1 means that this person originated this thread; 0 or omitted means that another person originated this thread.|
|unread||A number indicating whether or not the thread includes an unread message: 1 means yes; 0 or omitted means no.|
|<labels>||A tag that contains a pipe ('|') delimited list of labels applied to this thread.|
|<subject>||The subject of this email.|
|<snippet>||A snippet from the body of the email. This must be HTML-encoded.|
Extensibility is one of the greatest strengths of XMPP, the IETF standard protocol on which Google Talk is built. While XMPP itself defines a bare set of features, the protocol encourages third parties to develop their own extensions. During the development of Google Talk, we found it useful to define extensions to implement features not already found in XMPP or any of its currently defined extensions.The protocol defined in this document is currently used by the Google Talk clients and servers. However, note that it is not currently part of a proposed standardized extension, and therefore may change as we work to standardize these features.