Email Settings API Developer's Guide

Contents

Overview

Google Apps allows website administrators to offer their users co-branded versions of a variety of personalized Google applications, such as Google mail.

This document describes the Email Settings API which enables Google partners to programmatically manipulate most user-level Google Mail settings.

API Operations

The Email Settings API supports the following operations:

• The creation of the following entities for a user's account:
  • Labels
  • Filters
  • Send-as Aliases
• Updating the following settings for a user's account:
  • Web clip settings
  • Forwarding settings
  • POP settings
  • IMAP settings
  • Vacation Responder settings
  • Signature
  • Language settings
  • Many "General" settings such as Maximum Page Size, Shortcuts, Arrow Usage, Snippets, and Unicode activation

To use the Email Settings API, you need to send an HTTP request to a specific URL that represents a particular user's setting. The request will be one of two types—either a POST request that performs a create operation, for creating new labels, filters, or send-as aliases—or a PUT request that performs an update operation, for changing any of the updatable settings listed above. Each URL will either support a create operation, or an update operation. Retrieve and delete operations are currently not supported.

The body of the PUT or the POST requests will contain XML that describes either the entity to be created, or the new values that the settings should take. Google will verify that all requests contain valid XML, include all required data fields, and meet the authentication requirements given below.

API Authentication

All of your API requests must be sent over HTTPS. Each API request that you send needs to contain an authentication token, which Google will use to authorize access to the operation specified in the API request. Authentication tokens are only available to users who have administrative rights in your domain, and those tokens only authorize operations within your domain.

The ClientLogin Interface provides additional information about programmatically logging users into their accounts.

To obtain an authentication token, submit an HTTP POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The following guidelines apply to the request:

• The POST body needs to include a string in the following format:

  &Email=<email_address>&Passwd=<password>&accountType=HOSTED&service=apps
  

  You will need to make the following changes to this string:

  1. Replace the string <email_address> with the email address for your admin account.

  2. Replace the string <password> with the password for that account.

• The email address and password values must be URL-encoded. For example, the URL-encoded form of the email address apps.test.account@example.com is apps%2Etest%2Eaccount%40example%2Ecom.

• The POST request must specify the value application/x-www-form-urlencoded for the Content-Type header.

Google will return a response containing your authentication token in response to your POST request. The authentication token will be the Auth value on that page, and you need to extract the token from the page. When you submit an API request, you must set the Content-type and Authorization headers as shown in the example below.

  Content-type: application/atom+xml
  Authorization: GoogleLogin auth=your-authentication-token

Note: Authentication tokens expire after 24 hours. As such, you will need to submit a request to the above URL at least once every 24 hours. We recommend that you keep the token in memory rather than writing it to a file.

Sample Code for Obtaining an Authentication Token

The following Perl script demonstrates how to make an HTTP POST request for an authentication token.

#! /usr/bin/perl -w

use strict;
use LWP::UserAgent;

# Create an LWP object to make the HTTP POST request
my $lwp_object = LWP::UserAgent->new;

# Define the URL to submit the request to
my $url = 'https://www.google.com/accounts/ClientLogin';

# Submit the request with values for the Email, Passwd,
# accountType and service variables.
my $response = $lwp_object->post( $url,
            [ 'accountType' => 'HOSTED',
              'Email' => 'admin_email@example.com',
              'Passwd' => 'admin_password',
              'service' => 'apps'
            ]
);

die "$url error: ", $response->status_line unless $response->is_success;

# Extract the authentication token from the response
my $auth_token;
foreach my $line (split/\n/, $response->content) {
    if ($line =~ m/^Auth=(.+)$/) {
        $auth_token = $1;
        last;
    }
}

print "authentication token is $auth_token\n";

Note that to use this code, you need to replace the Email and Passwd values with the email address and password for your hosted admin account.

Using the Email Settings API

In order to change a user's settings with the Email Settings API, the administrator must make an HTTP request (either a POST or a PUT) to a certain URL, with an XML atom entry in the body of the request. The following sections explain the format of the request URL as well as the concept of an XML atom entry; however, for each setting you want to change, consult the specific section in this document for the exact properties to set.

