This document covers the key differences between the deprecated Email Migration API and the Gmail API. You can use this guide to help migrate your app to the Gmail API.
The Gmail API supports the same features as the Email Migration API and provides
many additional utilities for managing mail and labels. For most use cases, you
can replace the
request endpoint of the Email Migration API with the
messages.import request method
in the Gmail API. This method provides the same features such as, conversation
threading, spam scanning, and antivirus scanning. The following sections
highlight some of the key differences between the APIs.
Like the Email Migration API, the Gmail API uses the OAuth 2.0 protocol to authorize requests. One key difference is that Gmail API permissions are scoped to an individual user, rather than to the entire domain. This means authorizing a domain administrator account does not allow you to migrate mail for other users in the domain. Instead, you must use standard service accounts with domain-wide authority that are whitelisted in the Admin console to generate the appropriate authentication token.
The following table maps the Email Migration scope to its Gmail API scope equivalents.
|Email Migration API v2||Gmail API|
Like the Email Migration API, the Gmail API supports adding labels to messages during import. However, there are some notable differences:
- The Gmail API adds labels by ID instead of by name. These labels can be
specified in the
labelIdsfield of the Message resource supplied as part of the request body.
- If a user label does not already exist, it must be explicitly created using the labels.create method. Labels are not automatically created during import with the Gmail API.
- In contrast to the Email Migration API, which had separate request properties
for system labels such as
isUnread, the Gmail API supports adding system labels as part of the
labelIdsfield in the Message resource. For example, to add a message as unread in a user’s inbox, you would supply
UNREADas label IDs in the
labelIdsfield of the request. If no label IDs are supplied, the message will only appear under All Mail.
For more information on label management with the Gmail API, see Managing Labels.
Similar to the Email Migration API, the Gmail API also supports media upload for uploading large emails; however, this is not required for messages under 5 MB.
There are several performance differences between the Email Migration API and the Gmail API. Some of the notable changes:
- For successful requests, instead of returning an empty response the Gmail API
Message resource that contains the
idof the newly imported message.
- The Gmail API guarantees that messages are immediately delivered to the user’s mailbox.
- Because messages are delivered immediately to users' mailboxes, end-to-end request times for the Gmail API are slower. However, the overall throughput for any single user should be similar. The Email Migration API would complete requests faster, but then return 503 HTTP errors to throttle subsequent requests for the next 1-3 seconds. In contrast, the Gmail API completes the messages.import request in 1-3 seconds but upon success the next request can be executed immediately. Your application can migrate users in parallel, or use two threads to migrate a single user's mailbox, to achieve higher overall system throughput.
- Requests can be sent in immediate successon when there are no errors: it is
not necessary to explicitly rate limit to 1 request/user/sec. Clients should
implement retries with exponential backoff in the case of temporary errors
such as, HTTP 429 errors, HTTP 403 quota errors, or HTTP
- Overall throughput for the API has a maximum of 1 QPS on average, but in practice this throughput may be lower, decreasing with increased load for the user and the system.
- The Gmail API has no domain-wide migration quota limitations, so migrating users in parallel is recommended when you need higher overall throughput.