margin-mail/docs/research/gmail-api.md

Gmail API capability map

What the Gmail REST API (v1) and its neighbours can and cannot do for a native desktop client (Tauri 2, Rust backend, React frontend) that wants HEY and Superhuman style workflows on top of a user's Gmail account. Everything below was checked against the live Google docs on 2026-09-03 unless marked "unverified" or "third-party".

One headline before the detail: the Gmail API usage limits changed on 1 May 2026. The per-user rate limit is now 6,000 quota units per minute (100 per second, not the 250 per second most older write-ups quote), messages.get costs 20 units (not 5) and threads.get costs 40 (not 10). Every quota figure in this document uses the new table. Plan sync around it.

1. Auth and distribution

Scopes

Scope	Unlocks	Class
https://mail.google.com/	Everything, including permanent delete (messages.delete, batchDelete, threads.delete) and IMAP/SMTP via XOAUTH2. The only scope IMAP accepts.	Restricted
https://www.googleapis.com/auth/gmail.modify	Read, list, modify labels, trash/untrash, send, drafts, insert/import, history, watch. Not permanent delete.	Restricted
https://www.googleapis.com/auth/gmail.readonly	Read and list only, including history and watch.	Restricted
https://www.googleapis.com/auth/gmail.compose	Drafts create/update/send and messages.send. No reading.	Restricted
https://www.googleapis.com/auth/gmail.send	messages.send only.	Sensitive
https://www.googleapis.com/auth/gmail.insert	messages.insert and messages.import.	Restricted
https://www.googleapis.com/auth/gmail.labels	labels.* only.	Non-sensitive
https://www.googleapis.com/auth/gmail.metadata	List and read headers and labels, never bodies. format=full and format=raw are refused, and messages.list refuses the q parameter under this scope.	Restricted
https://www.googleapis.com/auth/gmail.settings.basic	Filters, vacation responder, IMAP/POP/language settings, update of the primary send-as (signature, display name).	Restricted
https://www.googleapis.com/auth/gmail.settings.sharing	Send-as alias create/delete/verify, forwarding addresses, auto-forwarding, delegates. Every one of these methods is documented as "only available to service account clients that have been delegated domain-wide authority", so a consumer desktop client cannot use them at all.	Restricted
https://www.googleapis.com/auth/contacts.other.readonly	People API otherContacts.list and otherContacts.search (the auto-collected "people you emailed" set that powers Gmail autocomplete).	Sensitive (third-party classification, unverified against Google's master list)
https://www.googleapis.com/auth/contacts.readonly	People API people.connections.list, people.searchContacts.	Sensitive (unverified, as above)
https://www.googleapis.com/auth/calendar.events	Calendar events.list, events.patch, events.import for RSVP.	Sensitive (unverified)
https://www.googleapis.com/auth/pubsub	Only needed if the client itself pulls from a Pub/Sub subscription. See section 3.	Cloud scope, not a Gmail scope

Minimum set for the product as described: gmail.modify (which covers gmail.labels), gmail.settings.basic, contacts.other.readonly, contacts.readonly, and calendar.events if you do RSVP. Add https://mail.google.com/ only if you use IMAP or want permanent delete. Any Gmail scope beyond gmail.send and gmail.labels is restricted, so there is no scope choice that avoids restricted-scope verification for a real mail client.

What verification means in practice

Publishing status and user caps, quoted from Google's "Manage App Audience" page:

• Testing: "up to 100 test users listed in the OAuth consent screen". Every test user must be added by email address by the project owner. "Authorizations by a test user will expire seven days from the time of consent", and that includes the refresh token. The only exception is apps that request nothing beyond name, email and profile. A mail client in Testing therefore forces a full re-login every 7 days. Do not ship in Testing.
• In production, unverified: any Google account can be presented with the "unverified app" interstitial and click through. The project gets "100 new users in total" for its lifetime; the cap "cannot be reset". Refresh tokens do not have the 7-day expiry in this state.
• In production, verified: no cap, no interstitial (after brand verification the app name and logo show on the consent screen).

Verification tiers and timelines:

• Brand verification (name and logo only): "typically takes 2-3 business days".
• Sensitive scope verification: "typically takes 3-5 business days". Requires a domain verified in Search Console, a public homepage on that domain, a privacy policy hosted on the same domain and linked from the consent screen, an unlisted YouTube demo showing the consent flow with the client ID visible in the address bar and each scope in use, and a written justification per scope.
• Restricted scope verification: all of the above plus Limited Use compliance, and the process "can potentially take several weeks". Re-verification is annual.
• Security assessment (CASA, run by the App Defense Alliance): Google's wording is "Every app that requests access to Google users' restricted data and has the ability to access data from or through a third-party server must go through a security assessment from Google-empanelled security assessors." Assessments are assigned an assurance level (AL1 or AL2) and "All applications must be revalidated every year." Third-party pricing for the common Tier 2 / lab-verified scan is roughly USD 540 to 1,800 per year (TAC Security via switchlabs.dev, 2025 to 2026); older figures of USD 15,000 to 75,000 (Nylas, 2021) refer to the original pentest regime and are stale.

The open question that decides Margin's cost: a desktop client whose only server is Google, with all mail data on the user's disk, does not obviously "access data from or through a third-party server". Google publishes no explicit "local-only apps are exempt" clause, so treat this as unverified and ask the verification team in writing before you build a push relay (a relay that sees only the user's email address and a historyId, as Mimestream's does, may or may not count). Mimestream states it "applied for and completed Google's Restricted scope verification process" and that "Mimestream stores user email data locally on the user's device", but does not say whether it was assessed.

Exemptions Google lists for verification itself: "personal use (fewer than 100 users)", apps in development/testing/staging, service-account-only apps, and internal Workspace apps. None of these is a distribution strategy.

Bring your own OAuth client

