Gmail API v1 · REST · 79 methods · 366 index entries

Written for someone who has called a REST API before and wants the shape of this one: what the resources are, what every parameter does, what a call costs, and how to authenticate without tripping over the consent screen. The first card is the entire API in one table; the next eight are the per-resource parameter tables generated from Google’s own discovery document, so a name or a default here is what the server accepts, not a transcription. Then the mechanisms — the message payload tree, the q search syntax, paging and batch, history and push sync, quota units and error handling — and authentication last: the three OAuth flows, choosing scopes, and the Testing-mode traps that stop a personal project cold. Cards 1–16 are the guide; the rest is a filterable index of 366 entries: 79 methods, 24 parameters, 175 schema fields, 14 scopes and the quota table. Press / to jump to the filter box.

Least scope: readonly / metadata modify / compose / send settings.basic settings.sharing (restricted) full mail.google.com only
Source: the Gmail API discovery document (gmail.googleapis.com/$discovery/rest?version=v1), revision 20260921, and the published usage-limits table, both read on 28 September 2026. Hover a clipped row for the whole entry.

The Working Guide

The whole surface on one card, then the parameter tables resource by resource, the mechanisms, and authentication last

The Whole API on One Card

REST · v1 · revision 20260921

The Gmail API is a plain REST surface over one mailbox: every URL starts https://gmail.googleapis.com/gmail/v1/users/{userId}/, userId is almost always the literal me, and everything below it is a resource with the usual verbs. There are 79 methods in 15 resources, 56 schemas and 14 OAuth scopes. Nothing here is asynchronous except watch; every call returns JSON, every error is an HTTP status with a JSON body.

Resource#Methods
users3getProfile, stop, watch
history1list
threads6delete, get, list, modify, trash, untrash
messages11batchDelete, batchModify, delete, get, import, insert, list, modify, send, trash, untrash
messages.attachments1get
settings10getAutoForwarding, getImap, getLanguage, getPop, getVacation, updateAutoForwarding, updateImap, updateLanguage, updatePop, updateVacation
settings.sendAs7create, delete, get, list, patch, update, verify
settings.sendAs.smimeInfo5delete, get, insert, list, setDefault
settings.cse.identities5create, delete, get, list, patch
settings.cse.keypairs6create, disable, enable, get, list, obliterate
settings.forwardingAddresses4create, delete, get, list
settings.filters4create, delete, get, list
settings.delegates4create, delete, get, list
drafts6create, delete, get, list, send, update
labels6create, delete, get, list, patch, update

The shape of every call

GET /users/me/messages?q=is:unread&maxResults=20list — ids and threadIds only, never bodies GET /users/me/messages/{id}?format=metadata&metadataHeaders=Fromget — one message, as much of it as you ask for POST /users/me/messages/send {"raw": "<base64url RFC 2822>"}send — you build the MIME, Gmail delivers it POST /users/me/messages/{id}/modify {"addLabelIds":["STARRED"]}modify — labels are the only mutable thing on a message GET /users/me/history?startHistoryId=…history — what changed since a point you remember
Read this sheet top-down. The next eight cards are the parameter tables for each resource, straight from Google’s discovery document; then the mechanisms (message anatomy, search syntax, sync, quota); authentication is the last card. The index below lists every method, parameter, schema field and scope, filterable. A * after a parameter means required; italics give the type, enum or default.

Messages

users.messages · 11 methods

A message is immutable: once in the mailbox its body, headers and id never change. Only its labels move (modify), and it can be trashed, untrashed or deleted. list returns id and threadId only — a second get per message is always needed, which is why format and batch requests matter.

MethodRequestParametersScope · units
trashPOST /messages/{id}/trashid* stringgmail.modify · 20
importPOST /messages/importinternalDateSource receivedTime|dateHeader =dateHeader, neverMarkSpam boolean =false, processForCalendar boolean =false, deleted boolean =false, body Messagegmail.insert · 25
modifyPOST /messages/{id}/modifyid* string, body ModifyMessageRequestgmail.modify · 5
getGET /messages/{id}id* string, format minimal|full|raw|metadata =full, metadataHeaders string (repeated)gmail.metadata · 20
insertPOST /messagesinternalDateSource receivedTime|dateHeader =receivedTime, deleted boolean =false, body Messagegmail.insert · 25
batchDeletePOST /messages/batchDeletebody BatchDeleteMessagesRequestmail.google.com · 50
deleteDELETE /messages/{id}id* stringmail.google.com · 10
batchModifyPOST /messages/batchModifybody BatchModifyMessagesRequestgmail.modify · 50
listGET /messagespageToken string, maxResults integer =100, labelIds string (repeated), includeSpamTrash boolean =false, q stringgmail.metadata · 5
untrashPOST /messages/{id}/untrashid* stringgmail.modify · 5
sendPOST /messages/sendbody Messagegmail.send · 100

format on get

fullparsed payload tree: headers, parts, inline bodies (default) metadataheaders only — pair with metadataHeaders=From,Subject,Date minimalids, labels, snippet, sizeEstimate; nothing decoded rawthe RFC 2822 bytes, base64url in raw; no payload

insert puts a message in the mailbox as if it had arrived (no delivery, no SMTP); import does the same but runs the spam and classification pipeline and honours neverMarkSpam / processForCalendar. Both are for migrations, not for sending.

MethodRequestParametersScope · units
getGET /messages/{messageId}/attachments/{id}messageId* string, id* stringgmail.readonly · 20

A part whose body exceeds a few hundred KB carries attachmentId instead of data; fetch it here. The data field is base64url in both places.

Threads

users.threads

A thread is a list of messages that Gmail has grouped by References / In-Reply-To and a matching subject. threads.get returns every message in it in one call (at 40 units, the most expensive read in the API); modify, trash and delete apply to all of them.

MethodRequestParametersScope · units
listGET /threadsincludeSpamTrash boolean =false, q string, pageToken string, labelIds string (repeated), maxResults integer =100gmail.metadata · 10
untrashPOST /threads/{id}/untrashid* stringgmail.modify · 10
deleteDELETE /threads/{id}id* stringmail.google.com · 20
trashPOST /threads/{id}/trashid* stringgmail.modify · 20
getGET /threads/{id}id* string, format full|metadata|minimal =full, metadataHeaders string (repeated)gmail.metadata · 40
modifyPOST /threads/{id}/modifyid* string, body ModifyThreadRequestgmail.modify · 10
Replying into a thread is three things at once: set threadId on the message you send, put the original Message-ID in References and In-Reply-To, and keep the subject (a Re: prefix is fine). Miss one and Gmail starts a new thread.

Drafts

users.drafts

A draft wraps a message that has not been sent. create and update take the same {"message": {"raw": …}} body as send; drafts.send delivers it and the draft disappears. Drafts are what a UI should write while a user is typing; messages.send is for finished mail.

MethodRequestParametersScope · units
getGET /drafts/{id}id* string, format minimal|full|raw|metadata =fullgmail.readonly · 20
deleteDELETE /drafts/{id}id* stringgmail.compose · 10
createPOST /draftsbody Draftgmail.compose · 10
sendPOST /drafts/sendbody Draftgmail.compose · 100
updatePUT /drafts/{id}id* string, body Draftgmail.compose · 15
listGET /draftsincludeSpamTrash boolean =false, q string, pageToken string, maxResults integer =100gmail.readonly · 5

