English | Site Directory

Google Apps APIs

Google Apps Provisioning API Developer's Guide: Protocol

Last updated September 17, 2008 (see recent changes)

Contents

  1. Overview
  2. API Operations
  3. Authentication
  4. How the API Works
    1. XML Request Formats
    2. XML Response Formats
    3. Results Pagination
  5. Appendixes
    1. Appendix A - Setting Up Google Apps
    2. Appendix B - XML Tag Definitions
    3. Appendix C - Sample XML Responses
    4. Appendix D - GData Error Codes
    5. Appendix E - Client Library Methods

Overview

Google Apps allows website administrators to offer their users cobranded versions of a variety of personalized Google applications, such as Gmail. This document describes the Google Apps Provisioning API, which enables Google partners to programmatically enable access to these applications. Specifically, the API provides functions for creating, retrieving, updating and deleting user accounts, nicknames and email lists.

This version of the Provisioning API follows the principles of the Google Data APIs. Google Data APIs are based on both the Atom 1.0 and RSS 2.0 syndication formats in addition to the Atom Publishing Protocol. Learn more about Google Data APIs.

Note: The Provisioning API is only available to Google Apps Premier Edition and Google Apps Education Edition partners. To enable the API, log in to your admin account, and click the User accounts tab. Then click the Settings subtab to enable the API, select the checkbox to enable the Provisioning API and save your changes. (You will need to complete the steps for setting up Google Apps before you can log in to your admin account.)

(Google will continue to support partners who already implemented version 1.0 of the Provisioning API. However, new partners must implement version 2.0 of the API.)

About this Document

This document contains the following sections:

  • The API Operations section introduces the types of functionality that you can access through the Provisioning API.

  • The Authentication section describes the authentication process needed for all API requests.

  • The How the API Works section explains the different types of API requests, the XML format of each request, and the format of the API's XML response to each request. Collectively, these sections explain how to construct API XML requests and how to process the XML responses.

  • The Using the Java Client Library section discusses the Google Apps Java client library, which provides methods that create API XML requests, submit those requests to the appropriate URLs and handle the API responses to those requests. In other words, this section explains how to use the Java client library to perform the processes discussed in the How the API Works section.

  • The Using the .NET Client Library section describes how to use the .NET client library to perform the operations described below.

  • The Using the PHP Client Library section describes how to use the PHP client library to perform the operations described below.

  • The Using the Python Client Library section describes how to use the Python client library to perform the operations described below.

  • The Appendixes provide background information about setting up your domain to use Google Apps. They also provide additional detail about the XML documents discussed in the document.

API Operations

To use the API, you will send HTTP requests to Google that instruct Google to perform a create, retrieve, update or delete operation on a resource in your domain. Resources include user accounts, nicknames and email lists.

This section explains the different types of operations that the API supports. The following section, How the API Works, identifies the URL that corresponds to each API operation. Note: The links below point to the corresponding Java Client Library methods. Parallel methods are also available in other client Libraries.

  • Create operations enable partners to add new user accounts, nicknames and email lists. Partners can also subscribe an email address to an email list using a Create request. To perform any of these operations, you will issue an HTTP POST request to the appropriate URL. The body of the POST request will be an XML document that contains information about the resource being created.

    Note:The maximum number of nicknames for a user is 30.

  • Retrieve operations allow Google partners to request and obtain information about user accounts, nicknames and email lists. To retrieve information about one of these resources, you will issue an HTTP GET request to the appropriate URL. The URL will contain information that identifies the requested resource.

  • Update operations allow Google partners to modify information about user accounts. To update a user account, you will issue an HTTP PUT request to the appropriate URL. The body of the PUT request will be an XML document that contains information about the resource being updated. The API supports the following types of updates:

    • Update a user's first name, last name or password.
    • Suspend or restore access to a user account.
    • Update the disk space allocated to the user. (This feature is not available to all partners.)

    Note: The API does not support updates to nicknames or email lists. To change a nickname or email list, you must delete the old entity and create a new one in its place. To update the list of subscribers to an email list, you must use the API requests for creating or deleting email list recipients.

  • Delete operations allow Google partners to delete user accounts, nicknames and email lists. Partners can also remove an email address from an email list using a Delete request. To perform any of these operations, you will issue an HTTP DELETE request to the appropriate URL. The URL will contain information that identifies the resource being deleted.

    Note: If you delete an account, you will not be able to create another account with the same username for at least five days.

Google will verify that all Create and Update requests contain valid XML, include all required data fields and meet authentication requirements.

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.

Obtaining an Authentication Token

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:

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

    • 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. If you encounter a CAPTCHA challenge while obtaining an authentication token, the knowledge base provides instructions on how you can handle it.

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.

How the API Works

To execute an operation using the API, you need to submit an HTTP POST, GET, PUT or DELETE request to the URL that corresponds to the operation that you wish to perform. Each URL includes variables that identify your domain and, possibly, the resource that you are creating, retrieving, updating or deleting. For example, to retrieve information about the us-sales email list in the www.example.com domain, you would submit an HTTP GET request to the following URL: 

https://apps-apis.google.com/a/feeds/www.example.com/emailList/2.0/us-sales