The pattern: each user creates their own Google Cloud project, enables the Gmail API, configures an External consent screen, adds every scope, creates a "Desktop app" OAuth client, and pastes the client ID and secret into Margin. Each user is then the "developer" of a one-user app, which falls under the personal-use exemption and needs no verification. It works, and several open-source tools ship this way.

It is not realistic for non-technical friends. It is fifteen to twenty clicks across a console whose UI changes every few months, it needs the People API and Calendar API enabled separately, the consent screen must either stay in Testing (7-day re-login) or be pushed to production (scary interstitial, but stable tokens), and support requests will all be "the Google page looks different". Offer it as an escape hatch for the technical, not as the default.

Installed-app OAuth flow

Use the loopback flow: OAuth client type "Desktop app", redirect to http://127.0.0.1:{port} (or http://[::1]:{port}) served by a one-shot listener in the Rust backend, PKCE mandatory (verifier 43 to 128 unreserved characters, S256 challenge). Google states "Custom URI schemes are no longer supported due to the risk of app impersonation" and the out-of-band copy-paste flow is gone. The client secret of a Desktop client is not a secret; Google's own doc says installed apps "cannot keep secrets", so embedding it in the binary is expected.

Token facts to design around:

• "refresh tokens are always returned for installed applications".
• "limit of 100 refresh tokens per Google Account per OAuth 2.0 client ID". The oldest is silently invalidated. Per-account, per-client, so a user on many machines is fine.
• A refresh token dies if unused for six months, if the user revokes it, or if "The user changed passwords and the refresh token contains Gmail scopes". Password change logs Margin out. Handle invalid_grant by prompting re-auth, not by crashing sync.
• Access tokens last about an hour. IMAP sessions authenticated with OAuth are "limited to about the validity period of the access token used (usually 1 hour)".

Store refresh tokens in the OS keychain (macOS Keychain, Windows Credential Manager, Secret Service on Linux), never in SQLite.

What a small team shipping to friends should do

Create one Cloud project and one Desktop OAuth client. Push the consent screen to production unverified straight away and eat the interstitial: it costs 100 lifetime users, which is plenty for a friends release and avoids the 7-day token expiry that Testing imposes. In parallel, buy a domain, publish a homepage and privacy policy on it, record the demo video, and submit restricted scope verification with the explicit statement that the app has no server and stores all Google user data on the user's device; ask whether a security assessment is required. Budget for one anyway (order of USD 1,000 to 2,000 per year at the cheap end). Do not request https://mail.google.com/ unless IMAP is in the plan; the narrower the scope list the easier the review.

Sources: https://developers.google.com/workspace/gmail/api/auth/scopes, https://support.google.com/cloud/answer/15549945, https://support.google.com/cloud/answer/7454865, https://support.google.com/cloud/answer/13464323, https://support.google.com/cloud/answer/13465431, https://developers.google.com/identity/protocols/oauth2/production-readiness/restricted-scope-verification, https://developers.google.com/identity/protocols/oauth2/production-readiness/sensitive-scope-verification, https://developers.google.com/identity/protocols/oauth2/native-app, https://developers.google.com/identity/protocols/oauth2 (refresh token expiration), https://developers.google.com/terms/api-services-user-data-policy, https://mimestream.com/trust/security-and-privacy, https://www.switchlabs.dev/post/casa-tier-2-tier-3-security-review-providers-pricing-and-the-cheapest-option (third-party), https://www.nylas.com/blog/google-oauth-app-verification/ (third-party, 2021).

2. Data model

Base URL is https://gmail.googleapis.com/gmail/v1/users/{userId}/...; use me for userId. Uploads go to https://gmail.googleapis.com/upload/gmail/v1/....

Message

Fields: id ("The immutable ID of the message", a 16-hex-digit string), threadId, labelIds[], snippet ("A short part of the message text", HTML-escaped, roughly a sentence), historyId ("The ID of the last history record that modified this message"), internalDate ("The internal message creation timestamp (epoch ms)", the time Gmail received or created it, not the Date header; for insert/import you choose internalDateSource=receivedTime|dateHeader), payload (parsed MIME tree), sizeEstimate (bytes, approximate), raw (base64url RFC 2822 bytes, only with format=raw).

format on messages.get and threads.get:

format	Returns	Notes
minimal	id, threadId, labelIds, snippet, historyId, internalDate, sizeEstimate	No headers. Same 20 units as full.
metadata	minimal plus payload.headers	Pass metadataHeaders=From&metadataHeaders=Subject... to restrict which headers come back. No body parts, no MIME tree.
full	Parsed MIME tree in payload	Body data is base64url in payload.parts[].body.data, or referenced by attachmentId when large.
raw	Whole RFC 2822 message base64url in raw	Best for archival and for feeding a real MIME parser (mail-parser or mailparse in Rust).

MessagePart: partId, mimeType, filename (only present on attachments), headers[] {name, value}, body {attachmentId, size, data}, parts[]. Body data is base64url without padding issues in practice but always decode with a URL-safe, padding-tolerant decoder. Large bodies and every real attachment arrive as attachmentId and must be fetched separately with GET .../messages/{messageId}/attachments/{id} (20 units, returns MessagePartBody {attachmentId, size, data}). Inline images are ordinary parts whose headers carry Content-ID: <foo> and Content-Disposition: inline; the HTML body references them as src="cid:foo", and the client maps cid to the part and serves the bytes to the webview. Attachment IDs are widely reported to change between get calls, so store the partId/Content-ID path, not the attachment ID (unverified in the docs, consistently observed).

Sort and display by internalDate. The Date header is the sender's claim and can be hours off or absent.

Thread

{id, snippet, historyId, messages[]}. threads.get accepts the same format and metadataHeaders and returns every message in the thread in one call for 40 units. Threads cannot be created directly; Gmail assigns threadId on delivery, send, insert or import. Threading rules are in section 4. Gmail's web UI splits a conversation into a new thread with the same subject after 100 messages (third-party, consistently reported, unverified in Google docs).

