This API is deprecated and will be turned down on October 16, 2019. Migrate to the Gmail API as soon as possible to avoid disruptions to your application.

Usage Limits and Quotas

Limits and quotas protect the Google infrastructure from an automated process that uses the Email Settings API in an inappropriate way. Excessive requests from an API might result from a harmless typo, or may result from an inefficiently designed system that makes needless API calls. Regardless of the cause, blocking traffic from a specific source once it reaches a certain level is necessary for the overall health of the G Suite system. It ensures that one developer's actions cannot negatively impact the larger community.

In the unlikely event that your API request fails, you'll receive an HTTP status code response. A status code of 403 has error information about incorrect input, and an HTTP status code of 503 has error information indicating which API quotas have been exceeded. These responses allow your custom application to detect these errors and take appropriate action.

If your requests need to be completed in a fixed period of time, send your requests in parallel or use multiple threads in your Java or C# application. An example of parallel requests is requesting small batches of emails from different users rather than adding or removing lots of emails from one user simultaneously. In the case of threads, try starting with 10 threads, one thread per user email. Note, the thread recommendation has trade-offs and is not useful for all API situations. If the number of requests gets too high, quota errors will occur. Another trade-off example is the Email Settings API's quota for the maximum overall message upload rate. The upload rate is one API request - per second - per user, no matter how many threads are making upload requests.

For all errors that are time based (maximum of N things for N seconds per thread), especially the 503 status code errors, we recommend your code catch the exception and, using an exponential backoff algorithm, wait for a small delay before retrying the failed call. An Email Settings API example for one thread is to wait 5 seconds and retry the failed call. If the request is successful, repeat this pattern for the other threads. If the second request is not successful, your application should scale back on the frequency of the request until a call is successful. For example, increase the initial 5 second delay to 10 seconds and retry your failed call again. Also, decide on a retry limit. For example retry a request 5 to 7 times with different delay times before your application returns an error to the user.

API Limit Categories Limits
Email settings, for a new account If you are changing the settings for a recently provisioned account, you should wait at least one second before making your API calls. This insures that the email account is fully provisioned and activated before any attempt is made to change a user's email settings.
Email settings, for a new delegate Depending on the network, there could be a delay of a minute or less before a new delegate is added. We recommend a delay between the creation of more than one delegate or between the retrieval of newly created delegates.
Language settings It may take several hours for new language settings to be applied.
API Quota Categories Quotas
ClientLogin authentication tokens Valid for 24 hours. The error is '401 token expired'
Error messages To see some common errors, along with the output produced to help diagnose them, see the common errors section of this guide.
Delegation, max delegates per user Each user delegating Gmail access is allowed a maximum of 25 delegates.
Filter, the forwardTo action A filter's forwardTo field must hold a validated email address or an error is returned.
You can create an unlimited number of filters, but, only 20 filters can forward to other addresses.
Filter, settings A filter name can be any HTML encoded string up to 225 characters.

Filter values are case insensitive. For example, HelpDesk@example.com is filtered the same as helpdesk@example.com.

Filters can use Boolean operators. See Boolean operators.