The tables in the subsections below identify the URLs associated with each API operation. The tables also identify the type of HTTP request associated with each API request.

Please note that all create and update requests – POST and PUT requests – also require you to submit an XML document that contains the information needed to fulfill the request. The content should be sent using the application/atom+xml content type. The XML Request Formats section, which follows the tables below, explains those XML structures.

Creating, Retrieving, Updating and Deleting User Accounts

Operation HTTP Request Type and URL
Create User Account POST https://apps-apis.google.com/a/feeds/domain/user/2.0
Retrieve User Account GET https://apps-apis.google.com/a/feeds/domain/user/2.0/userName
Retrieve All Users in Domain GET https://apps-apis.google.com/a/feeds/domain/user/2.0
Update User Account PUT https://apps-apis.google.com/a/feeds/domain/user/2.0/userName
Delete User Account DELETE https://apps-apis.google.com/a/feeds/domain/user/2.0/userName

Creating, Retrieving and Deleting Nicknames

Operation HTTP Request Type and URL
Create Nickname POST https://apps-apis.google.com/a/feeds/domain/nickname/2.0
Retrieve Nickname GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0/nickname
Retrieve All Nicknames for a User GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0?username=userName
Retrieve All Nicknames in Domain GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0
Delete Nickname DELETE https://apps-apis.google.com/a/feeds/domain/nickname/2.0/nickname

Creating, Retrieving and Deleting Email Lists

Operation HTTP Request Type and URL
Create Email List POST https://apps-apis.google.com/a/feeds/domain/emailList/2.0
Retrieve Email List GET https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName
Retrieve All Email List Subscriptions for an Email Address GET https://apps-apis.google.com/a/feeds/domain/emailList/2.0?recipient=emailAddress
Retrieve All Email Lists in Domain GET https://apps-apis.google.com/a/feeds/domain/emailList/2.0
Delete Email List DELETE https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName

Changing and Retrieving Email List Subscriptions

Operation HTTP Request Type and URL
Add Address to Email List POST https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName/recipient/
Retrieve All Subscribers to Email List GET https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName/recipient/
Remove Address from Email List DELETE https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName/recipient/emailAddress

XML Request Formats

For API requests to create or update information – HTTP POST and PUT requests – the body of the request must be an XML document that provides the data necessary to complete the request. For API requests to retrieve or delete information – HTTP GET and DELETE requests – the URL and HTTP request type specify all of the information that Google needs to fulfill the request.

The following subsections provide examples of the XML requests for creating user accounts, nicknames, email lists and email list recipients. The XML format for creating a user account is also used to update user accounts. (Nicknames, email lists and email list recipients cannot be updated; they may only be created, retrieved or deleted.)

User Data XML Format
Nickname Data XML Format
Email List Data XML Format
Email List Recipient Data XML Format

Note for partners using the client libraries: The client libraries provide methods that automatically create and submit these XML structures. While you may want to review the XML samples below, the Submitting API Requests through the Java Client Library, Submitting API Requests through the .NET Client Library, Submitting API Requests through the PHP Client Library, and Submitting API Requests through the Python Client Library sections explain how to use the client libraries to submit API requests and handle API responses without having to work directly with XML.

User Data XML Format

The following XML shows a sample request to create a user. This XML could also be used to update a user account. In addition, the ability to set the user's disk space quota using the <apps:quota> is not available to all partners. Your partner agreement will indicate whether this feature is available for your domain. All fields that are set by the partner are shown in bold text.

Note: This XML format contains all of the data that can be stored in a UserEntry object in the client libraries.

<?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">
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#user"/>
    <apps:login userName="SusanJones-1321" 
        password="123$$abc" suspended="false"/>
    <apps:quota limit="2048"/>
    <apps:name familyName="Jones" givenName="Susan"/>
</atom:entry>

Even though requests to create and update user accounts use the same XML format, these requests are different in several ways.

  • In a request to create a user, the <apps:name> tag and its attributes – familyName and givenName – are required. However, a request to update a user does not need to include this tag or its attributes unless the request is updating the user's given name or family name.

  • In a request to create a user, the <apps:login> tag is required, and the request must provide values for the username and password attributes. A request to update a user does not need to include the <apps:login> tag. In addition, the request should not provide a value for the <apps:login> tag's password attribute unless the user's password is being updated.

  • Typically, the suspended attribute of the <apps:login> tag only appears in update requests. (By default, newly created accounts are active.)

Nickname Data XML Format

The following XML shows a sample request to create a nickname. The XML uses the <apps:nickname> tag to specify the nickname and the <apps:login> tag to identify the user who is assigned the nickname. The fields that are set by the partner are shown in bold text.

Note: This XML format contains all of the data that can be stored in a NicknameEntry object in the client libraries.

<?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">
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#nickname"/>
    <apps:nickname name="Susy-1321"/>
    <apps:login userName="SusanJones-1321"/>
</atom:entry>

Email List Data XML Format

The following XML shows a sample request to create an email list. The XML uses the <apps:emailList> tag to specify the name of the email list. The field that is set by the partner is shown in bold text.

Note: This XML format contains all of the data that can be stored in an EmailListEntry object in the client libraries.

<?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">
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#emailList"/>
    <apps:emailList name="us-sales"/>
