Google Apps APIs

About Google Apps APIs
- Overview
- Getting Started
Management APIs
- Provisioning API
  - Developer's Guide
    - Java
    - .NET
    - PHP
    - Python
  - Reference Guide
- Email Migration API
  - Developer's Guide
    - Java
    - .NET
  - Reference Guide
Application APIs
- Domain Shared Contacts
- User Profiles API
  - Developer's Guide
  - Reference Guide
- Contacts Data API
- Calendar Data API
- Documents List Data API
- Spreadsheets Data API
- Email Settings API
- 2-legged OAuth for Google Apps Data
- Gmail Inbox Feed
Resources
Solutions Marketplace

Email Settings API Developer's Guide

Overview
1. API Operations
API Authentication
1. Sample Code for Obtaining an Authentication Token
Using the Email Settings API
Creating a Label
1. Label Creation Examples
Creating a Filter
1. Filter Creation Examples
Creating a Send-as Alias
1. Send-As Alias Creation Examples
Updating Web Clip Settings
1. Web Clip Settings Examples

Updating Forwarding Settings
1. Forwarding Settings Examples
Updating POP Settings
1. POP Settings Examples
Updating IMAP Settings
1. IMAP Settings Examples
Updating Vacation-Responder Settings
1. Vacation-Responder Settings Examples
Updating Signature
1. Signature Examples
Updating Language Settings
1. Language Examples
2. Language Tags
Updating General Settings
1. General Settings Examples
Common Errors for Email Settings API

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

Setting	settingID	POST or PUT
Label creation	label	POST
Filter creation	filter	POST
Send-as Alias creation	sendas	POST
Web clip settings	webclip	PUT
Forwarding settings	forwarding	PUT
POP settings	pop	PUT
IMAP settings	imap	PUT
Vacation Responder settings	vacation	PUT
Signature	signature	PUT
Language settings	language	PUT
General settings	general	PUT

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.

Name	XML attribute	example XML value	Description	Possible values
label	name="label"	value="Important"	The label to create in Google Mail	(any HTML encoded string up to 40 characters- note that the '^' character is not allowed)

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>

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

Name	XML attribute	example XML value	Description	Possible values
From	name="from"	value="jane@example.com"	The email must come from this address in order to be filtered.	(a valid email address up to 400 characters)
To	name="to"	value="bob@example.com"	The email must be sent to this address in order to be filtered.	(a valid email address up to 400 characters)
Subject	name="subject"	value="project"	A string the email must have in its subject line to be filtered.	(any HTML encoded string up to 1000 characters*)
Has the words	name="hasTheWord"	value="work"	A string the email can have anywhere in it's subject or body.	(any HTML encoded string up to 1000 characters*)
Doesn't have	name="doesNotHaveTheWord"	value="proposal"	A string that the email cannot have anywhere in its subject or body.	(any HTML encoded string up to 1000 characters*)
Has attachment	name="hasAttachment"	value="true"	A boolean representing whether or not the email contains an attachment.	"true" or "false"

*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

Action	XML attribute	example XML value	Description	Possible values
Apply a label	name="label"	value="example.com work"	The name of the label to apply if a message matches the specified filter criteria.	(any HTML encoded string up to 40 characters- note that the '^' character is not allowed)
Mark as read	name="shouldMarkAsRead"	value="true"	Whether to automatically mark the message as read if it matches the specified filter criteria	"true" or "false"
Archive	name="shouldArchive"	value="true"	Whether to automatically move the message to "Archived" state if it matches the specified filter criteria	"true" or "false"

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>

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>

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.

Name	XML attribute	example XML value	Description	Possible values
name	name="name"	value="Network Support"	The name that will appear in the "From" field for this user.	(any HTML encoded string up to 250 characters)
address	name="address"	value="support@example.com"	The email address that appears as the origination address for emails sent by this user.	(any email address which exists as a user or an alias on the hosted domain)
replyTo	name="replyTo"	value="fred@example.net"	(Optional) If set, this address will be included as the reply-to address in emails sent using the alias.	(any valid email address)
makeDefault	name="makeDefault"	value="true"	(Optional) If set to true, this alias will be become the new default alias to send-as for this user.	"true" or "false"

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>

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>

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.