Labels

users.labels

Labels are the only classification Gmail has — folders, stars, read state and the inbox are all labels. System labels have fixed ids (INBOX, UNREAD, STARRED, IMPORTANT, SENT, DRAFT, TRASH, SPAM, CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS). User labels get ids like Label_42 — never assume the id equals the name; call labels.list once and map.

MethodRequestParametersScope · units
createPOST /labelsbody Labelgmail.labels · 5
listGET /labels—gmail.metadata · 1
updatePUT /labels/{id}id* string, body Labelgmail.labels · 5
getGET /labels/{id}id* stringgmail.metadata · 1
deleteDELETE /labels/{id}id* stringgmail.labels · 5
patchPATCH /labels/{id}id* string, body Labelgmail.labels · 5

labelListVisibility and messageListVisibility control the sidebar and the message list; color takes only the palette values Gmail publishes (LabelColor in the schema index). update replaces the whole label; patch merges.

History, watch & getProfile

users · users.history

history.list is the change log: given a startHistoryId you remembered, it returns every message added, deleted, labelled or unlabelled since, in order. It is how a client stays in sync without re-listing the mailbox. watch asks Gmail to publish a Pub/Sub message whenever the history moves; getProfile is the cheapest call in the API and also tells you the current historyId.

MethodRequestParametersScope · units
watchPOST /watchbody WatchRequestgmail.metadata · 100
getProfileGET /profile—gmail.metadata · 1
stopPOST /stop—gmail.metadata · 50
MethodRequestParametersScope · units
listGET /historylabelId string, startHistoryId string, pageToken string, historyTypes messageAdded|messageDeleted|labelAdded|labelRemoved (repeated), maxResults integer =100gmail.metadata · 2
historyId expires. Gmail keeps roughly a week of history; a startHistoryId older than that returns 404, and the only recovery is a full re-sync. Store the newest id you have seen after every successful sync.

Settings — basic

users.settings · gmail.settings.basic

The per-mailbox switches a user sees under Gmail settings: IMAP and POP access, the vacation responder, display language, and reading (not writing) auto-forwarding. All of these need gmail.settings.basic.

MethodRequestParametersScope · units
updateImapPUT /settings/imapbody ImapSettingsgmail.settings.basic · 5
updatePopPUT /settings/popbody PopSettingsgmail.settings.basic · 100
getPopGET /settings/pop—gmail.readonly · 1
updateLanguagePUT /settings/languagebody LanguageSettingsgmail.settings.basic · 5
updateVacationPUT /settings/vacationbody VacationSettingsgmail.settings.basic · 5
getLanguageGET /settings/language—gmail.readonly · 1
getVacationGET /settings/vacation—gmail.readonly · 1
getImapGET /settings/imap—gmail.readonly · 1
updateAutoForwardingPUT /settings/autoForwardingbody AutoForwardinggmail.settings.sharing · 5
getAutoForwardingGET /settings/autoForwarding—gmail.readonly · 1
MethodRequestParametersScope · units
getGET /settings/filters/{id}id* stringgmail.readonly · 1
createPOST /settings/filtersbody Filtergmail.settings.basic · 5
listGET /settings/filters—gmail.readonly · 1
deleteDELETE /settings/filters/{id}id* stringgmail.settings.basic · 5

A filter is criteria (from, to, subject, query, negatedQuery, hasAttachment, size) plus an action (addLabelIds, removeLabelIds, forward). Filters are create-and-delete only; there is no update. Applying removeLabelIds: ["INBOX"] is what “skip the inbox” means.

Settings — sharing

sendAs · delegates · forwarding · S/MIME

Everything that changes who can act as this mailbox or where its mail goes is behind gmail.settings.sharing, a restricted scope. Creating a send-as alias, a forwarding address or a delegate each triggers a verification mail (or, in Workspace, an admin-controlled policy). Writes here cost 100 quota units each on purpose.

MethodRequestParametersScope · units
patchPATCH /settings/sendAs/{sendAsEmail}sendAsEmail* string, body SendAsgmail.settings.basic · 100
deleteDELETE /settings/sendAs/{sendAsEmail}sendAsEmail* stringgmail.settings.sharing · 5
getGET /settings/sendAs/{sendAsEmail}sendAsEmail* stringgmail.readonly · 1
verifyPOST /settings/sendAs/{sendAsEmail}/verifysendAsEmail* stringgmail.settings.sharing · 100
listGET /settings/sendAs—gmail.readonly · 1
updatePUT /settings/sendAs/{sendAsEmail}sendAsEmail* string, body SendAsgmail.settings.basic · 100
createPOST /settings/sendAsbody SendAsgmail.settings.sharing · 100
MethodRequestParametersScope · units
listGET /settings/sendAs/{sendAsEmail}/smimeInfosendAsEmail* stringgmail.readonly
insertPOST /settings/sendAs/{sendAsEmail}/smimeInfosendAsEmail* string, body SmimeInfogmail.settings.basic
deleteDELETE /settings/sendAs/{sendAsEmail}/smimeInfo/{id}sendAsEmail* string, id* stringgmail.settings.basic
getGET /settings/sendAs/{sendAsEmail}/smimeInfo/{id}sendAsEmail* string, id* stringgmail.readonly
setDefaultPOST /settings/sendAs/{sendAsEmail}/smimeInfo/{id}/setDefaultsendAsEmail* string, id* stringgmail.settings.basic
MethodRequestParametersScope · units
getGET /settings/forwardingAddresses/{forwardingEmail}forwardingEmail* stringgmail.readonly · 1
createPOST /settings/forwardingAddressesbody ForwardingAddressgmail.settings.sharing · 100
listGET /settings/forwardingAddresses—gmail.readonly · 1
deleteDELETE /settings/forwardingAddresses/{forwardingEmail}forwardingEmail* stringgmail.settings.sharing · 5
MethodRequestParametersScope · units
listGET /settings/delegates—gmail.readonly · 1
deleteDELETE /settings/delegates/{delegateEmail}delegateEmail* stringgmail.settings.sharing · 5
getGET /settings/delegates/{delegateEmail}delegateEmail* stringgmail.readonly · 1
createPOST /settings/delegatesbody Delegategmail.settings.sharing · 100

Settings — client-side encryption

users.settings.cse · Workspace only

Client-side encryption is a Workspace enterprise feature: the key material lives in a customer KACLS (Key Access Control List Service), Gmail stores only wrapped private keys and the public certificate. Consumer accounts have no CSE and these calls return errors for them.