</atom:entry>

A newly created email list does not have any subscribers. Learn more about adding recipients to an email list using either XML or the client libraries (Java, .NET, PHP, Python).

Email List Recipient Data XML Format

The following XML shows a sample request to subscribe an email address to an email list. The XML uses the <gd:who> tag to identify the email address being added. The field that is set by the partner is shown in bold text.

Note: This XML format contains all of the data that can be stored in an EmailListRecipientEntry object in the client libraries.

<?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"
    xmlns:gd="http://schemas.google.com/g/2005">
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#emailList.recipient"/>
    <gd:who xmlns="http://schemas.google.com/g/2005"
        email="SusanJones-6389@example.com"/>
</atom:entry>

XML Response Formats

Depending on the API request, the Google Apps Provisioning API will return one of 10 different types of responses. The list below defines the different types of responses and explains which API requests can produce each response. Appendix C provides XML examples for each of the first nine responses. (The tenth response type does not use XML.)

Note: The terms used to define the different response types are consistent with the object names used in the client libraries. For example, the following list defines a UserEntry response as an XML document that contains information about a single user. The client libraries convert this XML response into a UserEntry object.

  1. A UserEntry response contains information about a single user. The API requests to create a user, retrieve a user, update a user, suspend a user and restore a user all produce a UserEntry response.

  2. A UserFeed response contains a series of one or more UserEntry XML structures, each of which contains information about a single user. The only API request that yields a UserFeed response is the request to retrieve all users for a domain.

  3. A NicknameEntry response contains information about a single nickname. It identifies the nickname and the user to whom the nickname is assigned. The API requests to create a nickname and to retrieve a nickname both yield a NicknameEntry response.

  4. A NicknameFeed response contains a series of one or more NicknameEntry XML structures, each of which identifies the nickname and the user to whom the nickname is assigned. The API requests to retrieve all nicknames for a domain and to retrieve all nicknames assigned to a particular user both produce a NicknameFeed response.

  5. An EmailListEntry response contains information about a single email list and a link to retrieve a list of recipients for that email list. The API requests to create an email list and to retrieve an email list both yield an EmailListEntry response.

  6. An EmailListFeed response contains a series of one or more EmailListEntry responses. The API requests to retrieve all email lists for a domain and to retrieve all email lists that a particular user receives both return an EmailListFeed response.

  7. An EmailListRecipientEntry response identifies an individual user who is subscribed to a particular email list. The API request to add a recipient to an email list yields an EmailListRecipientEntry response.

  8. An EmailListRecipientFeed response contains a series of one or more EmailListRecipientEntry responses, each of which identifies a user who subscribes to a particular email list. The API request to retrieve all recipients for a particular email list yields an EmailListRecipientFeed response.

  9. The API returns an error XML response for invalid API requests. Any API request could produce an error response. In the response, the value of the <error> tag will explain why the API request was invalid. The Java and Python client libraries will return an AppsForYourDomainException when it receives an error response from the Provisioning API. The .NET client library will return an AppsException object. That object will be populated with the error information. The client library may also throw other exceptions for other types of errors. For more information, please see the discussion about "Identifying Errors in API Responses" in the respective Client Library sections (Java, .NET, PHP, Python).

  10. The API returns an HTTP 200 response code for all Successful HTTP DELETE requests. This includes the requests for deleting a user account, deleting a nickname, deleting an email list and removing a recipient from an email list.

As noted above, Appendix C - Sample XML Responses provides examples of the nine different types of XML responses. (The last response type – an HTTP 200 response code – does not use XML.)

Results Pagination

If your API request produces a UserFeed, NicknameFeed, EmailListFeed or EmailListRecipientFeed response, the Provisioning API will return an Atom XML feed containing a maximum of 100 entries. If there are more than 100 entries in the feed, the API response will contain an <atom:link> tag for which the rel attribute has a value of next. The URL identified in that <atom:link> tag points to the next page of results for the request.

In the XML excerpt below, the <atom:link> tag that identifies the next page of results is highlighted in bold text:

<?xml version="1.0" encoding="UTF-8"?>
<atom:id>
    https://apps-apis.google.com/a/feeds/example.com/emailList/2.0
</atom:id>
<atom:category scheme="http://schemas.google.com/g/2005#kind"
    term="http://schemas.google.com/apps/2006#emailList"/>
<atom:title type="text">EmailLists</atom:title>
<atom:link rel="next" type="application/atom+xml"
    href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0?startEmailListName=eng"/>
<atom:link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0"/>
...

The time to complete requests to retrieve all users, nicknames, email lists or recipients of an email list will directly relate to the amount of data being retrieved. For example, if an email list has 100 subscribers, the client library can obtain a complete subscriber list with a single HTTP request. However, if an email list has 1,000 subscribers, you must make 10 HTTP requests to obtain the full subscriber list.

  • If you are using the Java, .NET, PHP, or Python client library, the code provides you with the option of explicitly requesting additional pages of results or automatically requesting additional results until all results have been obtained. For example, the retrievePageOfUsers method makes a single HTTP request for up to 100 users, and the retrieveAllUsers method will automatically issue additional HTTP requests until all results have been obtained.

  • If you write your own code to process API responses, you will need to ensure that your code requests additional pages of results as necessary.