Labels

System labels the guide lists, and whether modify may add or remove them:

Label	Applicable via API
INBOX	Yes (remove to archive)
SPAM	Yes
TRASH	Yes (prefer trash/untrash methods)
UNREAD	Yes
STARRED	Yes
IMPORTANT	Yes
SENT	No
DRAFT	No
CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS	Yes

"The preceding list isn't exhaustive and other reserved label names exist" (CHAT is one). Creating a user label with a reserved name returns "HTTP 400 - Invalid label name". System label IDs equal their names; user label IDs look like Label_42 and are immutable, while names can be changed with labels.patch, so key everything on ID and re-list labels when history shows anything unexpected.

User label fields: name (a / in the name nests the label in the Gmail UI, so Margin/Snoozed renders under Margin; the parent label should exist first), messageListVisibility (show, hide), labelListVisibility (labelShow, labelShowIfUnread, labelHide), color {textColor, backgroundColor} restricted to a fixed palette of about a hundred hex values listed in the Label resource docs (any other value is rejected), type (system, user), and read-only counts messagesTotal, messagesUnread, threadsTotal, threadsUnread. Hard limit: "Maximum labels per mailbox: 10,000". Name length limit is not documented (the web UI enforces 225 characters, unverified). Labels cannot be applied to drafts.

Drafts

{id, message}. The draft id is stable across drafts.update; the inner message.id changes on every update. drafts.send deletes the draft and returns a new message with a new id and the SENT label. Draft messages only ever carry the DRAFT label.

History and historyId

historyId appears on every message, thread, the profile (users.getProfile, 1 unit, returns emailAddress, messagesTotal, threadsTotal, historyId), and every history.list and watch response. Google: "History IDs increase chronologically but are not contiguous with random gaps in between valid IDs." A history record is {id, messages[], messagesAdded[], messagesDeleted[], labelsAdded[], labelsRemoved[]} where the added/removed entries carry {message: {id, threadId, labelIds?}, labelIds[]}. "We recommend using the specific change-type fields instead of" messages[]. messagesDeleted means permanently deleted, not trashed; trash shows up as labelsAdded with TRASH.

Stable IDs: message id, thread id, label id, draft id (until sent), historyId (as a cursor). Not stable: the message id behind a draft, attachment ids (reported), snippet text (can be regenerated), resultSizeEstimate (an estimate).

Sources: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages, https://developers.google.com/workspace/gmail/api/reference/rest/v1/Format, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages.attachments/get, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads, https://developers.google.com/workspace/gmail/api/guides/labels, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels, https://developers.google.com/workspace/gmail/api/guides/drafts, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list, https://support.cloudhq.net/how-does-gmail-decide-to-group-emails-into-conversations/ (third-party).

3. Sync strategy

Quota, the numbers that matter

"As of May 1, 2026, the usage limits for this API were updated."

Limit	Value
Per minute per user per project	6,000 quota units
Per minute per project	1,200,000 quota units
Per day per project (billing threshold)	80,000,000 quota units
Batch	100 calls max per batch, "larger than 50 requests is not recommended", counted as n requests
Pricing	"All standard use of the Gmail API is available at no additional cost. Exceeding the quota request limits is planned to incur charges to your Google Cloud billing account later in 2026."

Per-method costs (units):

Method	Units	Method	Units
messages.send, drafts.send, watch	100	messages.get, drafts.get, messages.attachments.get, messages.trash	20
threads.get	40	threads.trash, threads.delete	20
messages.batchModify, messages.batchDelete, stop	50	messages.insert, messages.import	25
drafts.update	15	messages.delete, drafts.create, drafts.delete, threads.list, threads.modify	10
messages.list, drafts.list, messages.modify, messages.untrash, labels.create/delete/update, settings.filters.create/delete, settings.updateVacation	5	history.list	2
getProfile, labels.get, labels.list, settings.filters.get/list, settings.getVacation, settings.getAutoForwarding	1	settings.sendAs.create/update/verify, forwardingAddresses.create, delegates.create, updatePop	100

Third-party pages dated 2026 still quote messages.get at 5 and threads.get at 10; Google's page as read on 2026-09-03 says 20 and 40. There is also an undocumented concurrency ceiling per mailbox (Unipile reports "50 concurrent in-flight requests per mailbox"; Google's error page only says 429 can be "triggered by daily per-user limits, bandwidth limits, or concurrent request limits" and "Per-user limits cannot be increased").

What 6,000 units per minute buys: 300 messages.get per minute, or 150 threads.get, or 60 sends. A mailbox with 20,000 messages costs 400,000 units to fetch metadata for every message, which is 67 minutes at the ceiling; 100,000 messages is 5.6 hours. Idle polling of history.list every 15 seconds is 8 units per minute, so polling is free; hydration is what costs.

Initial full sync

1. getProfile and record historyId before you list anything, so the first partial sync covers everything that changed during the crawl.
2. messages.list?maxResults=500&includeSpamTrash=true (5 units per page, ids and threadIds only, newest first) and page with pageToken until exhausted. 20,000 messages is 40 pages, 200 units, a few seconds. Store ids, threadIds and a "needs hydration" flag.
3. Hydrate newest first in batches of 50 messages.get?format=metadata with metadataHeaders limited to what the UI and the classifier need: From, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID, In-Reply-To, References, List-Id, List-Unsubscribe, List-Unsubscribe-Post, Precedence, Authentication-Results, Content-Type. Throttle to roughly 280 gets per minute, retry 429 and 403 userRateLimitExceeded with truncated exponential backoff starting at 1 second, and treat 404 as "deleted since listing".
4. For threads with three or more messages, threads.get?format=metadata (40 units) is cheaper than per-message gets. Group step 2's ids by threadId and route.
5. Bodies: fetch format=full (or raw) lazily on open and prefetch the last N days in the background. Cache decoded HTML and text in SQLite with an LRU cap.
6. Labels: labels.list (1 unit) once, then again whenever history mentions a label id you do not know.