MethodRequestParametersScope · units
listGET /settings/cse/identitiespageToken string, pageSize integer =20gmail.readonly
createPOST /settings/cse/identitiesbody CseIdentitygmail.settings.basic
deleteDELETE /settings/cse/identities/{cseEmailAddress}cseEmailAddress* stringgmail.settings.basic
patchPATCH /settings/cse/identities/{emailAddress}emailAddress* string, body CseIdentitygmail.settings.basic
getGET /settings/cse/identities/{cseEmailAddress}cseEmailAddress* stringgmail.readonly
MethodRequestParametersScope · units
enablePOST /settings/cse/keypairs/{keyPairId}:enablekeyPairId* string, body EnableCseKeyPairRequestgmail.settings.basic
disablePOST /settings/cse/keypairs/{keyPairId}:disablekeyPairId* string, body DisableCseKeyPairRequestgmail.settings.basic
getGET /settings/cse/keypairs/{keyPairId}keyPairId* stringgmail.readonly
listGET /settings/cse/keypairspageSize integer =20, pageToken stringgmail.readonly
createPOST /settings/cse/keypairschainValidation all|none =all, body CseKeyPairgmail.settings.basic
obliteratePOST /settings/cse/keypairs/{keyPairId}:obliteratekeyPairId* string, body ObliterateCseKeyPairRequestgmail.settings.basic

Anatomy of a Message

payload · parts · raw

What messages.get returns is a Message: identity (id, threadId, historyId), classification (labelIds), a snippet, internalDate (epoch milliseconds, the inbox ordering key), sizeEstimate, and either a parsed payload or the raw bytes, depending on format.

The payload tree

payload.mimeTypee.g. multipart/alternative; a leaf is text/plain, text/html, image/png… payload.headers[]{name, value} — From, To, Subject, Date, Message-ID; case-insensitive names payload.body.database64url, only on leaves; absent when attachmentId is set payload.parts[]children; recurse — a forwarded mail nests a whole message part.filenamenon-empty on attachments; the Content-Disposition name

Reading a body

def body(part): if part.get("body", {}).get("data"): return base64.urlsafe_b64decode(part["body"]["data"] + "==") for p in part.get("parts", []): if p["mimeType"] == "text/plain": return body(p) return b""

Sending one

from email.message import EmailMessage m = EmailMessage(); m["To"] = "a@b.com"; m["Subject"] = "Hi" m.set_content("hello") raw = base64.urlsafe_b64encode(m.as_bytes()).decode() svc.users().messages().send(userId="me", body={"raw": raw}).execute()

Gmail sets From, Date and Message-ID if you leave them out, and rewrites From to a verified send-as alias or the account itself. Total size limit is 35 MB per message; larger uploads use uploadType=resumable on the /upload/ URL.

The q Parameter — Search Syntax

messages.list · threads.list

q takes exactly what the Gmail search box takes. Operators combine with implicit AND; OR, - and ( ) group; {a b} is OR too. Dates are YYYY/MM/DD or a duration. It is a search, not a filter: results are ranked, and maxResults caps the page, not the total.

OperatorMatches
from: to: cc: bcc:address or name fragment; deliveredto: the envelope recipient
subject:words in the subject; "exact phrase" anywhere
label: in:a label name (not id): in:inbox, in:anywhere (spam+trash), label:work
is:unread read starred important snoozed muted
has:attachment drive document spreadsheet presentation youtube userlabels nouserlabels
filename:attachment name or extension: filename:pdf
after: before: older: newer:date 2026/09/01 or epoch seconds
older_than: newer_than:relative: 2d 3m 1y
larger: smaller: size:bytes, or 10M
category:primary social promotions updates forums reservations purchases
rfc822msgid:exact Message-ID header — the way to find a mail you sent
list:mailing-list address (List-ID)
AROUND nproximity: budget AROUND 5 alert
+wordexact word, no stemming
q=from:no-reply@em-s.dropbox.com newer_than:60dwhat a mailbox assistant actually runs q=is:unread -category:promotions -category:socialthe inbox worth reading q=has:attachment larger:5M older_than:1ywhere the storage went

labelIds is the exact alternative to label: — ids, ANDed, cheaper to reason about; includeSpamTrash is the only way to see those two without in:anywhere.

Listing, Paging, Partial Responses & Batch

the cost levers

Paging

maxResultspage size; 100 default, 500 max on messages, 500 on threads/history, 100 on drafts nextPageTokenopaque; pass back as pageToken; absent on the last page resultSizeEstimatean estimate, often wrong by hundreds — never a loop bound

Partial responses — fields

Any method takes fields= to trim the JSON: fields=messages(id,threadId),nextPageToken on list, fields=id,payload/headers on get. Syntax: comma list, a/b for nesting, a(b,c) for sub-selection, * wildcard. It changes bytes, not quota units.

Batch

POST https://www.googleapis.com/batch/gmail/v1 Content-Type: multipart/mixed; boundary=b --b Content-Type: application/http Content-ID: <1> GET /gmail/v1/users/me/messages/18f3…?format=metadata --b--

Up to 100 calls per batch, one HTTP round trip, each inner call metered separately. Client libraries expose it as new_batch_http_request(). Batching more than ~50 gets at once trips the per-user per-minute rate limit; back off on 429 inside a batch like anywhere else.

The list-then-get pattern is the whole API: list ids cheaply (5 units), fetch the few you need with format=metadata (20 each), and only pull full for the ones you will actually parse.

Sync — history and push

history.list · watch · Pub/Sub

Two ways to stay current. Polling: remember the highest historyId you have seen, call history.list?startHistoryId=…, walk the records, update the id. Push: watch a Pub/Sub topic; Gmail publishes {emailAddress, historyId} when anything changes, and you call history.list from your stored id, not from the one in the notification.

history.list

historyTypesmessageAdded messageDeleted labelAdded labelRemoved — repeatable, filters records labelIdonly changes touching this label (e.g. INBOX) history[].messages[]touched ids; records also carry messagesAdded etc. with the message historyIdthe new high-water mark to store

watch

POST /users/me/watch {"topicName": "projects/<project>/topics/gmail", "labelIds": ["INBOX"], "labelFilterBehavior": "INCLUDE"} → {"historyId": "…", "expiration": "<epoch ms, ≤7 days>"}
  • The topic must grant gmail-api-push@system.gserviceaccount.com the Publisher role.
  • A watch lasts at most 7 days; call watch again daily. stop ends it early.
  • Notifications are hints, not data: they can arrive out of order or coalesced. Always sync from your own id.
A full sync (list every message, page by page) is the fallback when history 404s or on first run. For a large mailbox that is thousands of list calls; do it once, store ids, and never again.

Quota, Rate Limits & Errors

units per call

Every call costs quota units; the units differ by method (the Quota index card lists all 63). Limits as published on 28 Sep 2026:

LimitValue
Per project, per minute1,200,000 units
Per user, per project, per minute6,000 units
Per project, per day (billing threshold)80,000,000 units
Recipients per message500
Mail sent per day2,000 (Workspace) · 500 (consumer) — a Gmail limit, not an API one

What a minute buys one user

6,000 / 51,200 list calls6,000 / 20300 message gets6,000 / 10060 sends6,000 / 40150 thread gets

Errors

StatusreasonMeaning · what to do
400failedPrecondition / invalidArgumentbad request body or a mailbox that is not enabled for the API (Workspace policy). Do not retry.
401authErrorexpired or revoked token — refresh, then retry once.
403rateLimitExceeded userRateLimitExceeded dailyLimitExceededquota; exponential backoff with jitter starting at 1 s. Also insufficientPermissions = wrong scope, and domainPolicy = admin disabled the API.
404notFoundbad id, or a startHistoryId that has aged out — full re-sync.
429rateLimitExceededsame as 403 quota; honour Retry-After when present.
5xxbackendErrortransient; retry with backoff, cap at a few minutes.