Appendixes

Appendix A - Setting Up Google Apps

To set up Google Apps, you will need to create a Google account that will serve as an admin account for your domain. You can use an existing Google account. However, since the owner of the account will have the ability to create, update and delete user accounts for your domain, we recommend that you consider creating a new Google account for your domain rather than using someone's personal Google account.

The following steps explain how you would set up Google Apps.

  1. Go to the home page for Google Apps and follow the instructions to sign up for Google Apps Premier Edition (for your enterprise) or Google Apps Education Edition (for your school).

  2. Enter your domain name or indicate that you would like to purchase a new domain. If you purchase a new domain, you will need to complete the registration forms for the new domain before proceeding to the next step.

  3. Complete the form to provide information about your organization and yourself to Google.

  4. On the following page, complete the form indicating the number of user accounts you would like to purchase and then accept the terms and conditions.

  5. Complete the signup process using Google Checkout.

  6. Complete the form to set up your admin account.

  7. Follow the instructions to verify that you own your domain.

  8. Use the email address and password for your admin account to request an authentication token for your domain. The authentication token will be submitted in each API request that you send to Google, and Google will use the authentication token to authorize the execution of those API requests.

Appendix B - XML Tag Definitions

This appendix contains definitions of the XML tags used in Provisioning API requests and responses.

Subtags Legend

Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:

? = optional subtag
* = zero or more instances of the subtag
+ = one or more instances of the subtag
| = Boolean OR

atom:feed
Definition

The <atom:feed> tag encapsulates an API response to a request to retrieve either all of the nicknames associated with an account or all of the email lists that an account subscribes to.
Example <atom:feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
Subtags atom:id, atom:category, atom:link, openSearch:startIndex, openSearch:itemsPerPage, atom:entry
Content Format Container

atom:entry
Definition

The <atom:entry> encapsulates an API request or an API Atom response.
Subtags atom:id, atom:category, atom:title, atom:link, apps:login, apps:name, gd:feedLink, gd:who
Content Format Container

atom:category
Definition

The <atom:category> tag specifies the type of resource that is described in an Atom request or response.
Attributes
Name Format Description
scheme Text This attribute specifies the XML schema that defines the resource type. Please set this attribute value to http://schemas.google.com/g/2005#kind.
term Text This attribute identifies the category to which the entry belongs. If you are submitting an API request, please use the appropriate value from the list below:

Type of Resource URL
Account http://schemas.google.com/apps/2006#user
Nickname http://schemas.google.com/apps/2006#nickname
Email List http://schemas.google.com/apps/2006#emailList

The appropriate value is also returned in the API's XML responses.
Subtag of atom:entry
Content Format Empty

atom:title
Definition

The <atom:title> tag value describes an API response.
Attributes
Name Format Description
type String

This attribute identifies the content format of the tag's value. The value of the type attribute must be text.
Example <atom:title type="text">SusanJones-1321</atom:title>
Subtag of atom:entry
Content Format Complex

atom:id
Definition

The <atom:id> tag's value identifies a permanent, unique identifier for a feed. This tag is included in API responses. It may also be included in requests to update user accounts. When you include this tag in API requests, the tag's value should be set to the URL to which you submit your API request.
Example <atom:id>https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales</atom:id>
Subtag of atom:entry
Content Format String (IRI)

atom:link
Definition

The <atom:link> tag provides an IRI reference related to an API results feed or a resource in the feed.
Attributes
Name Format Description
rel Text

The rel attribute identifies the relationship of the link to the API response feed.

  • If the value of the rel attribute is self, then the href attribute value will be a link to the URL you would use to request the feed.

  • If the value of the rel attribute is edit, then the href attribute value will be the URL that you would use to retrieve, update or delete the resource. Note: You would use an HTTP GET request to retrieve the resource, an HTTP PUT request to update the resource, and an HTTP DELETE request to delete the resource.

  • If the value of the rel attribute is next, then the href attribute value contains the URL that you would use to retrieve the next page of results for the request. Please see the Pagination in API Responses section of this document for more information.
href Text The href attribute contains an IRI reference that indicates how to retrieve or edit the information in an API response.
Example <atom:link rel="edit" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
Subtag of atom:entry
Content Format Empty

atom:updated
Definition

The <atom:updated> tag identifies the date and time that an entry in an Atom feed was updated. This tag is included in Provisioning API responses so that those responses conform with the Atom specification. However, the value of the <atom:updated> tag will always be a date in 1970 and the value does not serve a function in Provisioning API responses.
Example <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
Subtag of atom:feed, atom:entry
Content Format Date

apps:emailList
Definition

The <apps:emailList> tag specifies an email list.
Attributes
Name Format Description
name Text The name attribute identifies the email list. The name attribute is required.
Example <apps:emailList name="us-sales"/>
Subtag of atom:entry
Content Format Complex

apps:login
Definition

The <apps:login> tag specifies the username, and possibly the password, associated with a user account.
Attributes
Name Format Description
userName Text

