We announced a new communications product, Hangouts, in May 2013. Hangouts will replace Google Talk and does not support XMPP.

Gmail Message Querying

This document describes the XMPP extension where clients can query for 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
  • About Google Talk Extensions
  • Introduction

    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.

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

    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.