Name	XML attribute	example XML value	Description	Possible values
enable	name="enable"	value="true"	Whether to enable showing Web clips.	"true" or "false"

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

Name	XML attribute	example XML value	Description	Possible values
enable	name="enable"	value="true"	Whether to enable forwarding of incoming mail.	"true" or "false"
forwardTo	name="forwardTo"	value="fred@example.com"	The email will be forwarded to this address.	(any valid email address)
action	name="action"	value="KEEP"	What Google Mail should do with its copy of the email after forwarding it on.	"KEEP" (in inbox), "ARCHIVE", or "DELETE" (send to trash)

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>

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>

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>

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

Name	XML attribute	example XML value	Description	Possible values
enable	name="enable"	value="true"	Whether to enable POP3 access.	"true" or "false"
enableFor	name="enableFor"	value="ALL_MAIL"	Whether to enable POP3 for all mail, or mail from now on.	"ALL_MAIL", "MAIL_FROM_NOW_ON"
action	name="action"	value="KEEP"	What Google Mail should do with its copy of the email after it is retrieved using POP.	"KEEP" (in inbox), "ARCHIVE", or "DELETE" (send to trash)

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>

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>

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>

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.

Name	XML attribute	example XML value	Description	Possible values
enable	name="enable"	value="true"	Whether to enable IMAP access.	"true" or "false"

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>

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>

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.

Name	XML attribute	example XML value	Description	Possible values
enable	name="enable"	value="true"	Whether to enable the vacation responder.	"true" or "false"
subject	name="subject"	value="On vacation!"	The subject line of the vacation responder autoresponse.	(any HTML encoded string up to 500 characters)
message	name="message"	value="I won't be checking email until the 28th."	The message body of the vacation responder autoresponse..	(any HTML encoded string up to 100 KB of characters)
contactsOnly	name="contactsOnly"	value="true"	Whether to only send the autoresponse to known contacts.	"true" or "false"

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>

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>

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.

Name	XML attribute	example XML value	Description	Possible values
signature	name="signature"	value="Regards, Joe."	The signature to be appended to outgoing messages. Don't want a signature? Set the signature to "" (empty string).	(any HTML encoded string up to 1000 characters)

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>

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>

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.

Name	XML attribute	example XML value	Description	Possible values
language	name="language"	value="en-US"	Google Mail's display language	Language Tag according to RFC 3066, for any language that Google Mail supports. e.g. "en-GB", "fr" or "ja" for British English, French, or Japanese See complete list below.

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>

Language Tags

English name for language	Language (as displayed in Google Mail)	RFC 3066 Language Tag accepted by Google Mail
Arabic	العربية	ar
Bengali	বাংলা	bn
Bulgarian	Български	bg
Catalan	Català	ca
Chinese (Simplified)	中文（简体）	zh-CN
Chinese (Traditional)	中文（繁體）	zh-TW
Croatian	Hrvatski	hr
Czech	Český	cs
Danish	Dansk	da
Dutch	Nederlands	nl
English (United States)	English (US)	en-US
English (United Kingdom)	English (UK)	en-GB
Estonian	Eesti keel	et
Finnish	Suomi	fi
French	Français	fr
German	Deutsch	de
Greek	Ελληνικά	el
Gujarati	ગુજરાતી	gu
Hebrew	עברית	iw
Hindi	हिन्दी	hi
Hungarian	Magyar	hu
Icelandic	Íslenska	is
Indonesian	Bahasa Indonesia	in
Italian	Italiano	it
Japanese	日本語	ja
Kannada	ಕನ್ನಡ	kn
Korean	한국어	ko
Latvian	Latviešu	lv
Lithuanian	Lietuvių	lt
Malay	Bahasa Melayu	ms
Malayalam	മലയാളം	ml
Marathi	मराठी	mr
Norwegian	Norsk (Bokmål)	no
Oriya	ଓଡିଆ (Oriya)	or
Persian	فارسی	fa
Polish	Polski	pl
Portuguese (Brazil)	Português (Brasil)	pt-BR
Portuguese (Portugal)	Português (Portugal)	pt-PT
Romanian	Română	ro
Russian	Русский	ru
Serbian	Српски	sr
Slovak	Slovenský	sk
Slovenian	Slovenščina	sl
Spanish	Español	es
Swedish	Svenska	sv
Tagalog	Filipino	tl
Tamil	தமிழ்	ta
Telugu	తెలుగు	te
Thai	ภาษาไทย	th
Turkish	Türkçe	tr
Ukrainian	Українська	uk
Urdu	اردو	ur
Vietnamese	Tiếng Việt	vi

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.