The userName attribute specifies the username associated with a user account. The userName attribute is required in requests to create a user account or a nickname. However, it is optional in requests to update user accounts. See a list of valid characters for usernames.

  • In requests to create an account, the userName attribute identifies the name that will be used for a new account.
  • In requests to update an account, the userName attribute identifies the account that will be updated.
  • In requests to create a nickname, the userName attribute identifies the account for which you are creating the nickname.
password Text

The password attribute identifies the password for a user account. Passwords must contain at least six characters.

The password attribute is required in requests to create an account. However, it is optional in requests to update an account and should only be provided if the user is updating her account password.

Note: This attribute is not returned in API responses.
hashFunctionName Text

The hashFunctionName attribute indicates the format of the value of the password attribute. Currently the only valid values for this attribute are "SHA-1" and "MD5". If this attribute is specified, then password is a hashed value as opposed to clear text.

For example, rather than sending:

password="tiddlyWinkles"

as clear text, you can send the base16-encoded SHA-1 hash value of "tiddlyWinkles" as the value of password and "SHA-1" as the value of hashFunctionName as shown below:

password="51eea05d46317fadd5cad6787a8f562be90b4446"
hashFunctionName="SHA-1"

or you can send the base16-encoded MD5 hash value of "tiddlyWinkles" as the value of password and "MD5" as the value of hashFunctionName as shown below:

password="d27117a019717502efe307d110f5eb3d"
hashFunctionName="MD5"
admin Text

The admin attribute indicates whether the user in an admin user.

  • To give a user admin status, include the admin attribute in your request with a value of true.
  • To remove admin status for a particular user, include the admin attribute in your request with a value of false.
  • If you omit the admin attribute from your request, Google will not update the status of the user account.
agreedToTerms Text

The agreedToTerms attribute indicates whether the user has agreed to the Terms of Service. This is a read-only attribute.

suspended Text

The suspended attribute indicates whether a user account is suspended or active.

  • To suspend a user account, include the suspended attribute in your request with a value of true.
  • To restore a user's ability to access a suspended account, include the suspended attribute in your request with a value of false.
  • If you omit the suspended attribute from your request, Google will not update the status of the user account.
changePasswordAtNextLogin Text

The changePasswordAtNextLogin attribute indicates whether the system will force the user to change his or her password at the next login.

  • To force the user to change his or her password at the next login, include the changePasswordAtNextLogin attribute in your request with a value of true.
  • To cancel the obligation for a user to change his or her password, include the changePasswordAtNextLogin attribute in your request with a value of false.
  • If you omit the changePasswordAtNextLogin attribute from your request, Google will not update the status of the user account.
Example <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
Subtag of atom:entry
Content Format Complex

apps:name
Definition

The <apps:name> tag specifies the account owner's first name and last name. First and last names may contain spaces, letters (a-z), numbers (0-9), dashes (-), forward slashes (/) and periods(.).
Attributes
Name Format Description
familyName Text The familyName attribute identifies the user's last name or surname. The familyName attribute is required.
givenName Text The givenName attribute identifies the user's first, or given, name. The givenName attribute is required.
Example <apps:name familyName="Jones" givenName="Susan"/>
Subtag of atom:entry
Content Format Complex

apps:nickname
Definition

The <apps:nickname> tag specifies a nickname.
Attributes
Name Format Description
name Text The name attribute identifies the nickname. The name attribute is required.
Example <apps:nickname name="Jones"/>
Subtag of atom:entry
Content Format Complex

apps:quota
Definition

The <apps:quota> tag specifies the amount of disk space that should be allocated to a user account. By default, Google allocates 2GB of disk space to each user account.

  • Domains that have additional valid quotas in their contracts must specify a value for the <apps:quota> tag in requests to create user accounts.

  • Domains that do not have additional valid quotas specified in their contracts may omit the <apps:quota> tag from requests to create or update accounts.
Attributes
Name Format Description
limit Integer

The limit attribute specifies the amount of disk space, in megabytes (MB), that you are allocating to a user's account. The limit attribute is required.
Example <apps:quota limit="2048"/>
Subtag of atom:entry
Content Format Complex

gd:feedLink
Definition

The <gd:feedLink> tag contains information about a logically nested feed associated with an API response. For example, when you retrieve information about a user account, the API response contains two <gd:feedLink> tags. One tag contains information about a feed of nicknames associated with the retrieved account. The other tag contains information about a feed of email lists that the account is subscribed to.
Attributes
Name Format Description
rel Text The rel attribute identifies the type of content that is in the nested feed. If the attribute's value ends with user.nicknames, then the feed contains a list of nicknames associated with the user account. If the attribute's value ends with #user.emailLists, then the feed contains a list of email lists that the user account subscribes to.
href Text The href attribute specifies the URI that you can use to retrieve the related feed.
Example <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists" href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0?recipient=us-sales@example.com"/>
Subtag of atom:entry
Content Format Complex

gd:who
Definition

The <gd:who> tag identifies a person associated with an API response. This tag is used in API requests to add a person to an email list as well as in API responses to requests to update or retrieve an email list.
Attributes
Name Format Description
email Text The email attribute specifies an email address that is subscribed to the email list. The email address can be for a hosted email account in your domain or it can be an address at an external domain. The email attribute is required.
Example <gd:who email="SusanJones-1321@example.com"/>
Subtag of atom:entry
Content Format Complex