Email Settings API HTTP Format

The first step to changing a user's settings with the Email Settings API is to find the URL for the setting you plan to change, and whether it is accessed with a create request (a POST) or an update request (a PUT).

The example below shows the format URLs take in the Email Settings API. This particular example adds a new Google Mail filter for a user in your domain. Variables are highlighted in bold, blue text.

https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/{settingID}

The following variables should be filled in to complete the request:

• domain: The domain of the email address you are creating a filter for.
• username: The username of the user where the filter is to be created.
• settingID: This last part of the URI indicates the setting to be changed.

The following table shows different settings which can be changed, their settingIDs, and whether they support POST (create requests) or PUT (update requests).

For example, to create a filter for the user alice on the example.com domain, you would submit an HTTP POST request to the following URL:

https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/alice/filter

XML Request Format

The second step is to find the format that the XML body of the request must take. The XML document is a Google Data Atom entry. The <entry> must contain at least one <apps:property> tag. Each <apps:property> tag has a name and a value attribute which describe how the email settings are to be changed— such as describing a filter to be created, or the new values that forwarding settings should take.

The following XML example describes a fairly straightforward filter that will archive every email from the example.com domain with project 1 in the subject header.

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
xmlns:apps='http://schemas.example.com/apps/2006'>
  <apps:property name='from' value='example.com'/>
  <apps:property name='subject' value='project 1'/>
  <apps:property name='shouldArchive' value='true'/>
</atom:entry>

This example does not show all of the possibilities for creating filters, or explain how to change any of the other settings. The following sections explain in full details the required XML format for each settings operation.

XML Responses

If the filter was created sucessfully, the Email Settings API will return an HTTP 201 response indicating a successful creation. The body of the response will echo back the create or update request.

However, if there was an error due to an invalid API request, an HTTP error response is returned. The list of possible HTTP response codes are listed at http://code.google.com/apis/gdata/reference.html#http-status-codes.

If there was an error that occurred during the creation of the filter, an XML error response is returned. The list of possible XML response codes are listed at http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html#google_apps_tag_error.

The following is an example of an error that occurred during the creation of a filter:

400 BAD REQUEST

<?xml version="1.0" encoding="UTF-8"?>

<AppsForYourDomainErrors>
  <error errorCode="1301" reason="EntityDoesNotExist"
            invalidInput="your-invalid-input"/>
</AppsForYourDomainErrors>

Common Problems

There are a few potential sources of errors that system administrators should consider when using the Email Settings API.

• If you are changing settings for a just-provisioned account, you should wait at least one second between the two API calls. This insures that the email account exists before the attempt is made to change the user's email settings.
• There are limits to the values that many properties can take. For instance, some only take true/false, others only valid email addresses or up to a certain number of characters; and for some properties, there are reserved values which cannot be used.
• Three of the settings - forwarding, POP and IMAP—are only made active once the user agrees to Google's terms of service. Attempting to change these settings before the user agrees to the terms of service will result in the updated settings being stored, but not made active. Once the user agrees to the terms, then the stored settings will be made active. This prevents users from using these features until they have agreed to the terms, but does not prevent administrators from changing the settings on these features before they have been made active.
• To see some common errors, along with the output produced to help diagnose them, see the common errors section of this guide.

Creating a Label

Creating labels in Google Mail is accomplished with a POST request to the following URL:

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/label

The following table shows the only property to be set when creating a label.

• Label names must not conflict with reserved label names in Google Mail, which in English include inbox, unread, drafts, sent, chat, muted, spam, trash, popped, and contactcsv. In addition to this, label names must not conflict with reserved label names in any language which Google Mail is available in. This is by design, as it prevents users from confusing messages in the inbox with messages labelled inbox, regardless of their display language.

Label Creation Examples

Example 1

• The username is ben.
• The label "status updates" will be created for Ben.

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/label

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="label" value="status updates" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.createLabel(users, "status updates");