Order of hydration is a product decision: newest 30 days first, then the rest, and the UI must be usable while step 3 is running. Zero (Mail-0) reports initial sync "can take hours for large inboxes (10,000+ emails)"; with the new unit costs that is the norm, not the exception.

Partial sync

history.list?startHistoryId=X&maxResults=500 (2 units per page), optionally historyTypes=messageAdded|messageDeleted|labelAdded|labelRemoved and labelId=. Apply pages in order; the records are chronological by id. For each messagesAdded run messages.get (the record includes labelIds, but not headers); for labelsAdded/labelsRemoved update the local label set; for messagesDeleted delete locally. A message can appear in messagesAdded and messagesDeleted in the same window, and messages.get can 404 for a record you have not processed yet; both are normal, not errors. When the final page has no nextPageToken, store the response historyId as the new cursor. Never combine q with history; history is mailbox-wide and has no query parameter, so every screening decision is made locally on the record's labelIds and the fetched headers.

Google on validity: "A historyId is typically valid for at least a week, but in some rare circumstances may be valid for only a few hours. If you receive an HTTP 404 error response, your application should perform a full sync." The cheap recovery is: re-run step 2 of the full sync (ids only, 5 units per 500), diff against the local set to find adds and deletes, hydrate the adds, and refresh labelIds for the most recent N days with format=minimal (still 20 units each; there is no cheaper label-only read except threads.list, which returns only ids). Accept that label state for old mail may be stale until the user opens it.

Polling cadence

Poll history.list every 10 to 15 seconds while the window is focused, 60 seconds in the background, and immediately after any local write. Cost at 15 seconds is 5,760 units per user per day; 1,000 users idle-polling this way is 5.8 million units per day against the 80 million project threshold. The budget goes to hydration and full syncs, not polling.

Push via Pub/Sub, honestly

users.watch (100 units) with topicName=projects/{project}/topics/{topic} where the project "must exactly match your Google developer project id (the one executing this watch request)". You grant roles/pubsub.publisher on the topic to [email protected]. Watches expire after 7 days and Google says "We recommend calling watch once per day". The notification is only {"emailAddress": "...", "historyId": "..."} and the rate is capped at "one event per second" per user. On receipt you run the partial sync above.

Delivery needs a Pub/Sub subscription. A push subscription posts to an HTTPS endpoint, which means a server. A pull subscription is possible from a desktop app in theory: projects.subscriptions.pull needs the pubsub.subscriptions.consume permission (roles/pubsub.subscriber) on the subscription and a token with https://www.googleapis.com/auth/pubsub or cloud-platform. The problem is the principal. The desktop app authenticates as the end user's Google account, which has no IAM on your project. Your options are to grant every user individually (a server or manual step), grant allAuthenticatedUsers (any Google account on earth could pull and ack everyone's notifications from the shared subscription), or ship a service account key in the binary (extractable, and Google will reject it in review). None is acceptable. Conclusion: with no server there is no push. If you want push later, the minimum is a small relay that owns the subscription and forwards {emailAddress, historyId} to connected clients; Mimestream runs exactly that (push.mimestream.com) and stores only "Email address, APNs device token, Device identifier". That relay may also drag you into the security assessment. Ship with polling.

IMAP as a complement

Gmail IMAP (imap.gmail.com:993, SMTP smtp.gmail.com:465 or 587) authenticates with SASL XOAUTH2 (base64("user=" user "^Aauth=Bearer " token "^A^A")) using the https://mail.google.com/ scope, which is restricted like the rest. Capabilities include IDLE, CONDSTORE, MOVE, UIDPLUS, X-GM-EXT-1 and APPENDLIMIT=35651584; there is no QRESYNC. The Gmail extensions expose X-GM-MSGID (64-bit message id), X-GM-THRID (thread id), X-GM-LABELS (fetch, store and search labels) and X-GM-RAW (full Gmail search syntax over IMAP). The REST id is the lowercase hex of X-GM-MSGID and threadId the hex of X-GM-THRID (widely relied on, verify in a spike before depending on it).

What IMAP does that REST cannot: bulk header fetch with no unit quota (one UID FETCH 1:* (ENVELOPE BODYSTRUCTURE X-GM-LABELS X-GM-THRID X-GM-MSGID) over [Gmail]/All Mail returns tens of thousands of messages in minutes, limited only by the 2,500 MB per day IMAP download bandwidth), and IDLE for near-instant new-mail notification without a server (one connection per watched folder, sessions "limited to about 24 hours" and OAuth sessions to the token lifetime, so reconnect hourly). What REST does that IMAP cannot: history.list (IMAP has no mailbox-wide change log; CONDSTORE gives per-folder MODSEQ only), filters, settings, send-as, vacation, drafts with stable ids, proper SENT threading via threadId, snippets, sizeEstimate, category labels as first-class ids, and batch HTTP. IMAP exceeding bandwidth suspends the account for "1 hour, but can last up to 24 hours".

Reasonable hybrid: REST for everything the user touches and for the change log; IMAP only as an optional accelerator for the initial backfill and for IDLE as a wake-up signal that triggers history.list. That costs you the https://mail.google.com/ scope and a second protocol stack, so do it only if the initial sync time measured with REST alone is unacceptable.

Local mirror

Mimestream keeps everything in a Core Data SQLite store on the Mac and syncs "directly with Google APIs, not through an intermediary service". Do the same: tables for accounts (email, historyId cursor, profile), labels (id, name, type, visibility, colour), messages (id, threadId, internalDate, sizeEstimate, snippet, labelIds as a JSON array or a join table, parsed headers as columns, hydration state), threads (id, latest internalDate, participant summary, derived flags), bodies (message id, html, text, fetched_at), attachments (message id, partId, filename, mimeType, size, content-id, cached path), an outbox, and an FTS5 table over subject, participants and body text. Everything in section 5 marked "client-side" also lives here.