Note: When specifying the subject or words for a filter to match, many non-alphanumeric characters cannot be used. These include square brackets( [ ] ), parentheses ( ), currency symbols, the ampersand ( & ), pound sign ( # ), and the asterisk ( * ).

Filter, the Subject setting A filter's Subject field can be any HTML encoded string up to 1000 characters.
Forwarding, in a non-active account Changes to forwarding settings are only made active once the user agrees to Google's terms of service. Attempting to change the forwarding settings before the user agrees to the terms of service will result in the updated settings being stored, but not made active. Once the user agrees to the terms, then the stored settings will be made active. This prevents users from using the forwarding feature until they have agreed to the terms, but does not prevent administrators from changing the forwarding settings before the user's account has been made active.
Forwarding, valid email address   An email address used in the Forwarding setting must be valid. A valid value of forwardTo is an email address that has been already verified to be used as a forwarding address in the email account, or one that fulfills one of the following criteria:
  • The email address is in the account's primary domain or a subdomain
  • The email address is a domain alias of the account's primary domain

If the value of forwardTo doesn't adhere to one of these rules, setting up of forwarding using the API will fail.

Note: Forwarding and updating settings are not active until the user has agreed to the account's terms of service. Although an administrator can change these properties at any time, the changed settings will be stored and will not take effect until the user has agreed to the account's terms of service.

 Label settings Email has a 225 character limit per label.

There is no limit to the number of emails assigned to a label.

Label names must not conflict with reserved label names in any language for which Google Mail is available. In English, these include inbox, unread, drafts, sent, chat, muted, spam, trash, popped, and contactcsv.

Note: The caret character (^) is not allowed in a label string.

 Language settings  The Language settings suppors the RFC 3066 standard format, for example en-GB, fr, or ja for British English, French, or Japanese.
  • The RFC 3066 Language Tag format begins with a primary subtag which is optionally followed with more subtags separated by hyphen signs (-).
  • In most cases, the primary subtag is sufficient to specify a language (de, ko, or hi for German, Korean, or Hindi)
  • In some cases, such as English or Chinese, a subtag needs to show which variant of the language to display (en-US or en-GB for US or British English, and zh-CN or zh-TW for simplified or traditional Chinese).
  • Although there are many regional subtags used to represent a certain language, the Email Settings API only accepts the specific tags. See the complete list.
Page size setting The possible number of conversations to be shown per page are 25, 50 or 100.
POP3 and IMAP, in a non-active account Changes to POP and IMAP settings are only made active once the user agrees to Google's terms of service. Attempting to change these settings before the user agrees to the terms of service will result in the updated settings being stored, but not made active. Once the user agrees to the terms, then the stored settings will be made active. This prevents users from using the POP and IMAP features until they have agreed to the terms, but does not prevent administrators from changing these settings before the user's account has been made active.
POP3 and IMAP settings These settings are not active until the user has agreed to the account's terms of service. Although an administrator can change these properties at any time, the changed settings will be stored and will not take effect until the user has agreed to the account's terms of service.
'Send-As' alias setting, size of alias' name An email 'Send-As' alias name can be any HTML encoded string up to 250 characters.
'Send-As' alias setting, verified The verified property shows if the ownership of the email address's domain has been verified. This property must be true (verified), before the Send-As alias address can work.
Signature setting and retrieving When setting an email signature, the plain text string can be up to 2000 characters. An empty string ("") results in no signature, meaning the signature feature is disabled. When setting or retrieving a signature, the API accepts plain or HTML-encoded strings.
Vacation-responder setting The vacation-responder's subject setting can be any HTML encoded string up to 500 characters.

The responder's message body can be any HTML encoded string up to 100KB of characters.

Note: If a contact sends you several messages during a vacation period, the responder's automated reply is sent at most once every 4 days.

Other Types of Limits Limitations and Guidelines
 abuse@example.com and postmaster@example.com  For email in general, Google monitors the postmaster and abuse addresses for problems with your account. Since abuse and postmaster are reserved aliases, you can not use them as usernames, nicknames, or email aliases. See reporting abuse.
Client libraries For the Java client library, use Java 1.5 or later. For a .NET client, use the .NET 1.1 runtime or later, and you should be current with all patches.
Email, administrator's recovery address  The Admin Settings API manages your domain administrator's email recovery address. For recovery address details, see recovery email address.
Email, maximum recipients per email When using your email and outside of the Email Settings API, the maximum number of recipients allowed for each email is 500 recipients.

If you use a POP or IMAP mail client (Microsoft Outlook or Apple Mail, e.g.), the maximum number of recipients for one message is 100 people at a time.

For external recipients, Google will temporarily disable an account for approximately 24 hours if the message being sent is going to more than 500 external recipients per day from a Google Apps free edition account, or 2000 external recipients per day from a G Suite account. This includes the recipients in the message's To:, Cc:, and Bcc: fields. See the help center's sending limits article.

In addition, an account is disabled if the there is a large number of undeliverable messages. For a large number of undeliverable messages, verify your contacts' email addresses and confirm everyone you are sending email are willing to receive it. See the Bulk Senders Guidelines.

Email, MX records and mail flow The Admin Settings API verifies your MX record status. This confirms that your email domain's MX records have been configured and your account has mail flow.
Email, SSO settings The Admin Settings API lets you control how users access the email by adjusting the Single Sign-On (SSO) settings.
Email client, report settings The Reporting API generates an email clients report showing how users in your domain access their hosted accounts on a day-to-day basis. For each day, the report lists the total number of accounts in your domain as well as the number of users in your domain who have access email using WebMail.
External content, viewing default When you receive an email with an externally linked image, the default is for the images not to be displayed. In addition, the default behavior will display the image if the email's sender is someone you have sent an email message at least twice. See display images.
Group email permission settings The Provisioning API manages a new group's subscription permissions.
HTTPS, default The default browser setting is HTTPS.

Note:Possible errors may result when using this setting. See changing HTTPS.

Mailbox, language and domain logo settings The Admin Settings API lets you set the default language for your users' accounts, and the API lets you personalize your mailbox by changing your domain logo.
Mail loops A mail loop often occurs when two accounts are forwarding to each other. When a mail loop is detected, the email system will bounce the message to break the cycle.
Outbound email routing The Admin Settings API configures outbound routing of email from users in your domain.
POP and IMAP supported clients Supported POP client list

Supported IMAP client list

Outside of the Email Settings and when using IMAP email client connections, the limit of simultaneous IMAP connections is 10 connections per account.

Mail clients can open multiple connections in the background. It is possible to reach a connection quota simply by using only two mail clients accessing the same account at the same time. If you commonly use multiple mail clients or mobile devices with the same email account, close or sign out of any mail clients you are not actively using.

User names Usernames can contain letters (a-z), numbers (0-9), dashers (-), underscores (_), and apostrophes ('). G Suite recognizes dots or periods (.). This is not the same as Gmail.

Send feedback about...

Email Settings API (deprecated)
Email Settings API (deprecated)
Need help? Visit our support page.