This document covers the key differences between the Email Settings API and the Gmail API. You can use this guide to help migrate your app to the Gmail API.
Authorizing 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 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 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:
Email Settings API
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>
Gmail API
POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
"name": "status updates"
}
Use the provided Client libraries instead of directly implementing the protocol.
Managing labels
To manage labels in the Gmail API, use the Labels resource.
Old setting | New setting | Notes |
---|---|---|
labelId | id | |
label | name | |
unreadCount | messagesUnread | |
visibility | labelListVisibility | SHOW is now labelShow HIDE is now labelHide |
Other changes:
- When updating or deleting labels, the Gmail API references labels by ID instead of by name.
Managing filters
To manage filters in the Gmail API, use the Filters resource.
Old setting | New setting | Notes |
---|---|---|
from | criteria.from | |
to | criteria.to | |
subject | criteria.subject | |
hasTheWord | criteria.query | |
doesNotHaveTheWord | criteria.negatedQuery | |
hasAttachment | criteria.hasAttachment | |
shouldArchive | action.removeLabelIds | Use INBOX as the label ID |
shouldMarkAsRead | action.removeLabelIds | Use UNREAD as the label ID |
shouldStar | action.addLabelIds | Use STARRED as the label ID |
label | action.addLabelIds | Use the ID of the label to add |
forwardTo | action.forward | |
shouldTrash | action.addLabelIds | Use TRASH as the label ID |
neverSpam | action.removeLabelIds | Use SPAM as the label ID |
Other changes:
- If adding a user label does not already exist, it must be explicitly created using the labels.create method.
Managing send-as aliases
To manage send-as aliases in the Gmail API, use the SendAs resource.
Old setting | New setting |
---|---|
name | displayName |
address | sendAsEmail |
replyTo | replyToAddress |
makeDefault | isDefault |
Managing web clips
Web Clip settings are no longer available via the API.
Managing auto-forwarding settings
To manage auto-forwarding in the Gmail API, use the Settings resource.
Old setting | New setting | Notes |
---|---|---|
enable | enabled | |
forwardTo | emailAddress | |
action | disposition | KEEP is now leaveInInbox ARCHIVE is now archive DELETE is now trash MARK_READ is now markRead |
Other changes:
- Forwarding addresses must be created and verified prior to use
- Forwarding addresses can be managed via the ForwardingAddresses resource.
Managing POP settings
To manage POP access in the Gmail API, use the Settings resource.
Old setting | New setting | Notes |
---|---|---|
enable | accessWindow | Disabled when set to disabled |
enableFor | accessWindow | ALL_MAIL is now allMail MAIL_FROM_NOW_ON is now fromNowOn |
action | disposition | KEEP is now leaveInInbox ARCHIVE is now archive DELETE is now trash MARK_READ is now markRead |
Managing IMAP settings
To manage IMAP access in the Gmail API, use the Settings resource.
Old setting | New setting |
---|---|
enable | enabled |
Managing vacation auto-reply settings
To manage vacation auto-reply in the Gmail API, use the Settings resource.
Old setting | New setting |
---|---|
contactsOnly | restrictToContacts |
domainOnly | restrictToDomain |
enable | enableAutoReply |
endDate | endTime |
message | responseBodyHtml responseBodyPlainText |
startDate | startTime |
subject | responseSubject |
Managing signature settings
To manage email signatures in the Gmail API, use the SendAs resource.
Old setting | New setting |
---|---|
signature | signature |
Other changes:
- Signatures are now managed per alias.
Managing language settings
To manage language settings in the Gmail API, use the Settings resource.
Old setting | New setting |
---|---|
language | displayLanguage |
Please refer to the Managing Language Settings guide for more information.
Managing delegation settings
To manage delegation in the Gmail API, use the Delegates resource.
Old setting | New setting |
---|---|
address | delegateEmail |
status | verificationStatus |
Other changes:
- General
- To use any of the delegation methods (including 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.
- 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 Users.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.
- delegates.delete
- This method can now be used to delete delegates with any
verificationStatus,
rather than just delegates which are
accepted
orexpired
.
- This method can now be used to delete delegates with any
verificationStatus,
rather than just delegates which are
- delegates.get
- This is a new method, which might be preferable over the delegates.list method depending on need.
Managing general settings
General settings are no longer available via the API.