Major

Gmail AI Agents: API Guide and Governed Automation

Learn how Gmail AI agents work with Major's native connector, deterministic apps, and approval workflows. Includes eight verified API endpoints, Gemini features, and recovery design.

Ritvij GautamUpdated
marketing team reviewing campaign results (Gmail AI agents and automations)

Gmail AI agents interpret email, propose next actions, and coordinate work beyond the inbox. Major gives that work a deterministic app with stored state and a review queue, while the agent handles judgment. This guide covers Gmail's built-in AI, its API, and governed automation across business systems.

What Gmail is and who relies on it

Gmail is Google's email service. Its API reference exposes messages, threads, labels, drafts, and mailbox history, the objects an operations team needs to turn an email into tracked work.

Sales operations teams use those conversations to understand inquiries and follow up with account owners. Recruiting coordinators exchange interview details, while finance operators receive supplier questions and invoice exceptions. For these teams, the important unit is often a business case spanning several messages, not an isolated email.

This guide is for operations leads who want that work to continue across systems without losing accountability. Major is the enterprise platform where agents build the software they run on: the agent can build a case-management app, then run its repeatable matching and tracking code rather than reconstructing the process every time.

Gmail remains the correspondence record. The Major app stores process state, review decisions, and links back to source messages. That separation lets a person inspect what happened without searching through an agent's conversation.

Gmail AI agents and Google's built-in AI

Gemini in Gmail already handles useful inbox tasks. Summarize this email condenses lengthy threads. Help me write creates drafts from prompts, while drafting tools improve tone and clarity. Contextual Smart Reply suggests replies grounded in the conversation.

Gemini can also answer questions about inbox content, compare information across emails, and reference specified Google Drive files. These are meaningful capabilities for someone reading and writing inside Gmail. Availability depends on the user's eligible plan and environment, as Google's product page explains.

An agent on Major adds a different layer: a durable business process around that correspondence. It can judge whether an inquiry conflicts with CRM ownership, recommend an exception path, and draft a response using authorized account context. The app holds the case and evidence; a workflow coordinates the connector calls and approvals.

Use the native assistance for composing and understanding mail. Use Major when the task needs cross-system context, persistent ownership, or an auditable approval boundary. A better summary alone does not establish who approved an external commitment or whether another run already handled it.

How Gmail connects to Major

Major has a native Gmail connector (gmail). IT sets up the connector once, stores credentials centrally in the connector vault, and grants access to the apps, agents, and workflows that need it. Credentials belong in the vault, never in application code or prompts.

Major orchestrates Gmail; it never replaces it. The native connector is the connection method, while the API below explains the underlying Gmail capabilities. A documented API method does not mean every connector action is enabled in every organization. Confirm the available operations and granted permissions before designing the write path.

A practical setup sequence is:

  1. Choose the authorized mailbox and narrowly defined business process.
  2. Grant the required Google access and restrict which Major components may use it.
  3. Build app tables for cases, source message IDs, draft references, approvals, and action attempts.
  4. Give the agent only the context and operations needed for its judgment step.
  5. Configure the workflow's schedule, recovery path, and human checkpoints.

SSO, RBAC, and audit logs cover the app, agent, and workflow. These controls complement Google's authorization rather than expanding it.

Gmail API guide for governed inbox work

Authentication and permission boundaries

Gmail uses OAuth 2.0 for private user data, not a general-purpose personal API token. Google's authentication overview also describes service accounts with domain-wide delegation for appropriately authorized Workspace access. Delegation requires administrative setup, not simply possession of a service account key.

The scope reference distinguishes gmail.labels for label definitions, gmail.readonly for reading mail, gmail.send for sending, gmail.compose for drafts and sending, and gmail.modify for reading, composing, sending, and mailbox changes short of immediate permanent deletion. These names use the https://www.googleapis.com/auth/ prefix.

Crucially, gmail.compose is not draft-only, and gmail.modify can send too. A separate gmail.send grant is not always necessary. Google classifies several broad mail scopes as restricted and documents verification and security-assessment requirements for restricted data stored or transmitted on servers. Scope selection and application policy must work together.

Pagination, quotas, events, and testing

Message listing uses pageToken, nextPageToken, and maxResults, with a maximum page size of 500. Its q search parameter is unavailable with the metadata-only scope. Read every page before marking a reconciliation complete.