Creating a Filter

Creating a Google Mail filter is accomplished with a POST request to the following URL:

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/filter

The following two tables shows the properties to be set when creating a filter. The first table shows what you can filter on, the second what action you can take, and their corresponding XML attributes. At least one property from the first table and one from the second table must be set.

Filter Criteria Properties

*Note that when specifying the subjects or the words for the filter to match, many non-alphanumeric characters cannot be used. Disallowed characters include square brackets, parentheses, currency symbols, the ampersand, the pound sign and asterisks.

• Filter criteria values are case insensitive. JaneDoe@example.com is filtered the same as janedoe@example.com.
• Boolean operators are available for creating filters. See the following Google Mail Help Center topic for more information: http://mail.google.com/support/bin/answer.py?answer=8931.

Filter Action Properties

• Filters can be created for labels that already exist - the created filter will simply label incoming mail with the existing label.
• Note that certain label names are reserved - see the labels section above.

Filter Creation Examples

Example 1

• The username is liz.
• The email is from Alice's other email account, alice@gmail.com.
• The email's subject contains the string project proposal.
• Emails filtered by this criteria are marked as read.

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/filter

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="from" value="alice@gmail.com" />
    <apps:property name="hasTheWord" value="project proposal" />
    <apps:property name="shouldMarkAsRead" value="true" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.createLabel(users, 
                    "alice@gmail.com",  // from
                    "",                 // to
                    "",                 // subject
                    "project proposal", // hasTheWord
                    "",                 // doesNotHaveTheWord
                    false,              // hasAttachment
                    true,               // shouldMarkAsRead
                    false,              // shouldArchive
                    "");                // label

Example 2

• The username is ben.
• The email is sent to announcements@example.com.
• Emails filtered by this criteria are labeled announcements.

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/filter

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="to" value="announcements@example.com" />
    <apps:property name="label" value="announcements" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.createLabel(users, 
                    "",                          // from
                    "announcements@example.com", // to
                    "",                          // subject
                    "",                          // hasTheWord
                    "",                          // doesNotHaveTheWord
                    false,                       // hasAttachment
                    false,                       // shouldMarkAsRead
                    false,                       // shouldArchive
                    "announcements");            // label

Creating a Send-as Alias

Creating a Google Mail send-as alias is accomplished with a POST request to the following URL:

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/sendas

The following table shows the properties to be set when creating a send-as Alias.

Send-As Alias Creation Examples

Example 1

• The username is liz.
• The send-as alias will allow Liz to send as Sales, with the email address sales@example.com.
• This alias will be selected for Liz by default.

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/sendas

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="name" value="Sales" />
    <apps:property name="address" value="sales@example.com" />
    <apps:property name="makeDefault" value="true" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.createSendAs(users,
                     "Sales",             // name
                     "sales@example.com", // address
                     true);               // makeDefault

Example 2

• The username is ben.
• The send-as alias will allow Ben to send as Support with the email address support@example.com.
• The reply-to will be set to another address, b.smith@gmail.com.

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/sendas

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="name" value="Support" />
    <apps:property name="address" value="support@example.com" />
    <apps:property name="replyTo" value="b.smith@gmail.com" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.createSendAs(users,
                     "Support",             // name
                     "support@example.com", // address
                     false);                // makeDefault

Updating Web Clip Settings

Updating Google Mail web clip settings is accomplished with a PUT request to the following URL:

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/webclip

The following table shows the only property to be set when updating web clip settings.

Web Clip Settings Examples

Example 1

• The username is ben.
• Web clip service is to be enabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/webclip

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="true" />
</atom:entry>

Example 2

• The username is ben.
• Web clip service is to be disabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/webclip

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="false" />
</atom:entry>

Updating Forwarding Settings

Updating Google Mail Forwarding settings is accomplished with a PUT request to the following URL:

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/forwarding

Note: Although an administrator can change these properties at any time, the changed settings will only take effect once the user has agreed to the terms of service.