Errors come as {"error": {"code", "message", "errors": [{"domain", "reason"}], "status"}}; branch on reason, not on the message text.

Calling It

curl · Python · Node · gog
curl — with a bearer token
TOKEN=$(gog auth print-access-token 2>/dev/null || echo ya29…) curl -s -H "Authorization: Bearer $TOKEN" \ "https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is:unread&maxResults=5" | jq .
Python — google-api-python-client
pip install google-api-python-client google-auth-oauthlib from googleapiclient.discovery import build svc = build("gmail", "v1", credentials=creds) r = svc.users().messages().list(userId="me", q="newer_than:1d").execute() for m in r.get("messages", []): msg = svc.users().messages().get(userId="me", id=m["id"], format="metadata", metadataHeaders=["From","Subject"]).execute()
Node — googleapis
import {google} from "googleapis"; const gmail = google.gmail({version: "v1", auth}); const {data} = await gmail.users.messages.list({userId: "me", q: "is:unread"});
gog — a CLI over the same API
# github.com/steipete/gogcli · brew install gogcli gog auth credentials client_secret.json gog auth add you@gmail.com --services gmail gog gmail search 'newer_than:7d' --max 10 gog gmail send --to a@b.com --subject Hi --body-file -

The discovery document this sheet was built from is the same one the client libraries generate themselves from: https://gmail.googleapis.com/$discovery/rest?version=v1. When a method is missing from a library, it is missing there too.

Authentication

OAuth 2.0 · scopes · the Testing-mode traps

There is no API-key access to a mailbox. Every call carries an OAuth 2.0 access token for a Google account, minted by a client you registered in a Google Cloud project, limited to the scopes the user consented to. Three flows cover everything:

FlowWhenMechanics
Installed app (desktop, CLI)your own mailbox, a script, a local agentclient id + secret from a Desktop OAuth client; browser consent; redirect to http://127.0.0.1:<port>; PKCE; you get an access token (1 h) and a refresh token.
Web servera hosted app acting for its usersWeb client with registered redirect URIs; authorization code exchanged server-side; store refresh tokens per user, encrypted.
Service account + domain-wide delegationWorkspace only: act as any user in the domainadmin grants the service account’s client id the scopes in the Admin console; the app signs a JWT with sub=user@domain. Never works for @gmail.com accounts.

Choosing scopes

gmail.metadataheaders and labels, never bodies — enough for triage; q is not allowed with it gmail.readonlyeverything, read-only — the default for an assistant gmail.sendsend only; cannot read gmail.composedrafts + send gmail.modifyread, label, trash, send, insert — everything but permanent delete and settings gmail.labelsmanage labels only gmail.settings.basic / .sharingsettings; sharing is restricted (verification with a security assessment) mail.google.comfull: adds permanent delete and CSE; restricted

Ask for the least scope that works, and add scopes incrementally (include_granted_scopes=true) rather than up front. Google classifies gmail.readonly, modify, compose, insert, metadata, settings.* and the full scope as restricted; an app that will be published needs verification and, for restricted scopes, a third-party security assessment.

The consent screen in Testing mode — what bites a personal project

  • “Error 403: access_denied — has not completed the Google verification process.” The project is in Testing and your account is not listed. Fix: Google Cloud Console → Google Auth Platform → Audience → Test users → add the address. Up to 100 test users; no verification needed.
  • Refresh tokens expire after 7 days while the app is in Testing with an External user type. You re-consent weekly. Moving to Internal removes the limit but needs a Workspace account; publishing removes it but needs verification. For a personal tool, weekly re-auth is the price.
  • “This app isn’t verified” is expected in Testing: Advanced → Go to <app> (unsafe).
  • The localhost redirect fails (“127.0.0.1 refused to connect”) when the process that opened the listener has already exited — run the auth step in a terminal you own, not through an agent’s exec tool with a timeout.

Tokens on the wire

Authorization: Bearer ya29.…on every request; the only header that matters POST https://oauth2.googleapis.com/tokengrant_type=refresh_token → a new access token, ~3600 s POST https://oauth2.googleapis.com/revoke?token=…revoke; users can also do it at myaccount.google.com/permissions GET https://oauth2.googleapis.com/tokeninfo?access_token=…what scopes a token really has — the first thing to check on a 403
Enable the API first. A brand-new project returns 403 accessNotConfigured until Gmail API is enabled under APIs & Services. The Model access / consent pages moved in 2025–26; search the console for Google Auth Platform rather than following old screenshots.

Method, Parameter, Schema & Scope Index

Every method with its verb, URL, parameters and quota cost; every parameter with who takes it; every schema field; every scope — read from the discovery document. Type in the filter box, or press /

Users

3

The mailbox itself: profile, push notifications

getProfileGET /profile · 1 u
stopPOST /stop · 50 u
watchPOST /watch · body: WatchRequest · 100 u

Messages

11

The unit of mail; a message is immutable once written

messages.batchDeletePOST /messages/batchDelete · body: BatchDeleteMessagesRequest · 50 u
messages.batchModifyPOST /messages/batchModify · body: BatchModifyMessagesRequest · 50 u
messages.deleteDELETE /messages/{id} · id* · 10 u
messages.getGET /messages/{id} · id*, format=full, metadataHeaders · 20 u
messages.importPOST /messages/import · internalDateSource=dateHeader, neverMarkSpam=false, processForCalendar=false, deleted=false · body: Message · 25 u
messages.insertPOST /messages · internalDateSource=receivedTime, deleted=false · body: Message · 25 u
messages.listGET /messages · pageToken, maxResults=100, labelIds, includeSpamTrash=false, q · 5 u
messages.modifyPOST /messages/{id}/modify · id* · body: ModifyMessageRequest · 5 u
messages.sendPOST /messages/send · body: Message · 100 u
messages.trashPOST /messages/{id}/trash · id* · 20 u
messages.untrashPOST /messages/{id}/untrash · id* · 5 u

Attachments

1

Bodies too large to inline arrive by attachmentId

messages.attachments.getGET /messages/{messageId}/attachments/{id} · messageId*, id* · 20 u

Threads

6

A conversation; modify/trash apply to every message in it

threads.deleteDELETE /threads/{id} · id* · 20 u
threads.getGET /threads/{id} · id*, format=full, metadataHeaders · 40 u
threads.listGET /threads · includeSpamTrash=false, q, pageToken, labelIds, maxResults=100 · 10 u
threads.modifyPOST /threads/{id}/modify · id* · body: ModifyThreadRequest · 10 u
threads.trashPOST /threads/{id}/trash · id* · 20 u
threads.untrashPOST /threads/{id}/untrash · id* · 10 u

Drafts

6

Unsent messages; drafts.send delivers one

drafts.createPOST /drafts · body: Draft · 10 u
drafts.deleteDELETE /drafts/{id} · id* · 10 u
drafts.getGET /drafts/{id} · id*, format=full · 20 u
drafts.listGET /drafts · includeSpamTrash=false, q, pageToken, maxResults=100 · 5 u
drafts.sendPOST /drafts/send · body: Draft · 100 u
drafts.updatePUT /drafts/{id} · id* · body: Draft · 15 u

Labels

6

System labels (INBOX, UNREAD, …) and user labels

