Gmail OAuth scopes for AI agents: what to request for each job

Direct answer

Request the narrowest Gmail scope for each thing the agent actually does. To send email only, use https://www.googleapis.com/auth/gmail.send, which is send-only and classified sensitive by Google. To read messages, use gmail.readonly, or gmail.metadata if headers and labels are enough; both are restricted. Avoid https://mail.google.com/ (full mailbox access) and gmail.modify unless the agent genuinely needs to change messages, because both are restricted and grant far more than most agents use. Then decide which actions wait for a person: sending to customers until the agent has a track record, and trashing or deleting email always. The free OAuth scope planner works this out for any mix of actions, with a source link for every scope.

The Gmail scopes an agent might need

Every scope and classification below comes from Google's Gmail API scopes page, as recorded in the permission-planner catalog (checked against the docs on 2026-10-03).

Agent action	Minimum scope	Google classification	What else it grants
Read messages and threads	`https://www.googleapis.com/auth/gmail.readonly`	restricted	Read-only
Read headers and labels, no bodies	`https://www.googleapis.com/auth/gmail.metadata`	restricted	Read-only, metadata only
Send email	`https://www.googleapis.com/auth/gmail.send`	sensitive	Nothing else; it cannot read the mailbox
Create and edit drafts	`https://www.googleapis.com/auth/gmail.compose`	restricted	Also permits sending
Create, rename and delete labels	`https://www.googleapis.com/auth/gmail.labels`	non-sensitive	Label definitions only
Apply labels, archive, mark read	`https://www.googleapis.com/auth/gmail.modify`	restricted	Also reading, composing and sending
Move messages to trash	`https://www.googleapis.com/auth/gmail.modify`	restricted	As above; trash is recoverable for 30 days
Permanently delete messages	`https://mail.google.com/`	restricted	Full mailbox access

A few things in that table are easy to miss:

There is no drafts-only scope. gmail.compose lets the agent send, too. If your agent must only ever draft, enforce that in your own code; the scope won't do it for you.
gmail.labels doesn't let an agent label mail. It manages the label list. Applying a label to a message needs gmail.modify.
Broader scopes cover narrower ones. Google documents that gmail.modify includes gmail.readonly, gmail.compose and gmail.send, and that gmail.compose includes gmail.send. Requesting both a broad scope and a narrow one it covers just adds a line to the consent screen.

Why the classification matters

Google sorts scopes into non-sensitive, sensitive and restricted. Sensitive scopes need OAuth app verification before users outside your organization can grant them. Restricted scopes need verification too, and for apps used outside your own Google Workspace organization they can also require a third-party security assessment.

That has a practical consequence for agent design. An agent that only sends notifications can live entirely on gmail.send, a sensitive scope. The moment it needs to read the inbox, it is on a restricted scope, and the review burden goes up. If you can split the work, for example a sender that never reads and a separate reader that never sends, you can keep each credential narrow.

Example plans for common agents

An inbox triage agent reads new mail, labels it and archives what's handled. It needs gmail.modify for the labeling and archiving, which already covers reading. Every action is internal, so it can run automatically with an audit log.

A follow-up agent reads customer replies and sends reminders. It needs gmail.readonly plus gmail.send, not https://mail.google.com/. Reading runs automatically; sends go out with a person's approval until the agent has proved itself.

A drafting assistant prepares replies for a person to send. It needs gmail.readonly and gmail.compose. Because compose can send, block the send call in code and say so in your security review.

You can produce these plans from the command line:

npx @teamshift/permission-planner plan --actions gmail.read,gmail.send

The report lists each scope with Google's classification and the actions that need it, groups the actions by risk tier with an approval policy, and warns when a scope you already request is broader than needed. The in-browser version does the same with a searchable checklist.

Requesting the scopes

With Google's Node.js auth library, ask only for what the first feature needs and add scopes when the user turns on a feature that needs more. include_granted_scopes lets a later request add to the scopes the user already granted instead of replacing them:

import { OAuth2Client } from "google-auth-library";

const client = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  "https://app.example/oauth/google/callback",
);

// Day one: the agent reads customer replies.
const readUrl = client.generateAuthUrl({
  access_type: "offline",
  include_granted_scopes: true,
  scope: ["https://www.googleapis.com/auth/gmail.readonly"],
});

// Later, when the owner turns on reminders: add send-only access.
const sendUrl = client.generateAuthUrl({
  access_type: "offline",
  include_granted_scopes: true,
  scope: ["https://www.googleapis.com/auth/gmail.send"],
});

After the exchange, check the scope field of the token response and only enable features whose scopes were actually granted. Users can decline part of a request, and an agent that assumes it can send because it asked to is an agent that fails at the worst moment.

Which Gmail actions should wait for a person

Scopes decide what an agent can do; approval policy decides what it may do without asking. A reasonable default, and the one the planner recommends:

Reading and searching: automatic, with access logged.
Labeling, archiving, managing labels: automatic with an audit trail and an easy undo.
Sending to customers or anyone outside the business: a person approves each send until the agent has a clean record, then spot checks.
Trashing or deleting: always a person. Prefer trash, which can be recovered for 30 days, over permanent deletion, which also needs full mailbox access.

Human in the loop AI goes deeper on how to set these gates so they protect you without becoming a bottleneck.

FAQ

What is the minimum Gmail scope to send email?

https://www.googleapis.com/auth/gmail.send. It can send but cannot read the mailbox, and Google classifies it as sensitive rather than restricted.

Is gmail.readonly a restricted scope?

Yes. Google classifies gmail.readonly as restricted, and gmail.metadata, which reads only headers and labels, is restricted as well.

Does gmail.modify include sending email?

Yes. Google documents that gmail.modify also grants reading, composing and sending. Request it only when the agent needs to change messages, for example to label or archive them.

Is there a Gmail scope that only allows drafts?

No. The drafts scope, gmail.compose, also permits sending. If an agent must never send, block sending in your own code.

Should I request https://mail.google.com/ for an AI agent?

Almost never. It is full mailbox access, and Google documents it as the only scope for permanent deletion. Narrower scopes cover reading, sending, drafting, labeling and trashing.