The following table shows the properties to be set when updating forwarding settings. Note that all properties are required to enable forwarding settings (but setting enable to false is enough to disable).

Forwarding Settings Examples

Example 1

• The username is liz.
• All emails are to be forwarded to another address, alice@example.net.
• No further action is to be taken - the forwarded emails are to be kept in the inbox.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/forwarding

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="true" />
    <apps:property name="forwardTo" value="alice@example.net" />
    <apps:property name="action" value="KEEP" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changeForward(users,
                      true,                // enable
                      "alice@example.com", // forwardTo
                      "KEEP");             // action

Example 2

• The username is ben.
• All emails are to be forwarded to another address: b.smith@gmail.com.
• Once forwarded, the emails are to be archived.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/forwarding

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="true" />
    <apps:property name="forwardTo" value="b.smith@gmail.com" />
    <apps:property name="action" value="ARCHIVE" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.changeForward(users,
                      true,                // enable
                      "b.smith@gmail.com", // forwardTo
                      "ARCHIVE");          // action

Example 3

• The username is liz.
• Emails are no longer to be forwarded to another address.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/forwarding

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="false" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changeForward(users,
                      false, // enable
                      "",    // forwardTo
                      "");   // action

Updating POP Settings

Updating Google Mail POP settings is accomplished with a PUT request to the following URL:

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/pop

Note: Although an administrator can change these properties at any time, the changed settings will only take effect once the user has agreed to the terms of service.

The following table shows the properties to be set when updating POP settings. Note that all properties are required to enable POP settings (but setting enable to false is enough to disable).

POP Settings Examples

Example 1

• The username is liz.
• POP access is to be enabled from now on.
• Emails accessed with POP are to be kept in the inbox.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/pop

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="true" />
    <apps:property name="enableFor" value="MAIL_FROM_NOW_ON" />
    <apps:property name="action" value="KEEP" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changePop(users,
                  true,               // enable
                  "MAIL_FROM_NOW_ON", // enableFor
                  "KEEP");            // action

Example 2

• The username is ben.
• POP access is to be enabled for all mail, not just mail that arrives from now on.
• Once accessed with POP, the emails are to be deleted (moved into trash, which is emptied over time).

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/pop

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="true" />
    <apps:property name="enableFor" value="ALL_MAIL" />
    <apps:property name="action" value="DELETE" />
</atom:entry>
<

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.changePop(users,
                  true,       // enable
                  "ALL_MAIL", // enableFor
                  "DELETE");  // action

Example 3

• The username is liz.
• POP access is to be disabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/pop

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="false" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changePop(users,
                  false, // enable
                  "",    // enableFor
                  "");   // action

Updating IMAP Settings

Updating Google Mail IMAP settings is accomplished with a PUT request to the following URL:

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/imap

Note: Although an administrator can change these properties at any time, the changed settings will only take effect once the user has agreed to the terms of service.

The following table shows the only property to be set when updating IMAP settings.

IMAP Settings Examples

Example 1

• The username is ben.
• IMAP access is to be enabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/imap

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="true" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.changeImap(users, true); // enable

Example 2

• The username is ben.
• IMAP access is to be disabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/imap

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="false" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.changeImap(users, false); // enable

Updating Vacation-Responder Settings

Updating Google Mail Vacation-responder settings is accomplished with a PUT request to the following URL:

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/vacation

The following table shows the properties to be set when updating Vacation-responder settings.

Vacation-Responder Settings Examples

Example 1

• The username is ben.
• The vacation-responder is to be enabled.
• The autoreply will only be sent to those people who are on Ben's list of contacts.
• Note that all strings have been HTML encoded where necessary.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/ben/vacation

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="true" />
    <apps:property name="subject" value="Out of office" />
    <apps:property name="message" value="If it&#39;s urgent you can contact me on 555-5555." />
    <apps:property name="contactsOnly" value="true" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.changeVacation(users,
                       true,                                                 // enable
                       "Out of office",                                      // subject
                       "If it's urgent you can contact me on 555-5555.", // message
                       true);                                                // contactOnly

Example 2