The current quota page lists 1,200,000 units per minute per project and 6,000 per minute per user per project. It notes that projects active during the specified pre-May 2026 period retain previous quotas. Check the actual project allocation; request costs vary by method and sometimes response format.

Google's error guide documents quota-related 403 errors, 429 responses, and exponential backoff. A remaining-quota response-header contract is not documented publicly on these pages. Monitor error status and reason rather than assuming such headers exist.

Push notifications use Cloud Pub/Sub, not a Gmail-specific signed webhook. Matching mailbox changes produce an email address and historyId. Renew the watch at least every seven days; Google recommends daily renewal. Delivery can be delayed or dropped, and notifications above one event per second per watched user are dropped.

For authenticated push, verify Pub/Sub's JWT, including signature, audience, expected service-account email, and verified-email claim. Pub/Sub retry policy supports immediate redelivery or configured exponential backoff. Persist work before acknowledging delivery.

The Python quickstart provides a testing-oriented OAuth setup. No separate Gmail API sandbox or dry-run sending mode is documented there. Test against a dedicated mailbox with controlled recipients.

Discover messages

GET /gmail/v1/users/{userId}/messages finds candidate messages, returning IDs and thread IDs rather than full bodies.

  • App: Populate a mailbox reconciliation view with source identifiers.
  • Agent: Request candidates relevant to a case before reading their content.
  • Workflow: Page through a scheduled catch-up scan and checkpoint completion.

Read one message

GET /gmail/v1/users/{userId}/messages/{id} retrieves a message in the requested format.

  • App: Show source evidence beside a proposed action.
  • Agent: Interpret intent, urgency, and the requester's actual question.
  • Workflow: Retrieve authorized content only after deduplication identifies new work.

Read conversation context

GET /gmail/v1/users/{userId}/threads/{id} retrieves a conversation's messages.

  • App: Display correspondence associated with a business case.
  • Agent: Distinguish a fresh escalation from an already answered question.
  • Workflow: Refresh the thread before submitting an older draft for approval.

Apply a processing label

POST /gmail/v1/users/{userId}/messages/{id}/modify adds or removes labels on one message.

  • App: Reflect an approved processing status in Gmail.
  • Agent: Recommend the appropriate category from the allowed taxonomy.
  • Workflow: Apply only preauthorized label IDs after policy validation.

Save a reply draft

POST /gmail/v1/users/{userId}/drafts creates a draft, keeping proposed correspondence separate from sending.

  • App: Store the draft reference and its reviewed content version.
  • Agent: Write a response grounded in the email and account evidence.
  • Workflow: Save the proposal and route it to its designated reviewer.

Send an approved draft

POST /gmail/v1/users/{userId}/drafts/send sends an existing draft to its To, Cc, and Bcc recipients.

  • App: Record the approved payload and resulting message reference.
  • Agent: Explain why the proposed response addresses the request.
  • Workflow: Execute only after approval of the exact recipients and content.

Recover mailbox changes

GET /gmail/v1/users/{userId}/history lists changes after a startHistoryId, with pagination.

  • App: Retain a committed mailbox checkpoint outside model context.
  • Agent: Interpret newly relevant correspondence after change retrieval.
  • Workflow: Process all pages before advancing the durable checkpoint.

Register mailbox notifications

POST /gmail/v1/users/{userId}/watch registers or updates a mailbox watch using a Pub/Sub topic.

  • App: Track watch expiration and notification health.
  • Agent: Explain an observed processing gap using the recorded evidence.
  • Workflow: Renew the watch and alert an operator if renewal fails.

Gmail automation use cases on Major

These are proposed designs, not customer deployments. Start with one mailbox and one case type, then expand after reviewing actual decisions and failure patterns.

Sales inquiry routing with HubSpot and Slack

  • App: Hold the inquiry, CRM match, assigned owner, and approval status.
  • Agent: Judge buying intent and distinguish an existing account request from a new prospect.
  • Workflow: Use message listing, message retrieval, thread retrieval, and draft creation above. Read HubSpot account context, notify the owner in Slack, and gate external replies on approval.

