This document describes the XMPP extension that notifies clients about email in their Gmail account.
Note: This extension is not intended to become a standard and is subject to change.
Table of Contents
Google Talk uses a custom extension to XMPP to enable users to query their Gmail account for emails, and receive notifications when a new message arrives. 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>
The first time this request is sent, in addition to returning messages that fulfill the query, the server will also subscribe the client to receive notifications when new mail is received, as documented below in "Email Notifications."
<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.|
When the user's Gmail account receives new email, if a client has previously
sent a new email query to the server, the server will send a notification
to the client. This notification includes a
qualified by the 'google:mail:notify' namespace, but it does not include
any information about the email.
Example 5. Server reports new mail
<iq type='set' firstname.lastname@example.org' email@example.com/orchard' id='mail-request-2'> <new-mail xmlns='google:mail:notify' /> </iq>
The client should respond with with an
of type 'result' as defined in section 9.2.3 of the XMPP-core
specification as shown here:
Example 6. Client returns success
<iq type='result' firstname.lastname@example.org' email@example.com/orchard' id='mail-request-2' />
The client should query the server as described previously to get accurate information about new email before alerting the user. This is because not all alerts indicate valid mail (for example, filtered junk email might generate an alert, but would not be returned by a query).
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.