Sources: https://developers.google.com/workspace/gmail/api/reference/quota, https://developers.google.com/workspace/gmail/api/guides/sync, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list, https://developers.google.com/workspace/gmail/api/guides/batch, https://developers.google.com/workspace/gmail/api/guides/handle-errors, https://developers.google.com/workspace/gmail/api/guides/push, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/watch, https://docs.cloud.google.com/pubsub/docs/access-control, https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/pull, https://mimestream.com/trust/private-push, https://developers.google.com/workspace/gmail/imap/imap-extensions, https://developers.google.com/workspace/gmail/imap/xoauth2-protocol, https://developers.google.com/workspace/gmail/imap/imap-smtp, https://knowledge.workspace.google.com/admin/gmail/gmail-bandwidth-limits, https://gist.github.com/emersion/2c769bc1ed60a7b7945910d35b606801 (third-party capability dump), https://www.unipile.com/gmail-api-limits/ (third-party).

4. Writes

Labels and state

• messages.modify (5 units): {addLabelIds[], removeLabelIds[]}.
• messages.batchModify (50 units): same body plus ids[], "There is a limit of 1000 ids per request", empty response, no per-id error report.
• threads.modify (10 units): applies to every message in the thread. Note that "Messages in a thread might have labels that other messages in the same thread don't have", so thread-level views must aggregate.
• Read/unread: remove/add UNREAD. Star: STARRED. Importance: IMPORTANT. Archive: remove INBOX. Spam: add SPAM (removes from inbox in Gmail's view). Category move: remove one CATEGORY_*, add another.
• Trash: messages.trash / threads.trash (20) and untrash (5). Gmail purges trash after 30 days. Permanent delete: messages.delete (10), batchDelete (50), threads.delete (20); these need https://mail.google.com/ (long-standing, unverified in this pass).
• Mute: there is no mute label or method. q=is:muted does find muted threads, so the state is readable but not writable. Emulate with a Margin/Muted label and a client rule that strips INBOX from new messages in muted threads as they arrive in history. While Margin is not running, Gmail web will show them in the inbox.

Sending

messages.send (100 units): body {raw, threadId?} where raw is the complete RFC 2822 message base64url-encoded. Simple JSON body is fine for small messages; for anything with attachments use the upload URI with uploadType=multipart or resumable. Discovery document maxSize for send is 36,700,160 bytes (35 MB) for the whole encoded message; the Gmail web UI limit for attachments is 25 MB (unverified). insert and import accept 157,286,400 bytes (150 MB). Consumer accounts are capped at 500 messages per day and Workspace at 2,000 (Google's help page confirms the 500; the 2,000 is third-party), counted across web, IMAP and API.

Threading rules for a reply, all three required: the threadId in the request, and "The References and In-Reply-To headers must be set in compliance with the RFC 2822 standard", and "The Subject headers must match" (Gmail tolerates Re:, Fwd:, R: and similar prefixes). Since the March 2019 change Gmail also requires that "an incoming message's Reference header, if present, must reference IDs of previous messages"; same subject and participants alone no longer thread. Practical recipe: In-Reply-To: <parent Message-ID>, References: <parent References> <parent Message-ID>, subject Re: <original>, threadId of the parent. Changing the subject starts a new thread on the recipient's side.

Other send facts: the From header must be the account's primary address or a verified send-as alias, otherwise Gmail rewrites it to the primary (documented behaviour of aliases, rewriting itself reported by developers, unverified in the reference). labelIds in the send body should be assumed ignored; apply labels with messages.modify on the returned id (unverified). Gmail generates a Message-ID if you omit one; supplying your own lets you correlate the outbox with the sent copy. The response contains the new id, threadId and labelIds (SENT). There is no scheduled send and no undo send in the API; Gmail web's Undo Send is a client-side hold of 5, 10, 20 or 30 seconds before the message leaves, which is exactly what Margin should implement.

Drafts

drafts.create (10), drafts.update (15), drafts.get (20), drafts.list (5), drafts.delete (10), drafts.send (100, "You can send as-is or provide updates by including a new MIME message"). Put threadId inside message for reply drafts. Drafts created via the API appear in Gmail web's Drafts folder, which is the only roaming compose state you get.

Settings

• settings.sendAs.list/get: enumerate the primary address and aliases with displayName, replyToAddress, signature (HTML, "added to new emails only", Gmail "will sanitize the HTML before saving it"), isPrimary, isDefault, treatAsAlias, verificationStatus (accepted, pending). sendAs.update/patch on the primary address works with gmail.settings.basic; "Addresses other than the primary address for the account can only be updated by service account clients that have been delegated domain-wide authority", and create, delete, verify are service-account-only too. So: read aliases, send from them, edit the primary signature; nothing else.
• settings.getVacation/updateVacation (gmail.settings.basic): {enableAutoReply, responseSubject, responseBodyPlainText, responseBodyHtml, restrictToContacts, restrictToDomain, startTime, endTime}.
• Filters (gmail.settings.basic): settings.filters.create/get/list/delete, no update ("filters must be deleted and recreated"), "you can only create a maximum of 1,000 filters". Criteria: from, to (matches the local part, case-insensitive), subject, query (Gmail search syntax), negatedQuery, hasAttachment, excludeChats, size with sizeComparison (smaller, larger). Actions: addLabelIds[], removeLabelIds[], forward (needs a verified forwarding address, which you cannot create). The guide's examples use INBOX and UNREAD in removeLabelIds (skip inbox, mark read), TRASH, STARRED, IMPORTANT in addLabelIds, and one user label per filter; the exact accepted set is not spelled out. "Filters only apply to specific messages and not the entire email thread", and they act on mail as it arrives; the web UI's "also apply filter to matching conversations" has no API equivalent, so backfilling is your job with batchModify.
• Forwarding addresses, auto-forwarding, delegates, POP/IMAP toggles: all service-account-only or admin territory. Delegates are Workspace-only ("up to 25 delegates and up to 10 delegators").
• messages.import (25 units, 150 MB) runs "standard email delivery scanning and classification similar to receiving via SMTP" including processForCalendar; messages.insert just stores. Neither sends. Useful for migration, not for the features here.

Sources: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/batchModify, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/send, https://gmail.googleapis.com/$discovery/rest?version=v1 (maxSize values), https://developers.google.com/workspace/gmail/api/guides/sending, https://developers.google.com/workspace/gmail/api/guides/threads, https://workspaceupdates.googleblog.com/2019/03/threading-changes-in-gmail-conversation-view.html, https://developers.google.com/workspace/gmail/api/guides/drafts, https://developers.google.com/workspace/gmail/api/guides/alias_and_signature_settings, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.sendAs/create, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.sendAs/update, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings/updateVacation, https://developers.google.com/workspace/gmail/api/guides/filter_settings, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.filters, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.filters/create, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.forwardingAddresses/create, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings/updateAutoForwarding, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.delegates/create, https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/import, https://support.google.com/mail/answer/22839, https://support.google.com/mail/answer/2819488.

5. Feature feasibility matrix

"Native" means the Gmail API (or the named Google API) does it as a first-class operation. "Emulate" means Margin builds it from labels, filters, headers and local state. Anything emulated with local state does not roam to another machine or to Gmail web unless the label mirror carries it.

Feature	Native in Gmail API	Emulate client-side (how)	Not possible
Screener (allow-list senders, hide unknown senders from inbox)	No. Filters cannot express "sender not in a list" beyond a single negatedQuery capped by query length.	On every messagesAdded with INBOX, look the sender up in a local allow-list (contacts, prior correspondents, user decisions). Unknown: modify remove INBOX, add Margin/Screened out. Screen-in decision re-adds INBOX for the thread and records the sender. Only runs while Margin is running; Gmail web shows unscreened mail in Inbox in between.	Server-side enforcement without a server.
Split inbox / Feed / Paper trail	Partial. CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_SOCIAL, CATEGORY_FORUMS, CATEGORY_PERSONAL are applied by Gmail's classifier regardless of whether tabs are on (third-party), and are readable and settable.	Per-sender routing stored locally and mirrored as Margin/Feed, Margin/Paper trail labels via modify; optionally a Gmail filter per stable sender (from: add label, remove INBOX) so Gmail web matches and mail arriving while Margin is closed is routed. Seed the initial bucket from CATEGORY_* and List-Id/Precedence: bulk headers; let the user override per sender.
Reply later pile	No.	Label Margin/Reply later plus local ordering and optional local reminders. Keep or drop INBOX as a product choice.
Set aside pile	No.	Label Margin/Set aside, remove INBOX.
Snooze	No. Gmail's own snooze is invisible except through q=in:snoozed and the eventual INBOX label add/remove in history; no snooze date is exposed (issue 287304309 is open).	Remove INBOX, add Margin/Snoozed, store wake time in SQLite; a scheduler re-adds INBOX (and UNREAD if wanted). Fires late if Margin was closed. Do not touch messages the user snoozed in Gmail web; Mimestream documents a Gmail server bug where archiving previously-snoozed mail via the API leaves it showing in Inbox.	Cross-device wake without your own sync.
Send later	No. Gmail web's Schedule send is not in the API.	Local outbox row with send_at; scheduler calls messages.send when due. Store the compose as a Gmail draft too so it survives a reinstall. App must be running at send time.	Sending while the app is closed.
Undo send	No.	Hold the message in the outbox for N seconds (Gmail web offers 5, 10, 20, 30) before calling messages.send. After send it is gone.	Recall after send.
Read receipts / open tracking	No. Gmail's read receipts are Workspace-only and admin-enabled (Disposition-Notification-To); consumer accounts cannot request or return them.	Adding Disposition-Notification-To to raw costs nothing but only some recipients' clients honour it (unverified). Pixel tracking needs a server you run and is the same practice Margin blocks on receipt; recommend not building it.	Open tracking without a server.
Spy pixel blocking	No.	Load bodies in the webview with remote content blocked by default, rewrite <img src=http...> to placeholders, allow per-sender or per-message, strip 1x1 and known tracker hosts, never send Referer. Optional proxy through your own server later.
Unsubscribe	No (Gmail web's button is UI only).	Fetch List-Unsubscribe and List-Unsubscribe-Post via metadataHeaders. If List-Unsubscribe-Post: List-Unsubscribe=One-Click is present, POST to the HTTPS URI with body List-Unsubscribe=One-Click (RFC 8058, no GET, no confirmation page). Else mailto: via messages.send, else open the HTTPS link. Pair with a from: filter to TRASH or Margin/Screened out for stragglers.
Block sender	Yes via filters: criteria.from, action.addLabelIds=[TRASH] (or removeLabelIds=[INBOX] plus a label).	Backfill existing mail with messages.list?q=from:x and batchModify.
Snippets / templates	No.	Local SQLite; insert into compose.
Sticky notes on threads	No.	Local SQLite keyed by threadId. Hidden drafts in the thread show up in Gmail web and labels cannot carry text, so there is no sane Gmail-side store.	Roaming without your own sync.
Rename thread subject	No; message headers are immutable.	Local display-name override keyed by threadId; replies still carry the real subject so threading holds.	Changing what Gmail web shows.
Merge threads	No; threadId is assigned by Gmail.	Local mapping of several threadIds to one virtual thread; writes fan out to every underlying thread.	Merging in Gmail itself.
Contacts autocomplete	Yes via People API: otherContacts.list (contacts.other.readonly, readMask=names,emailAddresses, pageSize up to 1000, sync tokens expire after 7 days), people.connections.list (contacts.readonly, up to 1000), otherContacts.search and people.searchContacts (max 30 results, send an empty-query warm-up first).	Also index From/To/Cc from synced headers locally; it is the best signal and needs no extra scope.
Attachments browsing	Partial: q=has:attachment or filename:pdf returns ids.	Index payload.parts[].filename/mimeType/size from format=full fetches into SQLite; fetch bytes on demand with attachments.get.
Calendar invite RSVP	Not in Gmail API. Calendar API: find the event with events.list?iCalUID=<UID from the text/calendar part> on primary (Gmail auto-adds invites depending on the user's "Add invitations to my calendar" setting, "From everyone" or "Only if the sender is known"), then events.patch with attendees[self].responseStatus in accepted, tentative, declined and sendUpdates=all; if absent, events.import with iCalUID, start, end. Needs calendar.events.	Parse the text/calendar part (METHOD:REQUEST) yourself and render the card. A standards-only fallback is to email a METHOD:REPLY iMIP message to the organiser via messages.send, which needs no Calendar scope but does not update the user's own calendar.
Shared / team features	Out of scope. Delegation exists but is Workspace-only and service-account-only.
Multiple accounts	Yes: one OAuth grant per account with the same client ID; separate refresh tokens and sync cursors.
Unified inbox	No.	Merge locally across account databases; every write routes to the owning account.
Search	Yes: messages.list?q= and threads.list?q= (5 or 10 units per page, full Gmail operator set: from:, to:, subject:, label:, category:, has:attachment, filename:, list:, newer_than:, larger:, rfc822msgid:, in:snoozed, is:muted, deliveredto:, AROUND, OR, -). Returns ids only; hydrate from the mirror. Not available under gmail.metadata. Cannot be combined with history.list.	SQLite FTS5 over synced subject, participants and cached bodies for instant results; fall back to server q for anything not yet hydrated and for operators you have not implemented. Server search is a network round trip and returns ids in relevance-ish order, so results feel slower than local.
Keyboard triage	No.	Client. Batch consecutive label changes into batchModify calls.
Push notifications	Yes with users.watch plus Pub/Sub, but delivery requires a server or an unacceptable IAM grant (section 3).	Poll history.list; optionally IMAP IDLE on INBOX as a wake-up.	Push with no server.
Offline compose and queue	No.	Local outbox; drafts.create when online so the draft roams; messages.send on reconnect with backoff.
Categories tabs	Yes: read and set CATEGORY_*. Accuracy is good for big senders and mediocre for small newsletters; Promotions is a fair Feed seed, Updates is a fair Paper trail seed (receipts, notifications), Forums and Social less useful. Gmail may reclassify a sender after the user moves a few messages, which you observe as label churn in history.	Treat as a prior; sender-level rules win.
Importance markers	Yes: IMPORTANT label readable and settable; filters can removeLabelIds=[IMPORTANT].
Muted threads	Readable via q=is:muted, not settable.	Margin/Muted label plus client rule (section 4).	Muting that Gmail itself enforces.
Labels and folders, archive, star, read state, trash, spam	Yes.
Signature and vacation responder	Yes for the primary address (sendAs.patch signature, updateVacation).		Creating or verifying send-as aliases (service-account-only).
Permanent delete	Yes, but only with https://mail.google.com/.	Trash instead.

Sources: https://developers.google.com/workspace/gmail/api/guides/labels, https://developers.google.com/workspace/gmail/api/guides/filter_settings, https://issuetracker.google.com/issues/287304309 (login required), https://mimestream.com/help/common-issues/archiving-snoozed-messages, https://support.google.com/mail/answer/9413651, https://www.rfc-editor.org/rfc/rfc8058, https://developers.google.com/people/api/rest/v1/otherContacts/list, https://developers.google.com/people/api/rest/v1/otherContacts/search, https://developers.google.com/people/api/rest/v1/people.connections/list, https://developers.google.com/people/api/rest/v1/people/searchContacts, https://developers.google.com/workspace/calendar/api/v3/reference/events, https://developers.google.com/workspace/calendar/api/v3/reference/events/list, https://developers.google.com/workspace/calendar/api/v3/reference/events/import, https://support.google.com/calendar/answer/13159188, https://support.google.com/mail/answer/7190 (search operators), https://support.google.com/mail/thread/231661001 (categories applied with tabs off, community thread).

6. Gotchas and war stories

• Quota changed on 1 May 2026. Any library, blog post or mental model built on 250 units per second per user and 5-unit messages.get is off by a factor of 4 to 10. Budget hydration at 300 messages per minute per user and expect billing for overage "later in 2026".
• Full sync is now the slow part. A 100,000 message mailbox is roughly 5 to 6 hours of metadata hydration at the ceiling. Hydrate newest first, show partial state, and consider IMAP for the backfill if that is unacceptable.
• history.list 404 is routine. A user who does not open Margin for a week or two will hit it; treat the ids-only re-list as a normal code path, not a disaster.
• History can reference messages that no longer exist. messages.get 404 on a messagesAdded id means it was deleted in the same window. Log and move on.
• Label IDs are not names. Label_123 is the key; names change; system labels are their own IDs. Re-list labels when history contains an unknown id. Do not create a label whose name collides with a reserved name (400).
• labelIds on messages.send should be assumed ignored; modify afterwards.
• raw is base64url, not standard base64. +// versus -/_ mistakes produce corrupt MIME that Gmail rejects with a 400 that says nothing useful.
• 35 MB (36,700,160 bytes) is the hard send ceiling for the whole encoded message, which after base64 expansion is about 25 MB of attachments. Fail early in the composer, not at send.
• Messages are immutable. There is no way to change headers, subject, or body of a stored message. Every "edit" feature in section 5 is a local overlay.
• messages.list pages at most 500 and returns only ids; resultSizeEstimate is an estimate and can be wildly wrong. threads.list likewise.
• Batch: 100 max, 50 recommended, each call metered separately, and 429 inside a batch comes back per part, so parse every part's status. The batch path from the discovery document is batch/gmail/v1 on www.googleapis.com.
• 429 and 403 userRateLimitExceeded / rateLimitExceeded both want truncated exponential backoff (min((2^n) + random_ms, 32 to 64 s)) and "Start retry periods at least one second after the error". Per-user limits "cannot be increased for any reason". Watch the undocumented concurrency ceiling: keep in-flight requests per mailbox low (single digits) and the batch size at 25 to 50.
• Server search is slow-ish and eventually consistent: a message you just labelled may not match q=label:x for a few seconds. Local FTS is the fast path.
• Header decoding: RFC 2047 encoded-words (=?UTF-8?B?...?=) in From, Subject and filenames, RFC 2231 parameter continuations in Content-Disposition, and charset-labelled bodies (iso-8859-1, windows-1252, gb2312) all show up daily. Use a real MIME parser on raw rather than trusting payload for anything beyond headers.
• HTML mail in a webview: sanitise (strip scripts, forms, <meta http-equiv>, external CSS, javascript: URLs), isolate in an iframe or Tauri child webview with CSP, block remote images by default, rewrite cid: to local resources, and expect broken layouts with dark mode. Practical dark-mode approach is per-message opt-in inversion or a light-background iframe; automatic colour inversion breaks a lot of newsletters.
• Newsletter and bulk detection: List-Id (RFC 2919), List-Unsubscribe, Precedence: bulk|list, Auto-Submitted, X-Mailer and a CATEGORY_PROMOTIONS or CATEGORY_UPDATES label together give a reliable "not a human" signal for the screener's default bucket.
• Authentication results are only in raw headers. Fetch Authentication-Results via metadataHeaders and parse spf=, dkim=, dmarc= from the mx.google.com stanza. There is no API field for spam score or phishing verdict; SPAM label is all you get.
• Gmail's classifier and your screener will disagree. A first-time human sender in Promotions is common (Gmail keys on content, you key on sender). Make the screener decision sender-based and use categories only to pick the default bucket.
• Threading edge cases: recipients and senders can see different threads for the same messages; a changed subject starts a new thread; Gmail web splits at 100 messages; mailing-list software that rewrites Message-ID or strips References produces orphan threads; a reply sent without threadId lands in a new thread even with correct headers.
• Snoozed-in-Gmail messages that Margin archives can reappear in Gmail web's Inbox (server bug, Mimestream help page). Leave Gmail-snoozed mail alone.
• Password change revokes every refresh token with Gmail scopes. Expect invalid_grant and re-prompt.
• Testing-mode tokens die after 7 days. If someone reports "it logs me out weekly", the consent screen is still in Testing.
• resultSizeEstimate, messagesTotal and label counts are estimates and lag. Never drive UI badges from them; count locally.
• People API sync tokens expire after 7 days and "The first page of a full sync request has an additional quota" that returns 429 if hammered; do one full contacts sync per install, then incremental.
• Sending limits are per account across all clients: 500 per day consumer. A bulk "unsubscribe from 200 lists via mailto" action can burn a meaningful chunk of it.

Sources: https://developers.google.com/workspace/gmail/api/guides/handle-errors, https://developers.google.com/workspace/gmail/api/reference/quota, https://developers.google.com/workspace/gmail/api/guides/sync, https://developers.google.com/workspace/gmail/api/guides/batch, https://developers.google.com/workspace/gmail/api/guides/threads, https://mimestream.com/help/common-issues/archiving-snoozed-messages, https://developers.google.com/identity/protocols/oauth2, https://developers.google.com/people/api/rest/v1/otherContacts/list.

7. Recommendation

REST is the only transport for v1. IMAP comes later, if at all, for two narrow jobs: bulk backfill when measured REST sync time is unacceptable, and IDLE as a wake-up signal. history.list stays the single change log; IMAP has no equivalent.

Request gmail.modify, gmail.settings.basic, contacts.other.readonly, contacts.readonly and calendar.events; no https://mail.google.com/ until IMAP is real. Push the consent screen to production unverified for the friends release (100 lifetime users, stable tokens) and file restricted-scope verification now, stating there is no server and asking in writing whether the assessment applies.

Everything lives in SQLite on the device: message and thread mirror, bodies with an LRU, FTS5 index, per-account history cursor, and an outbox with send_at and hold_until (send later and undo send are one mechanism). Poll history.list every 10 to 15 seconds in the foreground. No server, no push; say so in the product.

Mirror every pile as a real label under one namespace so Gmail web stays coherent: Margin/Screened out, Margin/Feed, Margin/Paper trail, Margin/Reply later, Margin/Set aside, Margin/Snoozed, Margin/Muted. All but Reply later also remove INBOX, so Gmail web's inbox matches Margin's and the rest is findable by label. For senders the user has explicitly routed, also create a from: filter so routing works while Margin is closed; stay well under the 1,000 filter cap.

What cannot live in Gmail, and so does not roam to another device or to Gmail web until Margin ships its own sync: sticky notes, thread renames and merges, snooze wake times, scheduled send times, the allow-list and per-sender rules (labels show the outcome, not the rule), snippets. A second machine sees the labels, not the rules, and a snooze set on the laptop will not wake the desktop. Call this "single device of record" in the onboarding copy rather than discovering it in support.

Skip open tracking: it needs a server, contradicts the pixel blocking, and invites scrutiny during review. Design against these numbers: 6,000 units per minute per user, 20 units per metadata fetch, 100 per send, 35 MB per message, 500 sends per day, 1,000 filters, 10,000 labels, 500 ids per page, 1,000 ids per batchModify, 100 calls per batch, history validity that can drop to hours, and no API for snooze, schedule send, undo send, mute, rename, notes, or push without a server.