Invoice exceptions with QuickBooks and Slack

  • App: Maintain supplier references, duplicate checks, and an exception queue.
  • Agent: Assess whether the email explains a genuine mismatch or needs clarification from finance.
  • Workflow: Use message retrieval, thread retrieval, and draft creation to prepare the case. Read authorized QuickBooks records, request finance review in Slack, and leave payment authorization outside the agent's authority.

Client deadline changes with Asana and Slack

  • App: Store the source thread, affected task, proposed deadline, and owner decision.
  • Agent: Interpret whether the client requested a new deadline or merely discussed a possibility.
  • Workflow: Use history retrieval and thread retrieval to discover and contextualize changes. Present an Asana update proposal in Slack, then apply approved changes through the configured connector operations.

Each design uses the endpoint guide's Gmail operations, with mailbox watches optional when scheduled reconciliation is sufficient. Never infer permission to write a business-system record from permission to read the related email.

Architecture: build the inbox control surface on Major

Gmail and HubSpot context flows through a Major workflow, triage agent, approval decision, and review app

Gmail remains the mail record; Major holds process state and review decisions.

Build the review app before allowing external actions. Its managed database should connect a mailbox and message ID to a case, an agent recommendation, the evidence used, a draft version, and an action status. The UI makes unresolved cases visible to their owners.

The workflow starts from a scheduled scan or a verified notification intake. It retrieves changes, deduplicates work, gathers permitted business context, and invokes the agent only where interpretation is needed. The agent judges intent or drafts a recommendation; deterministic policy checks then select the permitted route.

Keep checkpoints and action attempts in the app, not in the agent's conversational memory. Store separate states for proposed, awaiting review, approved, executing, completed, and uncertain. An uncertain network outcome must remain visible rather than becoming another automatic attempt.

As the process settles, agents can build reusable software for repeatable parsing, routing, and reconciliation. Judgment remains with the agent, while the app executes the stable mechanics. Reason once. Run forever.

A worked example with illustrative numbers

For example, suppose a sales operations team handles 300 inbound inquiries each week. This is planning arithmetic, not a measured Major customer result. Assume manual review takes four minutes per inquiry, including account lookup, owner selection, and drafting.

The baseline is 300 multiplied by four minutes, or 1,200 minutes, equal to 20 hours weekly. Now suppose the team tests a Major design where 240 straightforward cases need one minute of human review and 60 ambiguous cases still need four minutes.

Human handling becomes 240 minutes plus 240 minutes, or eight hours. Add two hours for queue supervision and corrections, producing a ten-hour illustrative total and a ten-hour difference from the baseline. Model and API costs are separate and must be measured.

One inquiry moves through message discovery, thread retrieval, CRM lookup, agent classification, saved draft, owner approval, and approved sending. The app retains the evidence and timing for every stage. Measure draft acceptance, wrong-owner corrections, duplicate actions, and delayed cases alongside time, because faster handling is not useful if correspondence becomes less accurate.

Governance and failure handling

Gmail agent recommendations pass a policy check, with labels allowed by policy and external drafts held for human approval

Approve exact recipients and content before the workflow sends an external reply.

Treat incoming email and attachments as untrusted content, never as instructions to expand permissions or reveal other correspondence. The agent must not independently change bank details, authorize payments, promise legal terms, broaden recipients, or delete records.

Google scopes are broader than some business policies. Because drafting scopes can also permit sending, enforce operation allowlists and workflow approval gates, not a fictional draft-only OAuth scope. If Gmail drafts are unnecessary, keep proposed text in the Major app and avoid granting compose access.

Use mailbox plus message ID plus action type as a deduplication key, with a draft version for approval-sensitive writes. Revalidate recipients and content immediately before sending. If a send request times out, reconcile the outcome rather than blindly retrying.

Retry transient failures with bounded exponential backoff and jitter. Separate per-mailbox queues to avoid one busy account blocking others. Google's synchronization guide requires full synchronization when an expired history checkpoint produces 404. Track watch renewal, periodically reconcile missed notifications, and log reviewer identity, policy version, connector operation, and outcome with retention limits.

Where Gmail rules stop and agent triage begins

Gmail's native filters apply selected actions to messages matching search criteria. They are useful for predictable sorting, labeling, forwarding, and other specified handling. Keep stable rules in deterministic software rather than asking a model to rediscover them.