labels.createPOST /labels · body: Label · 5 u
labels.deleteDELETE /labels/{id} · id* · 5 u
labels.getGET /labels/{id} · id* · 1 u
labels.listGET /labels · 1 u
labels.patchPATCH /labels/{id} · id* · body: Label · 5 u
labels.updatePUT /labels/{id} · id* · body: Label · 5 u

History

1

The change log that makes incremental sync possible

history.listGET /history · labelId, startHistoryId, pageToken, historyTypes, maxResults=100 · 2 u

Settings

10

Per-mailbox settings: IMAP, POP, vacation, language, forwarding

settings.getAutoForwardingGET /settings/autoForwarding · 1 u
settings.getImapGET /settings/imap · 1 u
settings.getLanguageGET /settings/language · 1 u
settings.getPopGET /settings/pop · 1 u
settings.getVacationGET /settings/vacation · 1 u
settings.updateAutoForwardingPUT /settings/autoForwarding · body: AutoForwarding · 5 u
settings.updateImapPUT /settings/imap · body: ImapSettings · 5 u
settings.updateLanguagePUT /settings/language · body: LanguageSettings · 5 u
settings.updatePopPUT /settings/pop · body: PopSettings · 100 u
settings.updateVacationPUT /settings/vacation · body: VacationSettings · 5 u

Settings · sendAs

7

Send-as aliases and their signatures

settings.sendAs.createPOST /settings/sendAs · body: SendAs · 100 u
settings.sendAs.deleteDELETE /settings/sendAs/{sendAsEmail} · sendAsEmail* · 5 u
settings.sendAs.getGET /settings/sendAs/{sendAsEmail} · sendAsEmail* · 1 u
settings.sendAs.listGET /settings/sendAs · 1 u
settings.sendAs.patchPATCH /settings/sendAs/{sendAsEmail} · sendAsEmail* · body: SendAs · 100 u
settings.sendAs.updatePUT /settings/sendAs/{sendAsEmail} · sendAsEmail* · body: SendAs · 100 u
settings.sendAs.verifyPOST /settings/sendAs/{sendAsEmail}/verify · sendAsEmail* · 100 u

Settings · S/MIME

5

S/MIME certificates on a send-as alias

settings.sendAs.smimeInfo.deleteDELETE /settings/sendAs/{sendAsEmail}/smimeInfo/{id} · sendAsEmail*, id*
settings.sendAs.smimeInfo.getGET /settings/sendAs/{sendAsEmail}/smimeInfo/{id} · sendAsEmail*, id*
settings.sendAs.smimeInfo.insertPOST /settings/sendAs/{sendAsEmail}/smimeInfo · sendAsEmail* · body: SmimeInfo
settings.sendAs.smimeInfo.listGET /settings/sendAs/{sendAsEmail}/smimeInfo · sendAsEmail*
settings.sendAs.smimeInfo.setDefaultPOST /settings/sendAs/{sendAsEmail}/smimeInfo/{id}/setDefault · sendAsEmail*, id*

Settings · filters

4

Server-side filters: criteria + action

settings.filters.createPOST /settings/filters · body: Filter · 5 u
settings.filters.deleteDELETE /settings/filters/{id} · id* · 5 u
settings.filters.getGET /settings/filters/{id} · id* · 1 u
settings.filters.listGET /settings/filters · 1 u

Settings · forwarding

4

Verified forwarding targets

settings.forwardingAddresses.createPOST /settings/forwardingAddresses · body: ForwardingAddress · 100 u
settings.forwardingAddresses.deleteDELETE /settings/forwardingAddresses/{forwardingEmail} · forwardingEmail* · 5 u
settings.forwardingAddresses.getGET /settings/forwardingAddresses/{forwardingEmail} · forwardingEmail* · 1 u
settings.forwardingAddresses.listGET /settings/forwardingAddresses · 1 u

Settings · delegates

4

Other accounts allowed to read and send

settings.delegates.createPOST /settings/delegates · body: Delegate · 100 u
settings.delegates.deleteDELETE /settings/delegates/{delegateEmail} · delegateEmail* · 5 u
settings.delegates.getGET /settings/delegates/{delegateEmail} · delegateEmail* · 1 u
settings.delegates.listGET /settings/delegates · 1 u

Settings · CSE identities

5

Client-side encryption identities (Workspace)

settings.cse.identities.createPOST /settings/cse/identities · body: CseIdentity
settings.cse.identities.deleteDELETE /settings/cse/identities/{cseEmailAddress} · cseEmailAddress*
settings.cse.identities.getGET /settings/cse/identities/{cseEmailAddress} · cseEmailAddress*
settings.cse.identities.listGET /settings/cse/identities · pageToken, pageSize=20
settings.cse.identities.patchPATCH /settings/cse/identities/{emailAddress} · emailAddress* · body: CseIdentity

Settings · CSE key pairs

6

Client-side encryption key pairs (Workspace)

settings.cse.keypairs.createPOST /settings/cse/keypairs · chainValidation=all · body: CseKeyPair
settings.cse.keypairs.disablePOST /settings/cse/keypairs/{keyPairId}:disable · keyPairId* · body: DisableCseKeyPairRequest
settings.cse.keypairs.enablePOST /settings/cse/keypairs/{keyPairId}:enable · keyPairId* · body: EnableCseKeyPairRequest
settings.cse.keypairs.getGET /settings/cse/keypairs/{keyPairId} · keyPairId*
settings.cse.keypairs.listGET /settings/cse/keypairs · pageSize=20, pageToken
settings.cse.keypairs.obliteratePOST /settings/cse/keypairs/{keyPairId}:obliterate · keyPairId* · body: ObliterateCseKeyPairRequest

Method parameters

24

Every path and query parameter, and who takes it

chainValidationquery, string, one of all|none, default all · The type of certificate chain validation to perform at creation
cseEmailAddresspath, string · The primary email address associated with the client-side encryption identity configuration that's removed
delegateEmailpath, string · The email address of the user to be removed as a delegate
deletedquery, boolean, default false · Mark the email as permanently deleted (not TRASH) and only visible in Google Vault to a Vault administrator
emailAddresspath, string · The email address of the client-side encryption identity to update
formatquery, string, one of full|metadata|minimal, default full · The format to return the messages in
forwardingEmailpath, string · The forwarding address to be retrieved
historyTypesquery, string, one of messageAdded|messageDeleted|labelAdded|labelRemoved, repeated · History types to be returned by the function
idpath, string · The ID of the thread to remove from Trash
includeSpamTrashquery, boolean, default false · Include threads from `SPAM` and `TRASH` in the results
internalDateSourcequery, string, one of receivedTime|dateHeader, default dateHeader · Source for Gmail's internal date of the message
keyPairIdpath, string · The identifier of the key pair to turn on
labelIdquery, string · Only return messages with a label matching the ID
labelIdsquery, string, repeated · Only return threads with labels that match all of the specified label IDs
maxResultsquery, integer, default 100 · Maximum number of history records to return
messageIdpath, string · The ID of the message containing the attachment
metadataHeadersquery, string, repeated · When given and format is METADATA, only include headers specified
neverMarkSpamquery, boolean, default false · Ignore the Gmail spam classifier decision and never mark this email as SPAM in the mailbox
pageSizequery, integer, default 20 · The number of identities to return
pageTokenquery, string · Page token to retrieve a specific page of results in the list
processForCalendarquery, boolean, default false · Process calendar invites in the email and add any extracted meetings to the Google Calendar for this user
qquery, string · Only return threads matching the specified query
sendAsEmailpath, string · The send-as alias to be updated
startHistoryIdquery, string · Required