• The username is liz.
• The vacation-responder is to be disabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/vacation

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="enable" value="false" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changeVacation(users,
                       false,  // enable
                       "",     // subject
                       "",     // message
                       false); // contactOnly

Updating Signature

Updating the Google Mail signature is accomplished with a PUT request to the following URL:

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/signature

The following table shows the only property to be set when updating the signature.

Signature Examples

Example 1

• The username is liz.
• Her signature is to be set to include her name and contact details, on separate lines.
• Note that all strings have been HTML encoded where necessary.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/signature

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="signature" value="Liz Jones - (+1) 619-555-5555
Accounts Management, A&amp;Z LTD." />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"ben"};
service.changeSignature(users,
                        "Liz Jones - (+1) 619-555-5555\n" +
                        "Accounts Management, A&Z LTD."); // signature

Example 2

• The username is liz.
• Her signature is to be disabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/signature

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="signature" value="" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changeSignature(user, ""); // signature

Updating Language Settings

Updating the display language setting in Google Mail can be accomplished with a PUT request to the following URL:

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/language

The following table shows the only property to be set when updating the display language.

• The RFC 3066 Language Tag format begins with a primary subtag, optionally followed with more subtags separated by hyphens/minus signs, '-'.
• In most cases, the primary subtag will be all you will need to specify the language (e.g. "de", "ko" or "hi" for German, Korean or Hindi).
• In a few cases, such as English or Chinese, you will need a subtag to show which variant of the language to display (e.g. "en-US" or "en-GB" for US or British English, and "zh-CN" or "zh-TW" for simplified or traditional Chinese).
• Note that in many cases, although there are many regional subtags which could represent a certain language, for technical reasons the Email Settings API will only accept the ones listed in the table below - so instead of "zh-HK", send "zh-TW" to mean Chinese (traditional).

Language Examples

Example 1

• The username is liz.
• Liz's Google Mail display will be in German next time she signs in. (The RFC 3066 tag for German is "de")

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/language

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="language" value="de" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changeLanguage(users, "de"); // language

Language Tags

Updating General Settings

Updating various Google Mail General settings can be accomplished with a PUT request to the following URL:

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain}/{username}/general

The following table shows the properties to be set when updating general settings. A request should contain at least one of these properties, but need not contain all five.

General Settings Examples

Example 1

• The username is liz.
• Her page size is to be set to show only 25 conversations per page.
• Personal indicators (arrows) are to be enabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/general

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="pageSize" value="25" />
    <apps:property name="arrows" value="true" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changeGeneral(users,
                      "25",   // pageSize
                      false,  // shortcuts
                      true,   // arrows
                      false,  // snippets
                      false); // unicode

Example 2

• The username is liz.
• Keyboard shortcuts are to be enabled.

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/liz/general

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
    <apps:property name="shortcuts" value="false" />
</atom:entry>

import sample.appsforyourdomain.gmailsettings;
...

GmailSettings service = new GmailSettings("your-apps", "yourdomain", "adminUsername", "adminPassword");
String[] users = new String[] {"liz"};
service.changeGeneral(users,
                      "25",   // pageSize
                      true,   // shortcuts
                      false,  // arrows
                      false,  // snippets
                      false); // unicode

Common Errors for Email Settings API

Incorrect URI

PUT https://apps-apis.google.com/a/feeeds/emailsettings/2.0/example.com/johndoe/language
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="language" value="ko" />
</atom:entry>

HTTP/1.1 302 Found
Connection: Close
Location: http://www.google.com
Content-Type: text/html; charset=UTF-8

<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>302 Moved</TITLE></HEAD><BODY>
<H1>302 Moved</H1>
The document has moved
<A HREF="http://www.google.com">here</A>.
</BODY></HTML>

Invalid domain user

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/invaliduser/language
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="language" value="ko" />
</atom:entry>

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<AppsForYourDomainErrors>
  <error errorCode="1301" invalidInput="" reason="EntityDoesNotExist" />
</AppsForYourDomainErrors>

