Migrate from the Email Settings API

This document can help migrate your app from the deprecated Email Settings API to the Gmail API.

Authorize requests

Like the Email Settings 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 doesn't let you migrate mail for other users in the domain. Instead, you must use standard service accounts with domain-wide authority that are added to an allowlist in the Google Admin console to generate the appropriate authentication token.

The Email Settings API used the scope:

  https://apps-apis.google.com/a/feeds/emailsettings/2.0/ 
 

The equivalent scopes in the Gmail API are:

  https://www.googleapis.com/auth/gmail.settings.basic 
 https://www.googleapis.com/auth/gmail.settings.sharing 
 

Protocol changes

The Email Settings API uses the XML based GDATA protocol. The Gmail API uses JSON. Since settings are mostly comprised of key-value pairs, payloads are conceptually similar between versions.

Example of creating a label:

 POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="label" value="status updates" />
</atom:entry> 

 POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
   "name": "status updates"
} 

Use the provided client libraries instead of directly implementing the protocol.

Manage labels

To manage labels in the Gmail API, use the labels resource.

Other changes:

• When updating or deleting labels, the Gmail API references labels by ID instead of by name.

Manage filters

To manage filters in the Gmail API, use the settings.filters resource.

Other changes:

• If adding a user label doesn't already exist, it must be explicitly created using the labels.create method.

Manage send-as aliases

To manage send-as aliases in the Gmail API, use the settings.sendAs resource.

Manage web clips

Web Clip settings are not available in the Gmail API.

Manage automatic forwarding

To manage automatic forwarding in the Gmail API, use the settings resource.

Other changes:

• Forwarding addresses must be created and verified prior to use.
• Forwarding addresses can be managed using the settings.forwardingAddresses resource.

Manage POP settings

To manage POP access in the Gmail API, use the settings resource.

Manage IMAP settings

To manage IMAP access in the Gmail API, use the settings resource.

Manage vacation automatic reply settings

To manage vacation automatic reply in the Gmail API, use the settings resource.

Manage signature settings

To manage email signatures in the Gmail API, use the settings.sendAs resource.

Other changes:

• Signatures are now managed per alias.

Manage language settings

To manage language settings in the Gmail API, use the settings resource.

For more information, see Manage language settings .

Manage delegation settings

To manage delegation in the Gmail API, use the settings.delegates resource.

Other changes:

• General
  • To use any of the delegation methods (including settings.delegates.create ) the delegator user must be enabled for Gmail. That means, for example, that the delegator user cannot be suspended in Google Workspace.
  • An email alias cannot be used as the delegate email input for any of the new methods. A delegate user must be referred to by their primary email address.
• settings.delegates.create
  • This method can now be used to create delegate relationships across multiple domains belonging to the same Google Workspace organization.
  • This method can now be used for users which require a password change at their next sign in.
  • If successful, this method returns a settings.delegates resource in the response body, rather than an empty response body.
  • If either of the delegator or delegate users are disabled (for example, suspended in Google Workspace) this method fails with an HTTP 4XX error instead of an HTTP 500 error.
• settings.delegates.delete
  • This method can now be used to delete delegates with any VerificationStatus , rather than just delegates which are accepted or expired .
• settings.delegates.get
  • This is a new method, which might be preferable over the settings.delegates.list method depending on need.

Manage general settings

General settings are not available in the Gmail API.