openSearch:startIndex
Definition

The <openSearch:startIndex> value identifies the one-based index of the first item returned in the result.
Example <openSearch:startIndex>1</openSearch:startIndex>
Subtag of atom:feed
Content Format Integer

openSearch:itemsPerPage
Definition

The <openSearch:itemsPerPage> value indicates the total number of items included in the API response.
Example <openSearch:itemsPerPage>10</openSearch:itemsPerPage>
Subtag of atom:feed
Content Format Integer

AppsForYourDomainErrors
Definition

The <AppsForYourDomainErrors> tag encapsulates a list of <error> tags explaining why an API request failed.
Example <AppsForYourDomainErrors>
Subtags error
Content Format Container

error
Definition

The <error> tag contains information explaining why Google failed to execute an API request.
Attributes
Name Format Description
errorCode Text

The errorCode attribute specifies the type of error that caused an API request to fail. The following list specifies possible values for this attribute. For more information about these codes, please see Appendix D - GData Error Codes.

  • UnknownError(1000)
  • UserDeletedRecently(1100)
  • UserSuspended(1101)
  • DomainUserLimitExceeded(1200)
  • DomainAliasLimitExceeded(1201)
  • DomainSuspended(1202)
  • DomainFeatureUnavailable(1203)
  • EntityExists(1300)
  • EntityDoesNotExist(1301)
  • EntityNameIsReserved(1302)
  • EntityNameNotValid(1303)
  • InvalidGivenName(1400)
  • InvalidFamilyName(1401)
  • InvalidPassword(1402)
  • InvalidUsername(1403)
  • InvalidHashFunctionName(1404)
  • InvalidHashDigestLength(1405)
  • InvalidEmailAddress(1406)
  • InvalidQueryParameterValue(1407)
  • TooManyRecipientsOnEmailList(1500)
reason Text The reason attribute contains a short explanation of the error.
invalidInput Text The invalidInput attribute contains the data that caused an API response to fail. This attribute may not be provided for all error types.
Example <error errorCode="1301" reason="EntityDoesNotExist" invalidInput="Some-Nonexistent-User"/>
Subtag of AppsForYourDomainErrors
Content Format Complex

Appendix C - Sample XML Responses

Sample UserEntry Response
 
 Sample UserFeed Response
 
 Sample NicknameEntry Response
 
 Sample NicknameFeed Response
 
 Sample EmailListEntry Response
 
 Sample EmailListFeed Response
 
 Sample EmailListRecipientEntry Response
 
 Sample EmailListRecipientFeed Response
 
 Sample Failure Response
 

Sample UserEntry Response

Whether you create, retrieve or update a user account, the Provisioning API returns an Atom XML response in the same format. The XML below shows a sample API response for modifying user account information. The client libraries convert this XML into a UserEntry object.

<?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"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones</atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/apps/2006#user"/>
    <atom:title type="text">SusanJones</atom:title>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
    <atom:link rel="edit" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
    <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
    <apps:name familyName="Jones" givenName="Susan"/>
    <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" 
    href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=Susy-1321"/>
    <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists" 
    href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0?recipient=us-sales@example.com"/>
</atom:entry>

Sample UserFeed Response

When you submit a request to retrieve all users for a domain, the Provisioning API returns an Atom XML feed containing a list of users, each of which is identified in an <atom:entry> XML block. The client libraries translate this feed into a UserFeed object, which contains a series of UserEntry objects.

The XML below shows a sample API response for a request to retrieve all users for a domain.

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" 
  xmlns:apps="http://schemas.google.com/apps/2006"
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>
        https://apps-apis.google.com/a/feeds/example.com/user/2.0
    </atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#user"/>
    <atom:title type="text">Users</atom:title>
    <atom:link rel="next" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/user/2.0?startUsername=john"/>
    <atom:link rel="http://schemas.google.com/g/2005#feed" 
        type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
    <atom:link rel="http://schemas.google.com/g/2005#post" 
        type="application/atom+xml"
        href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <atom:entry>
        <atom:id>
            https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones
        </atom:id>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#user"/>
        <atom:title type="text">SusanJones</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
        <gd:who rel="http://schemas.google.com/apps/2006#user.recipient" 
            email="SusanJones@example.com"/>
        <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
        <apps:quota limit="2048"/>
        <apps:name familyName="Jones" givenName="Susan"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" 
            href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=SusanJones"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists"
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0?recipient=SusanJones@example.com"/>
    </atom:entry>
    <atom:entry>
        <atom:id>
            https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith
        </atom:id>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#user"/>
        <atom:title type="text">JohnSmith</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith"/>
        <gd:who rel="http://schemas.google.com/apps/2006#user.recipient" 
            email="JohnSmith@example.com"/>
        <apps:login userName="JohnSmith" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
        <apps:quota limit="2048"/>
        <apps:name familyName="Smith" givenName="John"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" 
            href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=JohnSmith"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists"
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0?recipient=JohnSmith@example.com"/>
    </atom:entry>
</atom:feed>

Sample NicknameEntry Response