An intent-based decision needs more context. Two messages may contain the same product name and deadline, but one is a routine question and the other signals an account escalation. An agent can interpret that distinction using the thread and authorized business records, then explain its recommendation.

This also corrects two common API misconceptions. Label modification is not the API's only write capability; the reference includes drafts, sending, and other message operations. And saving a draft does not prove the authorization cannot send it. The specific granted scopes and exposed operations determine that boundary.

The useful comparison is therefore rules for known conditions, agents for judgment, and workflows for coordinated execution with approvals. A Major app makes their combined work durable and inspectable. It remembers prior actions even when the next run starts with a fresh model context.

Gmail AI Apps, Agents and Workflow Automations

Every published Major use case that works with Gmail, newest first. Each one names the Gmail API objects involved and shows the app, agent and workflow split.

  • Appsmith Alternatives: 7 Platforms, Major at #1: Comparing Appsmith alternatives? Start with what your internal apps must do after launch: connect systems, retain state, and keep repeated work governed. Major leads for teams turning those workflows into deterministic apps.

Frequently asked questions

What are Gmail AI agents?

Gmail AI agents interpret messages, judge intent, and propose or coordinate actions using authorized context. On Major, a deterministic app stores cases and history, the agent handles judgment, and a workflow manages execution and approvals.

Can you automate Gmail replies without sending them automatically?

Yes. Save a Gmail draft or hold proposed text in the Major app for review. Gmail's compose permission also allows sending, so enforce the no-send policy through operation restrictions and approval gates, not an assumed draft-only scope.

How does an AI agent remember past actions in Gmail?

Store mailbox and message IDs, case status, draft versions, approvals, and action outcomes in the Major app's managed database. Subsequent runs consult that record instead of relying on conversational memory, reducing repeated processing and preserving accountability.

Is it safe to let automation label and draft from my inbox?

It can be governed with scoped access, allowed-operation checks, review gates, and audit logs, but it is not risk-free. Drafting and mailbox-modification permissions can include sending, so review the actual grants and block unauthorized operations structurally.

What is a common cause of lost real-time Gmail notifications in automations?

An expired mailbox watch is one cause. Google requires renewal at least every seven days and recommends daily renewal. Notifications may also be dropped or delayed, so monitor expiration and run reconciliation rather than relying on push alone.

How do Gmail agents differ from Gemini in Gmail and filters?

Gemini provides native summarizing, drafting, contextual replies, and inbox assistance. Filters execute specified matching rules. An agent on Major adds cross-system judgment within a stateful process, while apps retain records and workflows coordinate approvals and recovery.

Sources

Start building on Major

Build a Gmail review app that keeps case state, gives agents bounded judgment, and requires approval before consequential actions.

About the author

Ritvij Gautam is Head of Growth at Major.

Last reviewed November 20, 2026 by Ritvij Gautam.

Frequently asked questions

What are Gmail AI agents?
Gmail AI agents interpret messages, judge intent, and propose or coordinate actions using authorized context. On Major, a deterministic app stores cases and history, the agent handles judgment, and a workflow manages execution and approvals.
Can you automate Gmail replies without sending them automatically?
Yes. Save a Gmail draft or hold proposed text in the Major app for review. Gmail's compose permission also allows sending, so enforce the no-send policy through operation restrictions and approval gates, not an assumed draft-only scope.
How does an AI agent remember past actions in Gmail?
Store mailbox and message IDs, case status, draft versions, approvals, and action outcomes in the Major app's managed database. Subsequent runs consult that record instead of relying on conversational memory, reducing repeated processing and preserving accountability.
Is it safe to let automation label and draft from my inbox?
It can be governed with scoped access, allowed-operation checks, review gates, and audit logs, but it is not risk-free. Drafting and mailbox-modification permissions can include sending, so review the actual grants and block unauthorized operations structurally.
What is a common cause of lost real-time Gmail notifications in automations?
An expired mailbox watch is one cause. Google requires renewal at least every seven days and recommends daily renewal. Notifications may also be dropped or delayed, so monitor expiration and run reconciliation rather than relying on push alone.
How do Gmail agents differ from Gemini in Gmail and filters?
Gemini provides native summarizing, drafting, contextual replies, and inbox assistance. Filters execute specified matching rules. An agent on Major adds cross-system judgment within a stateful process, while apps retain records and workflows coordinate approvals and recovery.