Standard query parameters

11

Accepted by every Google API method

oauth_tokenstring · OAuth 2.0 token for the current user
keystring · API key
$.xgafvstring, one of 1|2 · V1 error format
upload_protocolstring · Upload protocol for media (e.g
access_tokenstring · OAuth access token
altstring, one of json|media|proto, default json · Data format for response
prettyPrintboolean, default true · Returns response with indentations and line breaks
fieldsstring · Selector specifying which fields to include in a partial response
quotaUserstring · Available to use for quota purposes for server-side applications
callbackstring · JSONP
uploadTypestring · Legacy upload protocol for media (e.g

OAuth scopes

14

From least to most privilege

mail.google.comRead, compose, send, and permanently delete all your email from Gmail
gmail.labelsSee and edit your email labels
gmail.modifyRead, compose, and send emails from your Gmail account
gmail.addons.current.message.actionView your email messages when you interact with the add-on
gmail.addons.current.message.readonlyView your email messages when the add-on is running
gmail.settings.sharingManage your sensitive mail settings, including who can manage your mail
gmail.composeManage drafts and send emails
gmail.settings.basicSee, edit, create, or change your email settings and filters in Gmail
gmail.insertAdd emails into your Gmail mailbox
gmail.addons.current.message.metadataView your email message metadata when the add-on is running
gmail.readonlyView your email messages and settings
gmail.addons.current.action.composeManage drafts and send emails when you interact with the add-on
gmail.metadataView your email message metadata such as labels and headers, but not the email body
gmail.sendSend email on your behalf

Schemas

175

Message — An email message

Message.labelIdsarray of string · List of IDs of labels applied to this message
Message.sizeEstimateinteger int32 · Estimated size in bytes of the message
Message.rawstring byte · The entire email message in an RFC 2822 formatted and base64url encoded string
Message.threadIdstring · The ID of the thread the message belongs to
Message.payload&rarr; MessagePart · The parsed email structure in the message parts
Message.historyIdstring uint64 · The ID of the last history record that modified this message
Message.classificationLabelValuesarray of ClassificationLabelValue · Classification Label values on the message
Message.idstring · The immutable ID of the message
Message.internalDatestring int64 · The internal message creation timestamp (epoch ms), which determines ordering in the inbox
Message.snippetstring · A short part of the message text

MessagePart — A single MIME message part

MessagePart.mimeTypestring · The MIME type of the message part
MessagePart.body&rarr; MessagePartBody · The message part body for this part, which may be empty for container MIME message parts
MessagePart.filenamestring · The filename of the attachment
MessagePart.headersarray of MessagePartHeader · List of headers on this message part
MessagePart.partsarray of MessagePart · The child MIME message parts of this part
MessagePart.partIdstring · The immutable ID of the message part

MessagePartBody — The body of a single MIME message part

MessagePartBody.attachmentIdstring · When present, contains the ID of an external attachment that can be retrieved in a separate `messages.attachments.get` request
MessagePartBody.datastring byte · The body data of a MIME message part as a base64url encoded string
MessagePartBody.sizeinteger int32 · Number of bytes for the message part data (encoding notwithstanding)

MessagePartHeader — fields

MessagePartHeader.valuestring · The value of the header after the `:` separator
MessagePartHeader.namestring · The name of the header before the `:` separator

Thread — A collection of messages representing a conversation

Thread.historyIdstring uint64 · The ID of the last history record that modified this thread
Thread.snippetstring · A short part of the message text
Thread.idstring · The unique ID of the thread
Thread.messagesarray of Message · The list of messages in the thread

Draft — A draft email in the user's mailbox

Draft.idstring · The immutable ID of the draft
Draft.message&rarr; Message · The message content of the draft

Label — Labels are used to categorize messages and threads within the user's mailbox

Label.color&rarr; LabelColor · The color to assign to the label
Label.namestring · The display name of the label
Label.idstring · The immutable ID of the label
Label.labelListVisibilitystring (labelShow|labelShowIfUnread|labelHide) · The visibility of the label in the label list in the Gmail web interface
Label.typestring (system|user) · The owner type for the label
Label.messagesUnreadinteger int32 · The number of unread messages with the label
Label.messagesTotalinteger int32 · The total number of messages with the label
Label.threadsUnreadinteger int32 · The number of unread threads with the label
Label.messageListVisibilitystring (show|hide) · The visibility of messages with this label in the message list in the Gmail web interface
Label.threadsTotalinteger int32 · The total number of threads with the label

LabelColor — fields

LabelColor.backgroundColorstring · The background color represented as hex string #RRGGBB (ex #000000)
LabelColor.textColorstring · The text color of the label, represented as hex string

Profile — Profile for a Gmail user

Profile.messagesTotalinteger int32 · The total number of messages in the mailbox
Profile.threadsTotalinteger int32 · The total number of threads in the mailbox
Profile.emailAddressstring · The user's email address
Profile.historyIdstring uint64 · The ID of the mailbox's current history record

History — A record of a change to the user's mailbox

History.idstring uint64 · The mailbox sequence ID
History.messagesDeletedarray of HistoryMessageDeleted · Messages deleted (not Trashed) from the mailbox in this history record
History.labelsAddedarray of HistoryLabelAdded · Labels added to messages in this history record
History.labelsRemovedarray of HistoryLabelRemoved · Labels removed from messages in this history record
History.messagesarray of Message · List of messages changed in this history record
History.messagesAddedarray of HistoryMessageAdded · Messages added to the mailbox in this history record

HistoryMessageAdded — fields

HistoryMessageAdded.message&rarr; Message ·

HistoryMessageDeleted — fields

HistoryMessageDeleted.message&rarr; Message ·

HistoryLabelAdded — fields

HistoryLabelAdded.message&rarr; Message ·
HistoryLabelAdded.labelIdsarray of string · Label IDs added to the message

HistoryLabelRemoved — fields

HistoryLabelRemoved.message&rarr; Message ·
HistoryLabelRemoved.labelIdsarray of string · Label IDs removed from the message

WatchRequest — Set up or update a new push notification watch on this user's mailbox

WatchRequest.labelFilterBehaviorstring (include|exclude) · Filtering behavior of `labelIds list` specified
WatchRequest.labelFilterActionstring (include|exclude) · Filtering behavior of `labelIds list` specified
WatchRequest.labelIdsarray of string · List of label_ids to restrict notifications about
WatchRequest.topicNamestring · A fully qualified Google Cloud Pub/Sub API topic name to publish the events to

WatchResponse — Push notification watch response

WatchResponse.historyIdstring uint64 · The ID of the mailbox's current history record
WatchResponse.expirationstring int64 · When Gmail will stop sending notifications for mailbox updates (epoch millis)

Filter — Resource definition for Gmail filters

Filter.action&rarr; FilterAction · Action that the filter performs
Filter.idstring · The server assigned ID of the filter
Filter.criteria&rarr; FilterCriteria · Matching criteria for the filter

FilterCriteria — Message matching criteria

FilterCriteria.tostring · The recipient's display name or email address
FilterCriteria.sizeinteger int32 · The size of the entire RFC822 message in bytes, including all headers and attachments
FilterCriteria.sizeComparisonstring (unspecified|smaller|larger) · How the message size in bytes should be in relation to the size field
FilterCriteria.subjectstring · Case-insensitive phrase found in the message's subject
FilterCriteria.hasAttachmentboolean · Whether the message has any attachment
FilterCriteria.fromstring · The sender's display name or email address
FilterCriteria.querystring · Only return messages matching the specified query
FilterCriteria.negatedQuerystring · Only return messages not matching the specified query
FilterCriteria.excludeChatsboolean · Whether the response should exclude chats

FilterAction — A set of actions to perform on a message

FilterAction.addLabelIdsarray of string · List of labels to add to the message
FilterAction.removeLabelIdsarray of string · List of labels to remove from the message
FilterAction.forwardstring · Email address that the message should be forwarded to

SendAs — Settings associated with a send-as alias, which can be either the primary login address associated with the account or a custom "from" address

SendAs.isDefaultboolean · Whether this address is selected as the default "From:" address in situations such as composing a new message or sending a vacation auto-reply
SendAs.smtpMsa&rarr; SmtpMsa · An optional SMTP service that will be used as an outbound relay for mail sent using this alias
SendAs.verificationStatusstring (verificationStatusUnspecified|accepted|pending) · Indicates whether this address has been verified for use as a send-as alias
SendAs.replyToAddressstring · An optional email address that is included in a "Reply-To:" header for mail sent using this alias
SendAs.displayNamestring · A name that appears in the "From:" header for mail sent using this alias
SendAs.signaturestring · An optional HTML signature that is included in messages composed with this alias in the Gmail web UI
SendAs.sendAsEmailstring · The email address that appears in the "From:" header for mail sent using this alias
SendAs.isPrimaryboolean · Whether this address is the primary address used to login to the account
SendAs.treatAsAliasboolean · Whether Gmail should treat this address as an alias for the user's primary email address

SmtpMsa — Configuration for communication with an SMTP service

SmtpMsa.passwordstring · The password that will be used for authentication with the SMTP service
SmtpMsa.hoststring · The hostname of the SMTP service
SmtpMsa.portinteger int32 · The port of the SMTP service
SmtpMsa.usernamestring · The username that will be used for authentication with the SMTP service
SmtpMsa.securityModestring (securityModeUnspecified|none|ssl|starttls) · The protocol that will be used to secure communication with the SMTP service

SmimeInfo — An S/MIME email config

SmimeInfo.idstring · The immutable ID for the SmimeInfo
SmimeInfo.pemstring · PEM formatted X509 concatenated certificate string (standard base64 encoding)
SmimeInfo.isDefaultboolean · Whether this SmimeInfo is the default one for this user's send-as address
SmimeInfo.expirationstring int64 · When the certificate expires (in milliseconds since epoch)
SmimeInfo.pkcs12string byte · PKCS#12 format containing a single private/public key pair and certificate chain
SmimeInfo.encryptedKeyPasswordstring · Encrypted key password, when key is encrypted
SmimeInfo.issuerCnstring · The S/MIME certificate issuer's common name

VacationSettings — Vacation auto-reply settings for an account

VacationSettings.restrictToDomainboolean · Flag that determines whether responses are sent to recipients who are outside of the user's domain
VacationSettings.enableAutoReplyboolean · Flag that controls whether Gmail automatically replies to messages
VacationSettings.responseSubjectstring · Optional text to prepend to the subject line in vacation responses
VacationSettings.responseBodyHtmlstring · Response body in HTML format
VacationSettings.responseBodyPlainTextstring · Response body in plain text format
VacationSettings.restrictToContactsboolean · Flag that determines whether responses are sent to recipients who are not in the user's list of contacts
VacationSettings.startTimestring int64 · An optional start time for sending auto-replies (epoch ms)
VacationSettings.endTimestring int64 · An optional end time for sending auto-replies (epoch ms)

AutoForwarding — Auto-forwarding settings for an account

AutoForwarding.enabledboolean · Whether all incoming mail is automatically forwarded to another address
AutoForwarding.emailAddressstring · Email address to which all incoming messages are forwarded
AutoForwarding.dispositionstring (dispositionUnspecified|leaveInInbox|archive|trash|markRead) · The state that a message should be left in after it has been forwarded

ForwardingAddress — Settings for a forwarding address

ForwardingAddress.forwardingEmailstring · An email address to which messages can be forwarded
ForwardingAddress.verificationStatusstring (verificationStatusUnspecified|accepted|pending) · Indicates whether this address has been verified and is usable for forwarding

ImapSettings — IMAP settings for an account

ImapSettings.enabledboolean · Whether IMAP is enabled for the account
ImapSettings.autoExpungeboolean · If this value is true, Gmail will immediately expunge a message when it is marked as deleted in IMAP
ImapSettings.expungeBehaviorstring (expungeBehaviorUnspecified|archive|trash|deleteForever) · The action that will be executed on a message when it is marked as deleted and expunged from the last visible IMAP folder
ImapSettings.maxFolderSizeinteger int32 · An optional limit on the number of messages that an IMAP folder may contain

PopSettings — POP settings for an account

PopSettings.dispositionstring (dispositionUnspecified|leaveInInbox|archive|trash|markRead) · The action that will be executed on a message after it has been fetched via POP
PopSettings.accessWindowstring (accessWindowUnspecified|disabled|fromNowOn|allMail) · The range of messages which are accessible via POP

LanguageSettings — Language settings for an account

LanguageSettings.displayLanguagestring · The language to display Gmail in, formatted as an RFC 3066 Language Tag (for example `en-GB`, `fr` or `ja` for British English, French, or Japanese respectively)

Delegate — Settings for a delegate

Delegate.verificationStatusstring (verificationStatusUnspecified|accepted|pending|rejected|expired) · Indicates whether this address has been verified and can act as a delegate for the account
Delegate.delegateEmailstring · The email address of the delegate

ModifyMessageRequest — fields

ModifyMessageRequest.addLabelIdsarray of string · A list of IDs of labels to add to this message
ModifyMessageRequest.removeClassificationLabelIdsarray of string · A list of Classification Label values to remove from this message
ModifyMessageRequest.removeLabelIdsarray of string · A list IDs of labels to remove from this message
ModifyMessageRequest.addClassificationLabelsarray of ClassificationLabelValue · A list of classification label values to add

ModifyThreadRequest — fields

ModifyThreadRequest.removeLabelIdsarray of string · A list of IDs of labels to remove from this thread
ModifyThreadRequest.addLabelIdsarray of string · A list of IDs of labels to add to this thread

BatchDeleteMessagesRequest — fields

BatchDeleteMessagesRequest.idsarray of string · The IDs of the messages to delete

BatchModifyMessagesRequest — fields

BatchModifyMessagesRequest.addLabelIdsarray of string · A list of label IDs to add to messages
BatchModifyMessagesRequest.removeLabelIdsarray of string · A list of label IDs to remove from messages
BatchModifyMessagesRequest.addClassificationLabelsarray of ClassificationLabelValue · A list of Classification Label values to add
BatchModifyMessagesRequest.idsarray of string · The IDs of the messages to modify
BatchModifyMessagesRequest.removeClassificationLabelIdsarray of string · A list of Classification Label values to remove from messages

ListMessagesResponse — fields

ListMessagesResponse.resultSizeEstimateinteger uint32 · Estimated total number of results
ListMessagesResponse.messagesarray of Message · List of messages
ListMessagesResponse.nextPageTokenstring · Token to retrieve the next page of results in the list

ListThreadsResponse — fields

ListThreadsResponse.nextPageTokenstring · Page token to retrieve the next page of results in the list
ListThreadsResponse.threadsarray of Thread · List of threads
ListThreadsResponse.resultSizeEstimateinteger uint32 · Estimated total number of results

ListHistoryResponse — fields

ListHistoryResponse.historyIdstring uint64 · The ID of the mailbox's current history record
ListHistoryResponse.historyarray of History · List of history records
ListHistoryResponse.nextPageTokenstring · Page token to retrieve the next page of results in the list

ListLabelsResponse — fields

ListLabelsResponse.labelsarray of Label · List of labels

ListDraftsResponse — fields

ListDraftsResponse.nextPageTokenstring · Token to retrieve the next page of results in the list
ListDraftsResponse.draftsarray of Draft · List of drafts
ListDraftsResponse.resultSizeEstimateinteger uint32 · Estimated total number of results

CseIdentity — The client-side encryption (CSE) configuration for the email address of an authenticated user

CseIdentity.emailAddressstring · The email address for the sending identity
CseIdentity.signAndEncryptKeyPairs&rarr; SignAndEncryptKeyPairs · The configuration of a CSE identity that uses different key pairs for signing and encryption
CseIdentity.primaryKeyPairIdstring · If a key pair is associated, the ID of the key pair, CseKeyPair

CseKeyPair — A client-side encryption S/MIME key pair, which is comprised of a public key, its certificate chain, and metadata for its paired private key

CseKeyPair.subjectEmailAddressesarray of string · Output only
CseKeyPair.disableTimestring google-datetime · Output only
CseKeyPair.pkcs7string · Input only
CseKeyPair.pemstring · Output only
CseKeyPair.privateKeyMetadataarray of CsePrivateKeyMetadata · Metadata for instances of this key pair's private key
CseKeyPair.keyPairIdstring · Output only
CseKeyPair.enablementStatestring (stateUnspecified|enabled|disabled) · Output only

KaclsKeyMetadata — Metadata for private keys managed by an external key access control list service

KaclsKeyMetadata.kaclsUristring · The URI of the key access control list service that manages the private key
KaclsKeyMetadata.kaclsDatastring · Opaque data generated and used by the key access control list service

HardwareKeyMetadata — Metadata for hardware keys

HardwareKeyMetadata.descriptionstring · Description about the hardware key

CsePrivateKeyMetadata — Metadata for a private key instance

CsePrivateKeyMetadata.kaclsKeyMetadata&rarr; KaclsKeyMetadata · Metadata for a private key instance managed by an external key access control list service
CsePrivateKeyMetadata.privateKeyMetadataIdstring · Output only
CsePrivateKeyMetadata.hardwareKeyMetadata&rarr; HardwareKeyMetadata · Metadata for hardware keys

SignAndEncryptKeyPairs — The configuration of a CSE identity that uses different key pairs for signing and encryption

SignAndEncryptKeyPairs.signingKeyPairIdstring · The ID of the CseKeyPair that signs outgoing mail
SignAndEncryptKeyPairs.encryptionKeyPairIdstring · The ID of the CseKeyPair that encrypts signed outgoing mail

ClassificationLabelFieldValue — Field values for a classification label

ClassificationLabelFieldValue.fieldIdstring · Required
ClassificationLabelFieldValue.selectionstring · Selection choice ID for the selection option

ClassificationLabelValue — Classification Labels applied to the email message

ClassificationLabelValue.labelIdstring · Required
ClassificationLabelValue.fieldsarray of ClassificationLabelFieldValue · Field values for the given classification label ID

ListCseIdentitiesResponse — fields

ListCseIdentitiesResponse.nextPageTokenstring · Pagination token to be passed to a subsequent ListCseIdentities call in order to retrieve the next page of identities
ListCseIdentitiesResponse.cseIdentitiesarray of CseIdentity · One page of the list of CSE identities configured for the user

ListCseKeyPairsResponse — fields

ListCseKeyPairsResponse.cseKeyPairsarray of CseKeyPair · One page of the list of CSE key pairs installed for the user
ListCseKeyPairsResponse.nextPageTokenstring · Pagination token to be passed to a subsequent ListCseKeyPairs call in order to retrieve the next page of key pairs

ListDelegatesResponse — Response for the ListDelegates method

ListDelegatesResponse.delegatesarray of Delegate · List of the user's delegates (with any verification status)

ListFiltersResponse — Response for the ListFilters method

ListFiltersResponse.filterarray of Filter · List of a user's filters

ListForwardingAddressesResponse — Response for the ListForwardingAddresses method

ListForwardingAddressesResponse.forwardingAddressesarray of ForwardingAddress · List of addresses that may be used for forwarding

ListSendAsResponse — Response for the ListSendAs method

ListSendAsResponse.sendAsarray of SendAs · List of send-as aliases

ListSmimeInfoResponse — fields

ListSmimeInfoResponse.smimeInfoarray of SmimeInfo · List of SmimeInfo

Quota units

63

Per call, most expensive first · 6,000 units per user per minute

drafts.send100 units
messages.send100 units
settings.delegates.create100 units
settings.forwardingAddresses.create100 units
settings.sendAs.create100 units
settings.sendAs.patch100 units
settings.sendAs.update100 units
settings.sendAs.verify100 units
settings.updatePop100 units
watch100 units
messages.batchDelete50 units
messages.batchModify50 units
stop50 units
threads.get40 units
messages.import25 units
messages.insert25 units
drafts.get20 units
messages.attachments.get20 units
messages.get20 units
messages.trash20 units
threads.delete20 units
threads.trash20 units
drafts.update15 units
drafts.create10 units
drafts.delete10 units
messages.delete10 units
threads.list10 units
threads.modify10 units
threads.untrash10 units
drafts.list5 units
labels.create5 units
labels.delete5 units
labels.patch5 units
labels.update5 units
messages.list5 units
messages.modify5 units
messages.untrash5 units
settings.delegates.delete5 units
settings.filters.create5 units
settings.filters.delete5 units
settings.forwardingAddresses.delete5 units
settings.sendAs.delete5 units
settings.updateAutoForwarding5 units
settings.updateImap5 units
settings.updateLanguage5 units
settings.updateVacation5 units
history.list2 units
getProfile1 units
labels.get1 units
labels.list1 units
settings.delegates.get1 units
settings.delegates.list1 units
settings.filters.get1 units
settings.filters.list1 units
settings.forwardingAddresses.get1 units
settings.forwardingAddresses.list1 units
settings.getAutoForwarding1 units
settings.getImap1 units
settings.getLanguage1 units
settings.getPop1 units
settings.getVacation1 units
settings.sendAs.get1 units
settings.sendAs.list1 units