Google Apps Email Migration API Developer's Guide: Java

estrapadesherbetΛογισμικό & κατασκευή λογ/κού

18 Νοε 2013 (πριν από 3 χρόνια και 6 μήνες)

90 εμφανίσεις

Google Apps Email Migration API Developer's
Guide: Java

Last updated Mar 22nd, 2010 (
see recent changes
)

The Google Apps Email Migration API allows admi
nistrators and users of
Google Apps

to migrate mail
from legacy email systems into their domain's hosted Gmail accounts. Your client application can upload
email messages into these accounts using standard Google Dat
a API feeds.

Note
: This API is only available to Google Apps Premier, Education, and Partner Edition domains, and
cannot be used for migration into Google Apps Standard Edition email or Gmail accounts.

Contents

1.

Audience


2.

Getting Star
ted


3.

Authenticating to the Email Migration service


1.

ClientLogin username/password authentication


4.

Migr
ating email messages


1.

Sample RFC 822 email message


5.

Usage notes and troubleshooting


Audience

This document is intended for programmers who want to write client applications to allow domain
administrators or end users t
o migrate email into Google Apps mailboxes. It provides a series of examples
of basic data API interactions using the Java client library, with explanations. After reading this document,
you may wish to learn more about the underlying protocol (that is, th
e actual XML messages sent and the
HTTP requests used to transmit them) by reading the
protocol section

of this developer's guide.

This docum
ent assumes that you understand the general ideas behind the
Google Data APIs
.

For Apps Email Migration API reference information, see the
reference guide
.

Getting Started

You may want to create a Google Apps account for testing purposes. Email Migration uses Google Apps
Accounts, so if you already have a test Google Apps account, you're all set. Yo
u can create new test
accounts with the Google Apps control panel.

To use the Java client library, you must be running Java 1.5. After
downloading the client library
, you'll
find the

classes you need to get started in the
java/lib/gdata
-
appsforyourdomain
-
1.0.jar

and
java/lib/gdataclient
-
1.0.jar

jar files.

A full working copy of this sample is available in the distribution, under the directory
gdata/java/sample/appsforyourdomain/migrat
ion
. Build and execution instructions are included
in the same directory, in the file

README.txt
. To run the sample, you'll need to modify the following
values in
gdata/java/build.properties:



sample.appsforyourdomain.migration.username
is the username you
use to log in.



sample.appsforyourdomain.migration.password
is the password you use to log in.



sample.appsforyourdomain.migration.domain
is your domain name.

Note
: To migrate email to be owned by a different user, you must be an administrator; you can se
t the
owner with the
--
destination_user

command
-
line option.

To compile the examples in this document into your own code, you'll need to use the following

import
statements:

import com.google.gdata.client.appsforyourdomain.migration.*;

import com.google.gd
ata.data.appsforyourdomain.migration.*;

import com.google.gdata.util.*;

For more information, see
Getting Started with the Java Client Library
.

Authenticating to the Email Migr
ation service

To migrate email messages, you must first authenticate using the ClientLogin authentication system. To
use this system, you submit the email address and password of the domain user or administrator making
the request. The authentication servi
ce returns an authentication token that your client can then send to
the Email Migration API service along with every subsequent request on behalf of that user.

ClientLogin username/password authentication

To authenticate to the Email Migration service usi
ng ClientLogin, create a new
MailItemService
object, and invoke its
setUserCredentials

method, as follows:

MailItemService mailItemService = new MailItemService("exampleCo
-
exampleApp
-
1");

mailItemService.setUserCredentials(userEmail, password);

Replace
use
rEmail

with the email address of the user to authenticate (usually an administrator) and
password

with that user's password.

For more information about the ClientLogin authentication system, see the
Google Account
Authentication for Installed Applications

documentation.

Migrating email messages

To migrate mail messages into a hosted Gmail account, start by creating a
MailItemEntry
object for
each message you're migrating, as demo
nstrated in the following example:

MailItemEntry entry = new MailItemEntry();

Rfc822MediaSource mediaSource = new Rfc822MediaSource(rfc822text);

entry.setMediaSource(mediaSource);


entry.addMailItemProperty(MailItemProperty.STARRED);

entry.addMailItemPrope
rty(MailItemProperty.UNREAD);


entry.addLabel(new Label("Friends"));

entry.addLabel(new Label("Event Invitations"));

Set or add the following properties:



An
Rfc822MediaSource
object, containing the
RFC 82
2

content of the email message. (See
below for an example.)



Optionally, one or more
MailItemProperty

objects, corresponding to properties that the server
should apply to the message when the message is inserted into Gmail. Each
MailItemProperty

must be o
ne of the following:

MailItemProperty.DRAFT


The message should be marked as a draft when inserted.

MailItemProperty.INBOX

The message should appear in the Inbox, regardless of its labels. (By default, a migrated mail
message will appear in the Inbox on
ly if it has no labels.)

MailItemProperty.SENT

The message should be marked as "Sent Mail" when inserted.

MailItemProperty.STARRED

The message should be
starred

when inserted.

Ma
ilItemProperty.TRASH

The message should be marked as "Trash" when inserted.

MailItemProperty.UNREAD

The message should be marked as unread when inserted. Without this property, a migrated mail
message is marked as read.



Optionally, one or more
Label

ob
jects, corresponding to Gmail labels that should be applied to
the message when it is inserted. In the example above, we're specifying that the message should
have the "Friends" and "Event Invitations" labels in Gmail.

It's possible to post a single mail
item entry at a time, but in most cases when you're migrating mail you'll
want to migrate multiple entries at once. We therefore recommend that you take advantage of Java
multi
-
threading capabilities by creating one thread for each user's email and run man
y such threads for
multiple users to increase your migration rate. Note that Email Migration API is rate limited per user and
the server will respond with
503
-

Server Busy

if you migrate too fast. Read the troubleshooting section
at the end of this guide
to handle
503

HTTP return code.

There are two different groups who can migrate mail:



A domain administrator can migrate mail to any mailbox, by specifying a username to be used in
the above code.



An end user can migrate mail only to their own mailbox, and

only if an administrator has enabled
end
-
user access to migration. The username in the above code must be the same as the currently
authenticated username.

If your request is successful, the server returns an
HTTP 200 OK
status code, plus the Atom entry
containing the inserted mail item.

Sample RFC 822 email message

Below is a sample RFC 822 email message that might appear in your multipart HTTP request. For more
information about this format, including an explanation of how each field is interpreted, re
fer to the
official
RFC 822 standard definition
.

Received: by 140.23.6.190 with HTTP; Mon, 16 Jul 2007 10:12:26
-
0700 (PDT)

Message
-
ID: <c8acb6980707161012i5d395392p5a6d8d14a8582613@mail.gmail.com>

Date:

Mon, 16 Jul 2007 10:12:26
-
0700

From: "Elizabeth Bennet" <bennet@example.com>

To: "Fitzwilliam Darcy" <darcy@example.com>

Subject: Lunch on Monday

MIME
-
Version: 1.0

Content
-
Type: text/plain; charset=ISO
-
8859
-
1; format=flowed

Content
-
Transfer
-
Encoding: 7bi
t

Content
-
Disposition: inline

Delivered
-
To: darcy@example.com


This is the body of the email message. Would you like to have lunch this week?

Note
: Each line in an RFC 822 message should be terminated by a CR+LF (that is,
"
\
r
\
n"
) style newline.
The RFC 82
2 message should be UTF
-
8 text.

Usage notes and troubleshooting

Here are some notes about limits and error situations:



You may send a maximum of 32MB of data in each HTTP
POST

request.



The Gmail server may reject malformed messages. In particular, make su
re that each message has
at least the
From:, To:
, and
Date:

header fields required by the RFC822 specification. If a
message is rejected as malformed, you'll receive a
400 Bad Request
HTTP return code.



If your client exceeds the maximum allowed rate of me
ssage uploads per second, you will recieve
503 Service Unavailable
. If you receive that status code, then retry uploading the failed entry.
We recommend using an exponential backoff strategy for this process. For example, you might
wait thirty seconds and
retry the upload; then if your request still returns
503
s, wait 60 seconds
before trying again, and so on.

Google Apps Email Migration API Developer's
Guide: Protocol

Last updated Mar 22nd, 2010 (
see recent changes
)

The Google Apps Email Migration API allows administrators and users of
Google Apps

to migrate mail
from legacy email systems into their domain's hoste
d Gmail accounts. Your client application can upload
email messages into these accounts using standard Google Data API feeds.

Note
: This API is only available to Google Apps Premier, Education, and Partner Edition domains, and
cannot be used for migration
into Google Apps Standard Edition email or Gmail accounts.

Contents

1.

Audience


2.

Getting Started


3.

Authenticating to the Email Migration service


1.

ClientLogin username/password authentication


4.

Migrating email messages


1.

Sample RFC 822 email message


5.

Usage notes and troubleshoo
ting


Audience

This document is intended for programmers who want to write client applications to allow domain
administrators or end users to migrate email into Google Apps mailboxes. It provides some background
on the capabilities of the Email Migration
API, as well as examples of basic data API interactions using
raw XML and HTTP, with explanations. After reading this document, you may wish to learn more about
interacting with the API using our
client libraries

by reading the language
-
specific sections of this
developer's guide.

This document assumes that you understand the general ideas behind the
Google Data AP
Is
.

For Apps Email Migration API reference information, see the
reference guide
.

Getting Started

You may want to create a Google Apps account for testing pu
rposes. Email Migration uses Google Apps
Accounts, so if you already have a test Google Apps account, you're all set. You can create new test
accounts with the Google Apps control panel.

Authenticating to the Email Migration service

To migrate email messag
es, you must first authenticate using the ClientLogin authentication system. To
use this system, you submit the email address and password of the domain user or administrator making
the request. The authentication service returns an authentication token th
at your client can then send to
the Email Migration API service along with every subsequent request on behalf of that user.

ClientLogin username/password authentication

To obtain an authentication token, submit an HTTP

POST

request to the following URL:

ht
tps://www.google.com/accounts/ClientLogin

The
POST

body should contain a set of query parameters, as described in the following table. They should
look like parameters passed by an HTML form, using the
application/x
-
www
-
form
-
urlencoded

content
type.

Parame
ter

Description

Email

The email address of the domain administrator or user.

Passwd

The password for the domain administrator or user.

accountType

The string

HOSTED,

which indicates that this is an authorization for a hosted Google
Account.

service

The

string
apps
, which is the service name for Google Apps.

If the authentication request fails, the server returns an HTTP
403 Forbidden
status code.

If the request succeeds, then the server returns an HTTP
200 OK

status code, plus three long
alphanumeric c
odes in the body of the response:

SID, LSID
, and

Auth
. The

Auth
value is the
authentication token that you'll send to the Email Migration API with your request, so keep a copy of that
value. You can ignore the
SID
and
LSID
values.

Since all requests to Ema
il Migration API feeds require authentication, you have to set the
Authorization

header in the request, using the following format:

Authorization: GoogleLogin auth=yourAuthToken

Where
yourAuthToken
is the
Auth

string returned by the authentication request.

Note
: Authentication tokens expire after 24 hours. If an authenticated request fails, it may mean you need
to acquire another token by posting the credentials to the ClientLogin URL again.

We recommend that you keep the token in memory rather than writing

it to a file.

For information on how to handle a CAPTCHA challenge while obtaining an authentication token, see
the following
FAQ
.

Migrating email messages

To migrate m
ail messages into a hosted Gmail account, issue multipart POST requests, where the first
part contains an Atom entry specifying the message properties and labels, and the second part contains
the complete
RFC 822

message as UTF
-
8 text.

Note:
Base64 encoded
RFC 822

message capability is now deprecated. The
RFC 822

message should be
UTF
-
8 text.

HTTP Hea
der:

Content
-
Type: multipart/related;boundary="
----
=_Part_0_25934938.1266495790627"

HTTP Body:

------
=_Part_0_25934938.1266495790627

Content
-
Type: application/atom+xml


<?xml version=&apos;1.0&apos; encoding=&apos;UTF
-
8&apos;?><entry
xmlns=&apos;http://www
.w3.org/2005/Atom&apos;


xmlns:apps=&apos;http://schemas.google.com/apps/2006&apos;>

<category scheme=&apos;http://schemas.google.com/g/2005#kind&apos;
term=&apos;http://schemas.google.com/apps/2006#mailItem&apos;/>

<atom:content xmlns:atom=&apos;http://ww
w.w3.org/2005/Atom&apos;
type=&apos;message/rfc822&apos;/>

<apps:mailItemProperty value=&apos;IS_INBOX&apos;/>

</entry>


------
=_Part_0_25934938.1266495790627

Content
-
Type: message/rfc822


MIME
-
Version: 1.0

Received: by 10.216.52.85 with HTTP; Thu, 18 Feb
2010 04:16:09
-
0800 (PST)

Date: Thu, 18 Feb 2010 17:46:09 +0530

Delivered
-
To: audit1@yourdomain.com

Message
-
ID: <5db9e26e1002180416n9436618p2e828b22753764f9@mail.gmail.com>

Subject: Hello Multipart HTTP

From: anirudh dewani <audit1@yourdomain.com>

To: audi
t user <audit2@yourdomain.com>

Content
-
Type: multipart/alternative; boundary=0016e64c1c48a28a49047fdeee47


--
0016e64c1c48a28a49047fdeee47

Content
-
Type: text/plain; charset=ISO
-
8859
-
1


This is a test mail using multipart HTTP requests for Email Migration AP
I.


Thanks.


--
0016e64c1c48a28a49047fdeee47

Content
-
Type: text/html; charset=ISO
-
8859
-
1


This is a test mail using multipart HTTP requests for Email Migration
API.<div><br></div><div>Thanks.</div>


--
0016e64c1c48a28a49047fdeee47
--

------
=_Part_0_25934938.1
266495790627
--

Include the following elements in the Atom entry:



Optionally, one or more
<apps:mailItemProperty>
elements, corresponding to properties that
the server should apply to the message when the message is inserted into Gmail. The
value

attribute
for each element 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.



Optionally, one or more
<apps:label>

elements, corresponding to Gmail labels that should b
e
applied to the message when it is inserted. In the example above, we're specifying that the
message should have the "Friends" and "Event Invitations" labels in Gmail.

Note:
Batch insertion mode has been deprecated. We recommend that you use multi
-
thread
ed clients (one
thread per user) with multipart HTTP requests to fasten the process.

There are two different groups who can migrate mail:



A domain administrator can migrate mail to any mailbox, by specifying a username to be
used in the above URL.



An end
user can migrate mail only to their own mailbox, and only if an administrator has
enabled end
-
user access to migration. The username in the above URL must be the same as
the currently authenticated username.

If you are an end user migrating mail to your o
wn mailbox, you can also use the "default feed" for
convenience:

POST https://apps
-
apis.google.com/a/feeds/migration/2.0/default/mail

If your request is successful, the server returns a feed containing the inserted mail item entry.

Sample RFC 822 email me
ssage

Below is a sample
RFC 822

email message. We recommend that you use a public library such as
JavaMail

to construct these messages. For more info
rmation about this format, including an explanation
of how each field is interpreted, refer to the official
RFC 822 standard definition
.

MIME
-
Version: 1.0

Received: by 10.216.170.147 with HTTP; Fri, 26 M
ar 2010 12:54:28
-
0700 (PDT)

Date: Sat, 27 Mar 2010 03:54:28 +0800

Delivered
-
To: darcy@example.com

Message
-
ID: <203b3a4f1043461254v14855b71w9ce59e3abcf45962@mail.gmail.com>

Subject: hello multipart

From: Elizabeth Bennet <bennet@example.com>

To: Fitzwillia
m Darcy <darcy@example.com>

Content
-
Type: multipart/alternative; boundary=000e0cdf7740f8017e0482b9877a


--
000e0cdf7740f8017e0482b9877a

Content
-
Type: text/plain; charset=ISO
-
8859
-
1


howdy multipart!


--
000e0cdf7740f8017e0482b9877a

Content
-
Type: text/html; c
harset=ISO
-
8859
-
1


howdy multipart!


--
000e0cdf7740f8017e0482b9877a
--

Note
: Each line in an
RFC 822

message should be terminated by a CR+LF (that is,
"
\
r
\
n"
) style newline.

Usage notes and troubleshootin
g

Here are some notes about limits and error situations:



You may send a maximum of 32MB of data in each HTTP

POST

request.



The Gmail server may reject malformed messages. In particular, make sure that each
message has at least the
From:
,

To:
, and
Date:
he
ader fields required by the RFC822
specification. If a message is rejected as malformed, you'll receive a
400 Bad Request

HTTP
return code.



If your client exceeds the maximum allowed rate of message uploads per second, you will
recieve
503 Service Unavail
able
. If you receive that status code, then retry uploading the
failed entry. We recommend using an exponential backoff strategy for this process. For
example, you might wait thirty seconds and retry the upload; then if your request still returns
503
s, wai
t 60 seconds before trying again, and so on.