1. Audience
2. Email Migration API feed types
   1. Mail item feed
3. Email Migration API elements reference

Audience

This document is intended for programmers who want to write client applications that can migrate email into Google Apps mailboxes.

It's a reference document; it assumes that you understand the concepts presented in the developer's guide, and the general ideas behind the Google data APIs protocol.

Email Migration API feed types

The Email Migration API defines only one type of feed: the mail item feed. In order to access this feed, your client must first authenticate to your Google Apps domain using ClientLogin (Authentication for Installed Apps).

Mail item feed

The mail item feed is used to insert mail messages into hosted Gmail accounts associated with a Google Apps domain. Its feed URL is:

https://apps-apis.google.com/a/feeds/migration/2.0/yourDomain.com/username/mail

where yourDomain.com is your Google Apps domain name, and username is the username that will own the message after the migration. The username is only a username, not a full email address; for example, if you're migrating messages to be owned by liz@example.com, the username to use is liz. The Content-Type of the POST request must be application/atom+xml or the server will reply with a 415 Unsupported Media Type status code.

The above feed only allows you to insert messages one at a time. In other words, you must make one HTTP request for each mail message you wish to insert. It is recommended instead that you access the batch mail item feed, which allows you to insert many messages in a single HTTP request. The batch feed has the URL:

https://apps-apis.google.com/a/feeds/migration/2.0/yourDomain.com/username/mail/batch

Both of these feeds are write-only; that is, the only request method they support is HTTP POST.

Note: Only domain administrators can migrate mail to accounts other than their own (by specifying a username other than their own to be used in the above URLs). When an end user is migrating mail, the username in the above URLs must be the same as the currently authenticated username.

Email Migration API elements reference

In addition to the standard Google data API elements, the Email Migration API uses the following elements.

For information about the standard data API elements, see the Atom specification and the Common Elements document.

apps:label

A Gmail label to be applied to an inserted mail message.

Properties

Property	Type	Description
@labelName	xsd:string	The name of the label, with any special XML characters escaped.

Example

<apps:label xmlns:apps='http://schemas.google.com/apps/2006' labelName='Friends' />

Schema

namespace apps = "http://schemas.google.com/apps/2006"
start = label 

label =
  element apps:label {
    attribute labelName { xsd:string }
  }

apps:mailItemProperty

A special Gmail property to be applied to an inserted mail message.

Properties

Property	Type	Description
@value	xs:string	Must be one of the following: IS_DRAFT The message should be marked as a draft when inserted. IS_INBOX The message should appear in the Inbox, regardless of its labels. (By default, a migrated mail message will appear in the Inbox only if it has no labels.) IS_SENT The message should be marked as "Sent Mail" when inserted. IS_STARRED The message should be starred when inserted. IS_TRASH The message should be marked as "Trash" when inserted. IS_UNREAD The message should be marked as unread when inserted. Without this property, a migrated mail message is marked as read.

Example

<apps:mailItemProperty xmlns:apps='http://schemas.google.com/apps/2006' value='IS_STARRED' />

Schema

namespace apps = "http://schemas.google.com/apps/2006"
start = mailItemProperty 

mailItemProperty =
  element apps:mailItemProperty {
    attribute value { "IS_DRAFT" | "IS_INBOX" | "IS_SENT" | "IS_STARRED" |
    "IS_TRASH" | "IS_UNREAD" }
  }

apps:rfc822Msg

The RFC 822 content of the mail message to be migrated.

Properties

Property	Type	Description
text()	xs:string	The RFC 822 text content of the mail message.
@encoding?	xsd:string	Valid values are none, which is equivalent to not specifying the encoding attribute, and base64, which indicates that the RFC822 message is encoded in Base64 and should be decoded by the server.

Example

<apps:rfc822Msg xmlns:apps='http://schemas.google.com/apps/2006'>
Received: by 140.23.6.190 with HTTP; Mon, 16 Jul 2007 10:12:26 -0700 (PDT)
Message-ID: &lt;c8acb6980707161012i5d395392p5a6d8d14a8582613@mail.gmail.com&gt;
Date: Mon, 16 Jul 2007 10:12:26 -0700
From: &quot;Elizabeth Bennet&quot; &lt;liz@example.com&gt;
To: &quot;Fitzwilliam Darcy&quot; &lt;darcy@example.com&gt;
Subject: Lunch on Monday
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
Delivered-To: darcy@example.com

This is the body of the email message.  Would you like to have lunch this week?
</apps:rfc822Msg>

Schema

namespace apps = "http://schemas.google.com/apps/2006"
start = rfc822Msg 

rfc822Msg =
  element apps:rfc822Msg {
    attribute encoding { "base64" | "none" }?,
    xsd:string
  }

Back to top