Incorrect HTTP method (POST instead of PUT)

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/language
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="language" value="ko" />
</atom:entry>

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/plain; charset=UTF-8

Invalid request URI.

Incorrect version in URI (1.0 instead of 2.0)

PUT https://apps-apis.google.com/a/feeds/user/1.0/example.com/johndoe/language
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="language" value="ko" />
</atom:entry>

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/plain; charset=UTF-8

Invalid request URI.

No XML sent in request

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/language
<!-- missing XML. -->

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/plain; charset=UTF-8

Premature end of file.

Request missing a required boolean field

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/vacation
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <!-- Property "enable" is missing. -->
  <apps:property name="subject" value="Out of office" />
  <apps:property name="message" value="If it's urgent you can contact me on 555-5555." />
  <apps:property name="contactsOnly" value="true" />
</atom:entry>

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/plain; charset=UTF-8

Required field missing: enable

Request missing a required string

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/sendas
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <!-- Property "name" is missing. -->
  <apps:property name="address" value="sales@example.com" />
</atom:entry>

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/plain; charset=UTF-8

Required field missing: name

Property exceeds char count

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/filter
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="from" value="alice@gmail.com" />
  <apps:property name="hasTheWord" value="project proposal" />
  <apps:property name="shouldMarkAsRead" value="true" />
  <apps:property name="label" value="01234567890123456789012345678901234567890" />
</atom:entry>

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/plain; charset=UTF-8

Must be at most 40 characters: label

Misspelled tags

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/filter
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="from" value="alice@gmail.com" />
  <apps:property name="hasTheWord" value="project proposal" />
  <aapps:property name="shouldMarkAsRead" value="true" />
</atom:entry>

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/plain; charset=UTF-8

The prefix "aapps" for element "aapps:property" is not bound.

Request for Send As contains an invalid user

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/sendas
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="name" value="Sales" />
  <apps:property name="address" value="invaliduser@example.com" />
</atom:entry>

HTTP/1.1 400 Bad Request
Connection: Close
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<AppsForYourDomainErrors>
  <error errorCode="1301" invalidInput="invaliduser@example.com" reason="EntityDoesNotExist" />
</AppsForYourDomainErrors>

Missing or incorect authorization token was sent

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/filter
<!-- no authorization token was sent with this request -->
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="from" value="alice@gmail.com" />
  <apps:property name="hasTheWord" value="project proposal" />
  <apps:property name="shouldMarkAsRead" value="true" />
</atom:entry>

HTTP/1.1 401 (Unauthorized) Unknown authorization header
Connection: Close
Content-Type: text/html; charset=UTF-8

<HTML>
<HEAD>
<TITLE>Unknown authorization header</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
<H1>Unknown authorization header</H1>
<H2>Error 401</H2>
</BODY>
</HTML>

Request for invalid domain

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/invaliddomain.com/johndoe/language
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="language" value="ko" />
</atom:entry>

HTTP/1.1 403 (Forbidden) You are not authorized to perform operations on the domain invaliddomain.com.
<HTML>
<HEAD>
<TITLE>You are not authorized to perform operations on the domain invaliddomain.com.</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
<H1>You are not authorized to perform operations on the domain invaliddomain.com.</H1>
<H2>Error 403</H2>
</BODY>
</HTML>

HTTP/1.1 403 (Forbidden) Domain cannot use API
Connection: Close
Content-Type: text/html; charset=UTF-8

<HTML>
<HEAD>
<TITLE>Domain cannot use API</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
<H1>Domain cannot use API</H1>
<H2>Error 403</H2>
</BODY>
</HTML>

Content-type in HTTP request is incorrect

PUT https://apps-apis.google.com/a/feeds/emailsettings/2.0/example.com/johndoe/language
<!-- Content-Type should be "application/atom+xml" -->
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="language" value="ko" />
</atom:entry>

HTTP/1.1 415 Unsupported Media Type
Connection: Close
Content-Type: text/plain; charset=UTF-8

Content-Type text/html;charset=UTF-8 is not valid.