When a developer first needs email for an agent, the Gmail API is the obvious place to start. It is well documented, free at normal volume, and the address already exists. The problems that show up later are rarely about the API itself: Google's quotas are generous and push notifications exist. What does not fit is the identity model. The Gmail API gives your code access to a mailbox that a person or a Workspace admin owns, and an agent that needs its own addresses, often one per task, is a different shape of problem.
The Gmail figures below come from Google's developer documentation and Gmail Help pages as of September 2026.
What the Gmail API does well
Quota is not the constraint most people expect. Google lists 1,200,000 quota units per minute per project and 6,000 units per minute per user. A messages.list call costs 5 units and messages.get costs 20, so a single mailbox can list and fetch about 240 times a minute before it hits the per-user limit. Sending costs 100 units per message. Google also says usage above 80 million units per project per day is planned to incur charges, with billing details due later in 2026.
You do not have to poll either. users.watch connects a mailbox to a Cloud Pub/Sub topic, and Pub/Sub can call your webhook when the mailbox changes. The notification carries only the email address and a new historyId; you then call history.list to find what changed and messages.get to read it. The watch has to be renewed at least every 7 days (Google recommends daily), each watched user gets at most one notification per second, and Google's docs warn that notifications can occasionally be delayed or dropped, so a periodic history.list is the recommended fallback.
Google also documents a Gmail MCP server with its own query costs, so assistants can work with a person's mailbox through MCP as well.
Where it stops fitting agents
Addresses belong to people or to a Workspace domain. A consumer Gmail account is created by a person. Google's account help is explicit: "Don't use programs (called bots) to create fake accounts," and Google automatically detects and disables accounts made for abuse. Workspace admins can create users programmatically through the Admin SDK Directory API (users.insert), but each one is a full user in your domain with everything that implies, and Google notes that calls made immediately after creation can fail while the new user propagates.
Access is granted per mailbox. Reading a Gmail mailbox means an OAuth grant from its owner, a refresh token to store and rotate, and a consent screen to maintain. That is the right model when a person is handing an assistant their inbox. For fifty agent addresses it is fifty grants.
Sharing one mailbox between agents is fragile. The usual workaround for the identity problem is a single account that every agent uses. Then each agent has to pick its own message out of everyone else's, usually by subject and a time window, and two agents signing up to the same service at the same moment receive two emails that look identical apart from the code.
Sending is capped per account per day. Gmail Help lists 500 outgoing messages a day for standard accounts and 2,000 for work, school and Workspace Individual accounts. Past the limit, sending stops for 1 to 24 hours. Gmail's program policies also forbid automating the Gmail interface "in a manner that misleads or deceives users."
Parsing is your job. messages.get returns the message payload as MIME parts. Finding a six digit code or a verification link in it is code you write and maintain.
Side by side
| Gmail API | Lumbox | |
|---|---|---|
| Who owns the address | A Google account holder or Workspace domain | Your Lumbox account |
| New address | A person signs up, or a Workspace admin calls users.insert | POST /v1/inboxes |
| Access | OAuth grant per mailbox | One API key for the account's inboxes |
| New mail signal | Pub/Sub watch, renewed every 7 days, then history.list | Long-poll /wait, server-sent events, or a webhook with the email ID |
| Codes and links | Parse the MIME payload yourself | parsed.otp_codes, verification_links, magic_links |
| Sending volume | 500 a day (standard), 2,000 a day (Workspace) | Monthly plan cap, from 100 (free) to 50,000 (Scale) |
| Retiring an address | Delete the account or Workspace user | DELETE /v1/inboxes/:id |
When Gmail is the right choice
If the agent works for a specific person on that person's existing mail (triage, drafting replies, labelling, pulling receipts), use the Gmail API or Google's MCP server. The history the agent needs is in that mailbox, and OAuth consent is the correct way for the person to hand it over. The same goes for a small team already on Workspace that wants two or three long-lived agent mailboxes humans also read in Gmail; a Workspace user may be simpler than adding a service.
When a dedicated agent inbox is
If the agent needs an identity of its own, the Gmail model works against you. Signups, verifications and account setup want a fresh address per task, created and thrown away by code, with the code already extracted when the email lands. With Lumbox that is three HTTP calls:
import os, httpx
BASE = "https://api.lumbox.co/v1"
H = {"X-API-Key": os.environ["LUMBOX_API_KEY"]}
inbox = httpx.post(f"{BASE}/inboxes", headers=H, json={"name": "vendor-signup"}).json()
# the agent submits inbox["address"] (e.g. vendor-signup@trylumbox.com) to the form
r = httpx.get(f"{BASE}/inboxes/{inbox['id']}/otp", headers=H,
params={"timeout": 90, "from": "vendor.example"}, timeout=100)
if r.status_code == 408:
raise RuntimeError("no verification code within 90 seconds")
code = r.json()["code"]
httpx.delete(f"{BASE}/inboxes/{inbox['id']}", headers=H)The Gmail version of the same step needs a Pub/Sub topic with publish rights granted to Gmail's push service account, a watch call, a webhook, a history.list call, a messages.get call, MIME decoding and a regex. Each part is well documented, but that is seven pieces to build and monitor, and one of them, the watch, lapses after 7 days if nothing renews it.
Isolation comes from the addresses themselves. Each agent waits on its own inbox ID, so two agents signing up to the same service at once never see each other's codes. Lumbox's parser has limits worth knowing: on received mail it finds 4 to 8 digit codes in the subject and plain-text body, so an alphanumeric code means reading the body from /wait yourself.
If you are already fighting Gmail restrictions, this post on Gmail blocks covers recovery. The multi-agent isolation post goes deeper on per-agent inboxes, and the quickstart has the same flow with the SDKs.