Whether you create or retrieve a nickname, the Provisioning API returns an Atom XML response in the same format. The XML below shows a sample API response for a request to create or retrieve a nickname. The client libraries convert this XML into a NicknameEntry object.

<?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"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/Susy</atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/apps/2006#nickname"/>
    <atom:title type="text">Susy</atom:title>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/Susy"/>
    <atom:link rel="edit" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/Susy"/>
    <apps:nickname name="Susy"/>
    <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
</atom:entry>

Sample NicknameFeed Response

When you submit a request to retrieve all nicknames for a domain or all nicknames assigned to a particular user, the Provisioning API returns an Atom XML feed containing a list of nicknames, each of which is identified in an <atom:entry> XML block. The client libraries translate this feed into a NicknameFeed object, which contains a series of NicknameEntry objects.

The XML below shows a sample API response for a request to retrieve all nicknames for the username SusanJones.

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" 
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:apps="http://schemas.google.com/apps/2006">
    <atom:id>
        https://apps-apis.google.com/a/feeds/example.com/nickname/2.0
    </atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#nickname"/>
    <atom:title type="text">Nicknames for user SusanJones</atom:title>
    <atom:link rel="http://schemas.google.com/g/2005#feed" 
        type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0"/>
    <atom:link rel="http://schemas.google.com/g/2005#post" 
        type="application/atom+xml"
        href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0"/>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=SusanJones"/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <openSearch:itemsPerPage>2</openSearch:itemsPerPage>
    <atom:entry>
        <atom:id>
            https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy
        </atom:id>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#nickname"/>
        <atom:title type="text">susy</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy"/>
        <apps:nickname name="susy"/>
        <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
    </atom:entry>
    <atom:entry>
        <atom:id>
            https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse
        </atom:id>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#nickname"/>
        <atom:title type="text">suse</atom:title>
        <atom:link rel="self" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse"/>
        <apps:nickname name="suse"/>
        <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
    </atom:entry>
</atom:feed>

Sample EmailListEntry Response

When you submit a request to create an email list, the Provisioning API returns an XML response that identifies the newly created list. The client libraries translate this response into an EmailListEntry object. Following a request to add an address to an email list, this object does not serve any purpose except to confirm that the request was successful.

The XML below shows a sample API response for a request to create an email list.

<?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"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales</atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/apps/2006#emailList"/>
    <atom:title type="text">us-sales</atom:title>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
    <atom:link rel="edit" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
    <apps:emailList name="us-sales"/>
    <gd:feedLink rel="http://schemas.google.com/apps/2006#emailList.recipients"
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/"/>
</atom:entry>

Sample EmailListFeed Response

When you submit a request to retrieve all email lists for a domain or all email lists to which a particular user subscribes, the Provisioning API returns an Atom XML feed containing a list of email lists, each of which is identified in an <atom:entry> XML block. The client libraries translate this feed into a EmailListFeed object, which contains a series of EmailListEntry objects.

The XML below shows a sample API response for a request to retrieve all email lists for a domain.

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" 
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>
        https://apps-apis.google.com/a/feeds/example.com/emailList/2.0
    </atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#emailList"/>
    <atom:title type="text">EmailLists</atom:title>
    <atom:link rel="next" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0?startEmailListName=john"/>
    <atom:link rel="http://schemas.google.com/g/2005#feed" 
        type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0"/>
    <atom:link rel="http://schemas.google.com/g/2005#post" 
        type="application/atom+xml"
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0"/>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0"/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <atom:entry>
        <atom:id>
            https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales
        </atom:id>
        <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#emailList"/>
        <atom:title type="text">us-sales</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
        <apps:emailList name="us-sales"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#emailList.recipients"
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/"/>
    </atom:entry>
    <atom:entry>
        <atom:id>
            https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-eng
        </atom:id>
        <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#emailList"/>
        <atom:title type="text">us-eng</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-eng"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-eng"/>
        <apps:emailList name="us-eng"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#emailList.recipients"
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-eng/recipient/"/>
    </atom:entry>
</atom:feed>

Sample EmailListRecipientEntry Response

When you submit a request to add an email address to an email list, the Provisioning API returns an XML response that identifies the newly added address. The client libraries translate this response into an EmailListRecipientEntry object. Following a request to add an address to an email list, this object does not serve any purpose except to confirm that the request was successful.

The XML below shows a sample API response for a request to retrieve a particular recipient in a given email list.

<?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"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/SusanJones%40example.com</atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/apps/2006#emailList.recipient"/>
    <atom:title type="text">SusanJones</atom:title>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/SusanJones%40example.com"/>
    <atom:link rel="edit" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/SusanJones%40example.com"/>
    <gd:who email="SusanJones@example.com"/>
</atom:entry>

Sample EmailListRecipientFeed Response

When you submit a request to retrieve all subscribers for an email list, the Provisioning API returns an Atom XML feed identifying a list of subscribers, each of which is identified in an atom:entry XML block. The <gd:who> tag within each of these blocks identifies the subscribed email address. The client libraries translate this response into an EmailListRecipientFeed object, which contains a list of EmailListRecipientEntry objects.