Name	XML attribute	example XML value	Description	Possible values
pageSize	name="pageSize"	value="50"	The number of conversations to be shown per page.	"25", "50" or "100"
shortcuts	name="shortcuts"	value="true"	Whether to enable keyboard shortcuts	"true" or "false"
arrows	name="arrows"	value="true"	Whether to display arrow-shaped personal indicators next to emails that were sent specifically to the user. ( › and » )	"true" or "false"
snippets	name="snippets"	value="true"	Whether to display snippets of messages in the inbox and when searching.	"true" or "false"
unicode	name="unicode"	value="true"	Whether to use UTF-8 (unicode) encoding for all outgoing messages, instead of the default text encoding.	"true" or "false"

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>

Example 2

The username is liz.
Keyboard shortcuts are to be disabled.

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>

Common Errors for Email Settings API

Incorrect URI

Request

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>

Response

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

Request

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>

Response

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)

Request

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>

Response

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)

Request

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>

Response

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

Invalid request URI.

No XML sent in request

Request

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

Response

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

Request

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>

Response

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

Required field missing: enable

Request missing a required string

Request

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>

Response

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

Required field missing: name

Property exceeds char count

Request

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>

Response

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

Must be at most 40 characters: label

Misspelled tags

Request

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>

Response

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

The prefix &quot;aapps&quot; for element &quot;aapps:property&quot; is not bound.

Request for Send As contains an invalid user

Request

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>

Response

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

Request

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>

Response

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

Request

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>

Response

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

Request

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>

Response

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.


e.g. "ajax apis" or "open source"

Google Apps APIs

About Google Apps APIs

Management APIs

Application APIs

Resources

Solutions Marketplace

Email Settings API Developer's Guide

Contents

Overview

API Operations

API Authentication

Sample Code for Obtaining an Authentication Token

Using the Email Settings API

Email Settings API HTTP Format

XML Request Format

XML Responses

Common Problems

Creating a Label

Label Creation Examples

Example 1

Creating a Filter

Filter Criteria Properties

Filter Action Properties

Filter Creation Examples

Example 1

Example 2

Creating a Send-as Alias

Send-As Alias Creation Examples

Example 1

Example 2

Updating Web Clip Settings

Web Clip Settings Examples

Example 1

Example 2

Updating Forwarding Settings

Forwarding Settings Examples

Example 1

Example 2

Example 3

Updating POP Settings

POP Settings Examples

Example 1

Example 2

Example 3

Updating IMAP Settings

IMAP Settings Examples

Example 1

Example 2

Updating Vacation-Responder Settings

Vacation-Responder Settings Examples

Example 1

Example 2

Updating Signature

Signature Examples

Example 1

Example 2

Updating Language Settings

Language Examples

Example 1

Language Tags

Updating General Settings

General Settings Examples

Example 1

Example 2

Common Errors for Email Settings API

Incorrect URI

Invalid domain user

Incorrect HTTP method (POST instead of PUT)

Incorrect version in URI (1.0 instead of 2.0)

No XML sent in request

Request missing a required boolean field

Request missing a required string

Property exceeds char count

Misspelled tags

Request for Send As contains an invalid user

Missing or incorect authorization token was sent

Request for invalid domain

Content-type in HTTP request is incorrect