Google Apps Provisioning API V1.0 Reference

To access Google Apps, an end user must have a Google-hosted account. This document describes the Google Apps Provisioning API, which enables Google partners to create, retrieve, update and delete user accounts. Partners can also use the API to create email accounts, user aliases and mailing lists.

This document explains the formats for all of the different types of API requests as well as the format of the API's XML responses to those requests.

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.

To use the API, you will send HTTP POST 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, email aliases and mailing lists. Note: The Google Apps online control panel refers to aliases as nicknames and to mailing lists as email lists.

This section explains the different types of operations that the API supports. The Submitting API Requests section identifies the URL that corresponds to each API operation.

• Create operations enable partners to add new user accounts, email aliases and mailing lists. The Submitting API Requests section identifies the URL that corresponds to each API operation.

• Retrieve operations allow Google partners to request and obtain information about user accounts, email aliases and mailing lists.

  The XML for a retrieve request identifies a queryKey, which indicates the type of resource that is being retrieved. A retrieve request also specifies a queryData value, which identifies the particular resource being retrieved. Google will locate the resource identified in your request and return the corresponding information in the API response.

• Update operations allow Google partners to modify information about user accounts and mailing lists. Note: The API does not support updates to email aliases. The API supports the following types of updates:

  • First name changes
  • Last name changes
  • Password changes
  • Enable/disable a user's access to email
  • Adding users to an email list
  • Removing users from an email list

  Update requests also use the <queryKey> and <queryData> XML elements to identify the resource being updated. When you submit an update request, Google will locate the appropriate resource and update it to match the information in the <UpdateSection> node of the XML request.

• Delete operations allow Google partners to delete user accounts, email aliases and mailing lists.

  Like retrieve and update requests, delete requests use the <queryKey> and <queryData> XML elements to identify the resource being deleted. Google will locate the resource specified in your request, delete it, and return a success or failure message in the API response.

  After you delete an account, you must wait five days before reassigning the username for the deleted account to another account.

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

All of your API requests must be sent over HTTPS. In addition, all data sent to the API will be delivered using HTTPS POST to ensure the security of that data.

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:

The following guidelines apply to the request:

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

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

  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 in the POST body 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 SID value on that page. You need to extract the token from the page and then submit that token in API requests.

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.

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 accountType, 
# Email and Passwd variables.
my $response = $lwp_object->post( $url,
            [ 'accountType' => 'HOSTED',
              'Email' => 'admin_email@example.com',
              'Passwd' => 'admin_password'
            ]
);

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/^SID=(.+)$/) {
        $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 admin account.

To execute an operation using the API, you need to POST an appropriately formatted XML document to the URL that corresponds to that operation. The following table lists the different operations available in version 1.0 of the API. The table also identifies the URL to which you would submit an API request for each operation.

The following sections contain sample API requests to Create, Retrieve, Update and Delete user accounts, email aliases and mailing lists:

• User Accounts
• Email Aliases
• Mailing Lists

These sections provide a sample API request for each operation that you can perform using the API. These sections also discuss the XML tags used in each API request. Definitions for these XML tags are provided in Appendix A - XML Tag Definitions for API Requests.

As described earlier, your users must have a user account to access Google Apps for your domain. The following subsections show the proper API request syntax for creating, updating, retrieving and deleting Google user accounts.

*Note: Each command marked with an asterisk (*) updates an account in a different way.

This example shows a request to create a user account.

In this request, the value of the <type> tag is Account. The <CreateSection> tag has four required subtags:

• <firstName>
• <lastName>
• <password>
• <userName>

The <CreateSection> tag in the example also contains the <quota> tag. Please note that this tag, which is used in a request to create an account with email, is required for domains that have the ability to customize the disk space quota allocated to their email accounts.

This example shows a request to update a user account.

The URL to use for this request is:

In this request, the value of the <type> tag is Account. In addition, the queryKey value (userName) indicates that Google Apps should look up a user account, and the queryData value identifies the account to be located (john-doe).

The <UpdateSection> tag in this request has three optional subtags. A request may include any combination of the three subtags and only the corresponding values will be updated.

• <firstName>
• <lastName>
• <password>

This example shows a request to lock, or disable, a user's email account.

The URL to use for this request is:

In this request, the value of the <type> tag is Account. In addition, the queryKey value (userName) indicates that Google Apps should look up a user account, and the queryData value identifies the account to be located (john-doe).

The <UpdateSection> tag in this request has one required subtag:

• <accountStatus> - Valid values for this tag are locked, which disables the specified email account, and unlocked, which enables the specified email account. An end user cannot log in to a disabled account, and email sent to the account will not be delivered.

This example shows a request to retrieve information about a user account.

The URL to use for this request is:

API requests to retrieve user accounts, email aliases and mailing lists all use the same XML structure. The only differences between the requests are the values of the <type>, <queryKey> and <queryData> tags.

To retrieve information about a user account, set the value of the <type> tag to Account and the value of the <queryKey> tag to userName. Also set the value of the <queryData> tag to the name of the user account to be retrieved.

This example shows a request to delete a user account.

The URL to use for this request is:

API requests to delete user accounts, email aliases and mailing lists all use the same XML structure. The only differences between the requests are the values of the <type>, <queryKey> and <queryData> tags.

To delete a user account, set the value of the <type> tag to Account and the value of the <queryKey> tag to userName. Also set the value of the <queryData> tag to the name of the user account to be deleted.

Email aliases enable a single email account to receive email sent to more than one email address. However, an alias should not be considered an alternate userName for an account. For example, a user cannot log in to an account using an alias name.

The following subsections demonstrate the proper syntax for creating, retrieving and deleting aliases through the API. (Aliases cannot be updated.)

This example shows a request to create an email alias.

In this request, the value of the <type> tag is Alias. The <CreateSection> tag has two required subtags:

• <userName> - This value identifies the user to whom the alias is assigned.

• <aliasName> - This value identifies the name of the alias to be created.

This example shows a request to retrieve information about an email alias.

The URL to use for this request is:

API requests to retrieve user accounts, email aliases and mailing lists all use the same XML structure. The only differences between the requests are the values of the <type>, <queryKey> and <queryData> tags.

To retrieve information about an email alias, set the value of the <type> tag to Alias and the value of the <queryKey> tag to aliasName. Also set the value of the <queryData> tag to the name of the email alias to be retrieved.

This example shows a request to delete an email alias.

The URL to use for this request is:

API requests to delete user accounts, email aliases and mailing lists all use the same XML structure. The only differences between the requests are the values of the <type>, <queryKey> and <queryData> tags.

To delete an email alias, set the value of the <type> tag to Alias and the value of the <queryKey> tag to aliasName. Also set the value of the <queryData> tag to the name of the email alias to be deleted.

Mailing lists enable many different users to receive email sent to a single email address. The following subsections show the proper API request syntax for creating, updating, retrieving and deleting mailing lists.

Note: Mailing lists are always empty when you create them. After creating a mailing list, you will need to update the mailing list to add users to it. A user must already have a user account before she can be added to a mailing list.

This example shows a request to create a mailing list.

In this request, the value of the <type> tag is MailingList. In addition, the <CreateSection> tag has one required subtag (<mailingListName>), which identifies the list to be created.

This example shows a request to update a mailing list.

The URL to use for this request is:

In this request, the value of the <type> tag is MailingList. In addition, the queryKey value (mailingListName) indicates that Google Apps should look up a mailing list, and the queryData value identifies the mailing list to be located (sales-europe).

The <UpdateSection> tag contains two required subtags:

• <userName> - This tag identifies the user who is being added to or removed from the mailing list.

• <listOperation> - This tag indicates whether the user should be added to the list or removed from the list. Valid values for this tag are add and remove.

This example shows a request to retrieve information about a mailing list.

The URL to use for this request is:

API requests to retrieve user accounts, email aliases and mailing lists all use the same XML structure. The only differences between the requests are the values of the <type>, <queryKey> and <queryData> tags.

To retrieve information about a mailing list, set the value of the <type> tag to MailingList and the value of the <queryKey> tag to mailingListName. Also set the value of the <queryData> tag to the name of the mailing list to be retrieved.

This example shows a request to delete a mailing list.

The URL to use for this request is:

API requests to delete user accounts, email aliases and mailing lists all use the same XML structure. The only differences between the requests are the values of the <type>, <queryKey> and <queryData> tags.

To delete a mailing list, set the value of the <type> tag to MailingList and the value of the <queryKey> tag to mailingListName. Also set the value of the <queryData> tag to the name of the mailing list to be deleted.

The API will log each operation in which a user account is created, updated or deleted for your domain. Logs are available on a per-domain basis.

Note: Usernames and passwords for your accounts are not recorded in logs.

The API returns an XML response to all API requests that are sent to a valid API URL. The XML response indicates whether Google processed the API request successfully. (Google does not return XML responses to requests sent to invalid API URLs.)

• If a response is processed successfully, the <status> tag in the XML response will contain the text Success(2000).

• If a request is not processed successfully, the <status> tag in the XML response will contain the text Failure(2001) and the <reason> tag will contain an error code that explains the cause of the failure.

The following list contains the XML tags that may appear in an API response. These tags are defined in Appendix B - XML Tag Definitions for API Responses. In addition, the Sample API Responses section of this document contains sample XML responses for both successful and unsuccessful API requests.

* Note: The URLs that correspond to each API operation are listed in the Submitting API Requests section of this document. If you send an API request to a URL that is not in that list, Google will return an HTTP 301 response code, indicating that the requested URL has been permanently redirected. If you receive an HTTP 301 response code from the API, please verify that you are sending your POST requests to a valid API URL.

The following examples demonstrate the syntax used for API XML responses.

• Sample Failure Response
  <?xml version="1.0" encoding="UTF-8"?>
  <hs:rest xmlns:hs="google:accounts:rest:protocol">
      <hs:status>Failure(2001)</hs:status>
      <hs:reason>AuthenticationFailure(1006)</hs:reason>
      <hs:extendedMessage>Supplied user is not an admin, cannot use API.</hs:extendedMessage>
      <hs:result></hs:result>
  </hs:rest>

• Sample Success Response

  The syntax of an API response is identical for Create, Update and Delete requests. This syntax is shown below in example 1. Responses to Retrieve requests use some additional tags. Those tags vary depending on whether the API request was for user account or mailing list information. The syntax for returning user account information is shown in example 2, and the syntax for returning mailing list information is shown in example 3.

  Example 1: Successful Response to Create, Update or Delete Request

  <?xml version="1.0" encoding="UTF-8"?>
  <hs:rest xmlns:hs="google:accounts:rest:protocol">
      <hs:status>Success(2000)</hs:status>
      <hs:reason>N/A</hs:reason>
      <hs:extendedMessage>N/A</hs:extendedMessage>
      <hs:result>N/A</hs:result>
  </hs:rest>

  Example 2: Successful Response to Retrieve Account Information

  <?xml version="1.0" encoding="UTF-8"?>
  <hs:rest xmlns:hs="google:accounts:rest:protocol">
      <hs:status>Success(2000)</hs:status>
      <hs:reason>N/A</hs:reason>
      <hs:extendedMessage>N/A</hs:extendedMessage>
      <hs:result>N/A</hs:result>
      <hs:RetrievalSection>
          <hs:firstName>John</hs:firstName>
          <hs:lastName>Doe</hs:lastName>
          <hs:userName>john-doe</hs:userName>
          <hs:accountStatus>unlocked</hs:accountStatus>
          <hs:aliases>
              <hs:alias>johnnyd</hs:alias>
          </hs:aliases>
          <hs:emailLists>
              <hs:emailList>sales-europe</hs:emailList>
              <hs:emailList>sales-uk</hs:emailList>
          </hs:emailLists>
      </hs:RetrievalSection>
  </hs:rest>

  Example 3: Successful Response to Retrieve Mailing List Information

  <?xml version="1.0" encoding="UTF-8"?>
  <hs:rest xmlns:hs="google:accounts:rest:protocol">
      <hs:status>Success(2000)</hs:status>
      <hs:reason>N/A</hs:reason>
      <hs:extendedMessage>N/A</hs:extendedMessage>
      <hs:result>N/A</hs:result>
      <hs:RetrievalSection>
          <hs:emailAddresses>
              <hs:emailAddress>john-doe@example.com</hs:emailAddress>
              <hs:emailAddress>mary-smith@example.com</hs:emailAddress>
              <hs:emailAddress>steve-jones@example.com</hs:emailAddress>
          <hs:/emailAddresses>
      </hs:RetrievalSection>
  </hs:rest>

The following appendixes contain definitions of the XML tags used in API XML requests and responses.

Note: The tags in both appendixes are presented in alphabetical order. However, in API requests, XML tags must appear in a specific sequence. The sections on sample API requests for user accounts, email aliases and mailing lists show the sequence in which tags must appear in your API requests.

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