The XML below shows a sample API response for a request to retrieve all subscribers for an email list.

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" 
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>
        https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient
    </atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#emailList.recipient"/>
    <atom:title type="text">Recipients for email list us-sales</atom:title>
    <atom:link rel="next" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/?startRecipient=terry@example.com"/>
    <atom:link rel="http://schemas.google.com/g/2005#feed" 
        type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient"/>
    <atom:link rel="http://schemas.google.com/g/2005#post" 
        type="application/atom+xml"
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient"/>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient"/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <atom:entry>
        <atom:id>
            https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/joe%40example.com
        </atom:id>
        <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#emailList.recipient"/>
        <atom:title type="text">joe@example.com</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/joe%40example.com"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/joe%40example.com"/>
        <gd:who email="joe@example.com"/>
    </atom:entry>
    <atom:entry>
        <atom:id>
            https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/susan%40example.com
        </atom:id>
        <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#emailList.recipient"/>
        <atom:title type="text">susan@example.com</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/susan%40example.com"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="https://apps-apis.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/susan%40example.com"/>
        <gd:who email="susan@example.com"/>
    </atom:entry>
</atom:feed>

Sample Failure Response

The XML below shows a sample response to an invalid API request. Possible values for the errorCode attribute are defined in the <error> tag definition. The Java and Python client libraries will return an AppsForYourDomainException while the .NET client library will return an AppsException when it receives an error response from the Provisioning API. That object will be populated with the error information.

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

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

Note: The client library can also return other exceptions for more generic types of errors, such as invalid XML or an error in the path to which you submit a request. For more information, please see the documentation of the ServiceException, which is the base exception class used to identify errors in Google Data API requests.

Appendix D - GData Error Codes

The following list (ordered by error code number) explains the different error codes that you may receive in a Google Apps XML response.

  • UnknownError(1000) - The request failed for an unknown reason.

  • UserDeletedRecently(1100) - The request instructs Google to create a new user but uses the username of an account that was deleted in the previous five days.

  • UserSuspended(1101) - The user identified in the request is suspended.

  • DomainUserLimitExceeded(1200) - The specified domain has already reached its quota of user accounts.

  • DomainAliasLimitExceeded(1201) - The specified domain has already reached its quota of aliases. Aliases include nicknames and email lists.

  • DomainSuspended(1202) - Google has suspended the specified domain's access to Google Apps.

  • DomainFeatureUnavailable(1203) -  This particular feature is not available for the specified domain.

  • EntityExists(1300) - The request instructs Google to create an entity that already exists.

  • EntityDoesNotExist(1301) - The request asks Google to retrieve an entity that does not exist.

  • EntityNameIsReserved(1302) - The request instructs Google to create an entity with a reserved name, such as "abuse" or "postmaster".

  • EntityNameNotValid(1303) - The request provides an invalid name for a requested resource.

  • InvalidGivenName(1400) - The value in the API request for the user's first name, or given name, contains unaccepted characters. Learn more about accepted characters for this field.

  • InvalidFamilyName(1401) - The value in the API request for the user's surname, or family name, contains unaccepted characters. Learn more about accepted characters for this field.

  • InvalidPassword(1402) - The value in the API request for the user's password contains an invalid number of characters or unaccepted characters. Learn more about accepted characters for this field.

  • InvalidUsername(1403) - The value in the API request for the user's username contains unaccepted characters. Learn more about accepted characters for this field.

  • InvalidHashFunctionName(1404) - The specified query parameter value is not valid.

  • InvalidHashDigestLength(1405) - The specified password does not comply with the specified hash function.

  • InvalidEmailAddress(1406) - The specified email address is not valid.

  • InvalidQueryParameterValue(1407) - The specified query parameter value is not valid.

  • TooManyRecipientsOnEmailList(1500) - The request instructs Google to add users to an email list, but that list has already reached the maximum number of subscribers (1000).

Appendix E - Client Library Methods

Function Input Parameters Return Value
createUser String username
String givenName
String familyName
String password
String passwordHashFunction (optional)
Integer quotaLimitInMB (optional)		 UserEntry
retrieveUser String username UserEntry
retrieveAllUsers None UserFeed
retrievePageOfUsers String startUsername UserFeed
updateUser String username
UserEntry userEntry		 UserEntry
suspendUser String username UserEntry
restoreUser String username UserEntry
deleteUser String username None
createNickname String username
String nickname		 NicknameEntry
retrieveNickname String nickname NicknameEntry
retrieveNicknames (for a user) String username NicknameFeed
retrieveAllNicknames (in a domain) None NicknameFeed
retrievePageOfNicknames (in a domain) String startNickname NicknameFeed
deleteNickname String nickname None
createEmailList String emailList EmailListEntry
retrieveEmailLists (for a user) String recipient EmailListFeed
retrieveAllEmailLists None EmailListFeed
retrievePageOfEmailLists String startEmailListName EmailListFeed
deleteEmailList String emailList None
createUser String username
String givenName
String familyName
String password
Integer quotaLimitInMB (optional)		 UserEntry
addRecipientToEmailList String recipientAddress, String emailList EmailListRecipientEntry
retrieveAllRecipients String emailList EmailListRecipientFeed
retrievePageOfRecipients String emailList, String startRecipient EmailListRecipientFeed
removeRecipientFromEmailList String recipientAddress
String emailList		 None