Migrating from the Email Migration API

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 POST https://www.googleapis.com/upload/email/v2/users/userKey/mail 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.

Authorizing requests

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
https://www.googleapis.com/auth/email.migration https://www.googleapis.com/auth/gmail.insert https://www.googleapis.com/auth/gmail.labels

Managing labels

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 labelIds field 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 isInbox or isUnread, the Gmail API supports adding system labels as part of the labelIds field in the Message resource. For example, to add a message as unread in a user’s inbox, you would supply INBOX and UNREAD as label IDs in the labelIds field 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.

Uploading files

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.

Performance differences

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 returns a Message resource that contains the id of 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 5xx errors.
  • 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.