Gmail Notifications

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

Introduction

Determining Server Support

Querying for Email

Email Query Response

New Email Notifications

About Google Talk Extensions

Introduction

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.

Determining Server Support

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' to='romeo@gmail.com' from='gmail.com'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='google:mail:notify'/>
    ...
  </query>
</iq>

Querying for Email

To request mail information from the Google Talk server, a client sends a <query/> element qualified by the 'google:mail:notify' namespace.

Example 3. Client requests new mail

<iq type='get'
    from='romeo@gmail.com/orchard'	
    to='romeo@gmail.com'
    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."

The <query/> element specifies which emails to retrieve from Gmail. The <query/> element defines the following attributes.

• 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.

Email Query Response

In response to an email query, the server will respond with a <mailbox/> element qualified by the 'google:mail:notify' namespace as shown here:

<iq type='result'
    from='romeo@gmail.com'
    to='romeo@gmail.com/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' address='romeo@gmail.com' originator='1' />
        <sender name='Benvolio' address='benvolio@gmail.com' />
        <sender name='Mercutio' address='mercutio@gmail.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> elements, each of which describes an email.
<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.

New Email Notifications

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 <new-mail/> element 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'
    from='romeo@gmail.com'
    to='romeo@gmail.com/orchard'
    id='mail-request-2'>
  <new-mail xmlns='google:mail:notify' />
</iq>

The client should respond with with an <iq/> stanza 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'
    from='romeo@gmail.com'
    to='romeo@gmail.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).

About Google Talk Extensions

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.