# Gmail for AI Agent

> Using Gmail for an AI agent? Learn the sending limits, API quotas, OAuth scopes and aliases, and when to give each agent a separate inbox.

Gmail can work for an AI agent that needs existing conversations or must send from a Gmail address. The setup needs the correct OAuth scopes, quota handling and a clear limit on the email that the agent can read. Google documents the [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes) and a [Gmail MCP server](https://developers.google.com/workspace/gmail/api/reference/mcp) in Developer Preview. MCP is a standard that connects AI apps to tools.

If the agent only receives email for one task, give it a separate inbox. The section "A three-inbox agent architecture" shows one way to do that.

## Sending limits are not account rules

A Gmail sending limit tells you when Gmail stops sending for a time. It does not promise that Google keeps the account active. Google can disable an account that breaks the [Gmail Program Policies](https://support.google.com/mail/answer/16734397). These policies do not allow spam or unsolicited commercial email. They also limit automation of the Gmail interface to send, delete or filter email.

For an agent, use the Gmail API or the Gmail MCP server. Do not use a script that controls the Gmail web page.

## Separate Gmail sending limits from Gmail API quotas

Personal Gmail can show a sending-limit error after more than 500 emails in a day. It can also show it for one email to more than 500 recipients. Google says that sending works again within 1 to 24 hours. See [Gmail sending limits](https://support.google.com/mail/answer/22839?hl=en).

Paid Google Workspace accounts can send 2,000 messages a day for each user. Trial accounts can send 500. Google can change these limits without notice. See [Workspace sending limits](https://knowledge.workspace.google.com/admin/gmail/gmail-sending-limits-in-google-workspace).

The Gmail API has separate quotas, counted in quota units. Each method uses a number of units, for example 100 for `messages.send`. A project can use 1,200,000 units a minute, and one user can use 6,000 units a minute in a project. See [Gmail API quotas](https://developers.google.com/workspace/gmail/api/reference/quota).

Google changed these quotas on May 1, 2026. Projects that used the API from November 2025 to April 2026 keep their earlier quotas. Projects created on or after May 1, 2026 get the new quotas. Above 80,000,000 units a day for each project, Google plans to charge from later in 2026. Google promises at least 90 days of notice.

If a request fails because of a quota, retry with truncated exponential backoff. Each retry waits twice as long as the one before, plus a random part of up to 1,000 milliseconds. Google gives 32 or 64 seconds as the usual maximum wait.

To get new email without polling, use Gmail `watch` notifications through Cloud Pub/Sub. Call `watch` at least once every 7 days, because the watch expires. Google recommends one call a day. Notifications can be late or lost, so also call `history.list` after a period with no notifications. See [Gmail push notifications](https://developers.google.com/workspace/gmail/api/guides/push).

## Choose Gmail OAuth scopes for the task

A scope sets what an app can do with an account. Google puts each Gmail scope in a class: non-sensitive, sensitive or restricted.

| Scope | What Google says it permits | Class |
| --- | --- | --- |
| `gmail.send` | Send email on your behalf | Sensitive |
| `gmail.readonly` | View your email messages and settings | Restricted |
| `gmail.metadata` | View message metadata, such as labels and headers, but not the email body | Restricted |
| `gmail.compose` | Manage drafts and send email | Restricted |
| `gmail.modify` | Read, compose and send email, without permanent deletion that bypasses the trash | Restricted |
| `https://mail.google.com/` | Read, compose, send and permanently delete all email | Restricted |

The scope names are shortened. See the [Gmail scope reference](https://developers.google.com/workspace/gmail/api/auth/scopes).

A label or search filter in your code does not make the access of the token smaller. A token with `gmail.readonly` can read every message of the account, also when your code searches only for invoices. Request `https://mail.google.com/` only when the app must delete email permanently. Gmail add-ons have separate scopes for the message that the user opens.

An agent that only sends approved notifications can use `gmail.send`. That scope does not let it read the inbox. The `gmail.compose` scope manages drafts, but it also permits sending.

Request a new scope only when the app needs it. Google recommends this incremental authorization in its [OAuth best practices](https://developers.google.com/identity/protocols/oauth2/resources/best-practices).

The Gmail MCP server uses `gmail.readonly` and `gmail.compose`. Its tools search and read threads, manage labels and create drafts. It lists no tool that sends email. Google tells users to review the actions of the AI app and to avoid untrusted email, because email can hold hidden instructions. See [Configure the Gmail MCP server](https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server).

## Extra addresses are not separate agent inboxes

Gmail plus addressing sends email for `address+tag` to the same inbox. It sorts arrivals, but it does not make a separate account or a separate permission for an agent. See [Gmail address variations](https://support.google.com/a/users/answer/9282734?hl=en).

Workspace administrators can add up to 30 aliases for each user at no extra cost. Email to an alias goes to the inbox of that user. See [Workspace aliases](https://knowledge.workspace.google.com/admin/users/add-or-delete-an-alternate-email-address-email-alias).

An eligible account can create a new `@gmail.com` address once every 12 months, three times in total. The old address stays on the account, and both addresses share one inbox. See [Google Account address changes](https://support.google.com/accounts/answer/19870?hl=en).

To give agents different access, use separate accounts or separate inboxes.

## A three-inbox agent architecture

For example, give three tasks three inboxes. Each inbox has its own address, and each agent has its own credential:

| Inbox purpose | Incoming email | Agent access and output |
| --- | --- | --- |
| Research | Newsletters and research attachments | Research inbox only. Saves a digest with links to the sources |
| Support intake | Customer questions and screenshots | Support inbox only. Saves triage notes and proposed replies for a person |
| Invoice intake | Supplier email and invoice PDFs | Invoice inbox only. Saves extracted fields for review |

### Choose where the inboxes live

- Three Gmail accounts or Google Workspace users. Each agent gets an OAuth grant for one account.
- Three [AgentMail inboxes](https://www.agentmail.to/docs/inboxes). Each agent gets an [API key that is limited to its inbox](https://www.agentmail.to/docs/permissions).
- Three addresses on your own domain with [Cloudflare Email Routing](https://developers.cloudflare.com/email-service/get-started/route-emails/). A routing rule sends each address to a Worker, and the Worker gives the email to the correct agent.
- Three addresses at [Postmark inbound](https://postmarkapp.com/developer/user-guide/inbound) or [SendGrid Inbound Parse](https://www.twilio.com/docs/sendgrid/for-developers/parsing-email/setting-up-the-inbound-parse-webhook). The service sends each email to your webhook, and your code gives it to the correct agent.

### Give each agent its own credential

Give each agent its own OAuth grant or API key, with only the access that its task needs. If one key leaks, only one inbox is open to the attacker. Your logs also show which agent did each action. Give write access only to the agent that must save output.

### Keep the original email with the result

Keep the original email and its attachment next to the result of the agent. Then a person can compare them. Save the message ID with each result. The agent or your app does the extraction, so a person must be able to find the source.

## Choose the inbox for the job

For most people, a separate Gmail account for the agent is the simplest choice. It is free, and most AI apps can connect to it. Use another service when your own code must create many inboxes or receive email at your own domain. [Email inboxes for AI agents and people](/email-for-ai-agents/) lists them, with prices.

Use Gmail when the agent must read existing conversations or send from a Gmail address. Use a separate inbox when the agent only receives email for one task. You can also use both: the agent proposes a reply from the separate inbox, and a person sends it from Gmail.

To send selected Gmail email to a separate inbox, use [Gmail automatic forwarding](https://support.google.com/mail/answer/10957?hl=en). Gmail first sends a confirmation link to the new address.

For the risks of a personal inbox, read [Why a personal Gmail inbox is a poor fit for an AI agent](/blog/why-a-personal-gmail-inbox-is-a-poor-fit-for-an-ai-agent/).

A docs portal with Ask AI
and support tickets

Connect a repository, or describe your product to start. Each docs site has search, Ask AI, an API console, an MCP server and support tickets.

Publishes from GitHub on every push

Works with Mintlify repositories

API console from your OpenAPI file

MCP server and llms.txt for AI agents

Ask AI and support tickets

Analytics for people and AI agents

Start Free →

Questions? Ask AI in our docs
No card required.

## Frequently Asked Questions

### Does an agent app need Google verification for Gmail scopes?

An app that requests a restricted scope, such as `gmail.readonly`, needs Google's verification, unless an exception applies. Exceptions include personal use by you or a few people that you know, apps in development or testing, and internal apps of a Workspace organization. An app that can get restricted data through a third-party server also needs a security assessment. See [restricted scope verification](https://developers.google.com/identity/protocols/oauth2/production-readiness/restricted-scope-verification).

### Can several agents share one Gmail account?

They can, but each token gets the access of its scope on the complete account. So every agent can read the same email. For different access, give each agent its own account or a separate inbox.

---

[View the canonical page](https://revdoku.com/blog/gmail-for-ai-agent/) · [Browse llms.txt](https://revdoku.com/llms.txt)