Gmail - Pome

A deterministic, resettable, in-process digital twin of the Gmail REST API v1. It reproduces the same response shapes and error semantics as Gmail without sending real email or touching Google. Each instance starts from a task seed and resets between runs, so the same task produces the same state every time.

By use case

These are the workflows agents actually run against this twin, each naming the MCP tools and REST surfaces involved. Anything named here that is not fully modelled says so in place.

Triage an unread inbox

List unread messages, read one, and move it out of the inbox. MCP: get_message, label_message, unlabel_message. REST: GET /gmail/v1/users/{userId}/messages, GET /gmail/v1/users/{userId}/messages/{id}, POST /gmail/v1/users/{userId}/messages/{id}/modify, POST /gmail/v1/users/{userId}/messages/batchModify.

Draft and send a reply

Prepare a reply without sending it, then send once it is approved. MCP: create_draft, list_drafts. REST: POST /gmail/v1/users/{userId}/drafts, GET /gmail/v1/users/{userId}/drafts, POST /gmail/v1/users/{userId}/drafts/send, POST /gmail/v1/users/{userId}/messages/send.

Organize threads and mailboxes with labels

Apply a label to a whole thread, including the sensitive labels a coach workflow gates on, and manage the label taxonomy itself. MCP: label_thread, unlabel_thread, apply_sensitive_thread_label, apply_sensitive_message_label, create_label, list_labels. REST: GET /gmail/v1/users/{userId}/labels, POST /gmail/v1/users/{userId}/labels, PATCH /gmail/v1/users/{userId}/labels/{id}, DELETE /gmail/v1/users/{userId}/labels/{id}, POST /gmail/v1/users/{userId}/threads/{id}/modify.

Search and read a thread’s history

Find a thread by query, read every message in it, and check what changed since a given history id. MCP: search_threads, get_thread. REST: GET /gmail/v1/users/{userId}/threads, GET /gmail/v1/users/{userId}/threads/{id}, GET /gmail/v1/users/{userId}/history.

Manage mailbox settings

Read filters, forwarding addresses, and send-as identities, and edit filters. Forwarding addresses and send-as identities are read-only — there is no create or update route for either. REST: GET /gmail/v1/users/{userId}/settings/filters, POST /gmail/v1/users/{userId}/settings/filters, DELETE /gmail/v1/users/{userId}/settings/filters/{id}, GET /gmail/v1/users/{userId}/settings/forwardingAddresses, GET /gmail/v1/users/{userId}/settings/sendAs.

What you can rely on

Each surface below carries two rulings that are deliberately kept apart: heat is how deep it should be, ruled per milestone; state is how deep it is today, measured by the twin’s own tests. Neither moves because the other did. A surface is in exactly one state, and the three below are different answers to “can I write a task against this”:

State	What it means
Verified	the behaviour is implemented and test-covered. Code written against the real API runs here unchanged.
Out of scope	a loud 501, and it stays one. Ruled off an agent’s task chain, so the 501 is the answer rather than a gap.
Known divergence, ruled	measured against the real API, found to differ, and the difference was reviewed and accepted. It is registered, numbered, and reverse-tested.

@pome-sh/twin-gmail declares 13 MCP tools and 54 REST surfaces, read from the twin’s own fidelity.inventory.json (last updated 2026-08-10):

State	MCP tools	REST surfaces
Verified	13	46
Out of scope	0	8

Out of scope

Real SMTP delivery, Pub/Sub push, Google OAuth and OIDC, and the Calendar, Drive, Contacts and admin surfaces are not modelled — send is a mailbox-state transition and no mail ever leaves. The bearer token is the Pome JWT, not a Google OAuth token, so there are no consent screens, refresh tokens, or scopes. These surfaces are named rather than left to the catch-all, so the 501 is documented and test-backed:

Surface	Heat
`POST /resumable/upload/gmail/v1/users/{userId}/messages/send (resumable)`	cold
`POST /resumable/upload/gmail/v1/users/{userId}/messages (resumable)`	cold
`POST /resumable/upload/gmail/v1/users/{userId}/messages/import (resumable)`	cold
`POST /resumable/upload/gmail/v1/users/{userId}/drafts (resumable)`	cold
`PUT /resumable/upload/gmail/v1/users/{userId}/drafts/{id} (resumable)`	cold
`POST /resumable/upload/gmail/v1/users/{userId}/drafts/send (resumable)`	cold
`POST /gmail/v1/users/{userId}/watch`	cold
`POST /gmail/v1/users/{userId}/stop`	cold

Known divergence, ruled

8 divergences are on the ledger for Gmail: measured against the real API, found to differ, reviewed, and accepted. Each is registered and reverse-tested, so one that upstream heals becomes a signal rather than a surprise. The numbers are stable identifiers, not positions — a retired divergence leaves its number behind, so a gap in this list is a divergence that closed.

#	Divergence
1	Message payloads are single-part where Gmail returns `payload.parts`.
2	The twin synthesizes a fixed eight-header set, so its header count is wrong in both directions.
3	`messages.list` does not count drafts.
4	`threads.list` does not count a draft’s thread.
5	The label set omits Gmail’s `CHAT` system label.
6	A thread message’s `labelIds` carries the twin’s own labels and its own read state.
7	`sendAs` entries omit `replyToAddress`.
8	The missing-credential 401 omits Gmail’s `details[]`, which names the backend method.

Where it runs. Both doors serve the same twin: pome twin start gmail boots it as a local process, and pome sandbox create --twin gmail starts a hosted sandbox running the same image. The states above are properties of the twin, so they hold on either. Everything above is what the twin declares. What it was measured to do is a different number: the comparison against real Gmail runs daily and publishes, surface by surface, how many matched, which drifted, and which are ruled exceptions with the reason written out in full — at status.pome.sh/twin/gmail, which also states when it last ran and how old the captured baseline it compares against is. No count is copied onto this page, because copying one is how it goes stale. Read from FIDELITY.md, fidelity.inventory.json, LIMITS.md and REFERENCE-DIVERGENCES.md in pome-sh/digital-twins, at the commit .github/twins-ref pins (2e41939). LIMITS.md is the one to read before writing a task that pages, batches or attaches — every bound it names is enforced and fails loudly rather than truncating. REFERENCE-DIVERGENCES.md records which oracle each ruling was measured against.

Quickstart

pome run tasks/22-gmail-inbox-triage.md \
  --agent "<your agent command>"

That task boots the Gmail twin, seeds a world from the task, hands your agent a base URL and a token, and scores the run once the agent exits.

Point your agent at it

For interactive development without a full task run, start the standalone twin:

pome twin start gmail

The command prints env-var lines you can paste into your agent’s environment:

POME_GMAIL_REST_URL=http://127.0.0.1:3336/s/standalone
POME_GMAIL_MCP_URL=http://127.0.0.1:3336/s/standalone/mcp
POME_AUTH_TOKEN=<jwt>
POME_GMAIL_TOKEN=<jwt>

POME_GMAIL_REST_URL is the REST root. POME_GMAIL_MCP_URL is the MCP transport endpoint. POME_AUTH_TOKEN is a short-lived JWT that authenticates every request on the sandbox, and POME_GMAIL_TOKEN is an alias of it. The default mailbox is pome-agent@pome-twin.test. Mailbox resolution accepts only me or the exact seeded gmail_email — anything else is rejected. The session path /s/standalone/healthz requires the JWT and returns 401 without it. To check whether the twin is alive, use the unauthenticated root health endpoint:

curl http://127.0.0.1:3336/healthz

Task seed shape

Gmail task seeds are flat, with a required primaryMailbox, an optional mailboxes array, a deliveryMode, a clock and named faults. Generate it; do not copy it. The block below is what the twin starts with, printed by the CLI from the twin’s own declared state — so it parses against the twin you are about to seed, today and after the twin changes:

pome twin new-seed gmail > gmail.seed.json

A seed replaces the twin’s starting state. It does not merge into it. Seed your own world and everything below is gone — drop a mailbox and the messages below are not in the inbox.

{
  "primaryMailbox": {
    "email": "pome-agent@pome-twin.test",
    "displayName": "Pome Agent",
    "labels": [
      {
        "id": "Label_follow_up",
        "name": "Follow Up"
      },
      {
        "id": "Label_build",
        "name": "Build"
      }
    ],
    "messages": [
      {
        "id": "msg_welcome",
        "threadId": "thread_welcome",
        "from": "welcome@pome-twin.test",
        "to": [
          "pome-agent@pome-twin.test"
        ],
        "cc": [],
        "bcc": [],
        "subject": "Welcome to your Pome Gmail twin",
        "text": "Your deterministic inbox is ready for agent testing.",
        "html": "<p>Your deterministic inbox is ready for agent testing.</p>",
        "date": "2026-07-18T09:00:00.000Z",
        "messageId": "welcome@pome-twin.test",
        "references": [],
        "attachments": [],
        "labels": [
          "INBOX"
        ]
      },
      {
        "id": "msg_build",
        "threadId": "thread_build",
        "from": "ci@example.com",
        "to": [
          "pome-agent@pome-twin.test"
        ],
        "cc": [],
        "bcc": [],
        "subject": "Build failed on main",
        "text": "The nightly build failed. See the attached log.",
        "html": "",
        "date": "2026-07-19T10:00:00.000Z",
        "messageId": "build-001@example.com",
        "references": [],
        "attachments": [
          {
            "filename": "build.log",
            "mimeType": "text/plain",
            "disposition": "attachment",
            "data": "QlVJTEQgRkFJTEVEIHN0ZXA9dGVzdAo="
          }
        ],
        "labels": [
          "INBOX",
          "UNREAD",
          "Build"
        ]
      },
      {
        "id": "msg_build_reply",
        "threadId": "thread_build",
        "from": "pome-agent@pome-twin.test",
        "to": [
          "ci@example.com"
        ],
        "cc": [],
        "bcc": [],
        "subject": "Re: Build failed on main",
        "text": "Looking into the failure now.",
        "html": "",
        "date": "2026-07-19T11:00:00.000Z",
        "messageId": "build-reply@pome-twin.test",
        "inReplyTo": "build-001@example.com",
        "references": [
          "build-001@example.com"
        ],
        "attachments": [],
        "labels": [
          "SENT"
        ]
      },
      {
        "id": "msg_support",
        "threadId": "thread_support",
        "from": "alice@example.com",
        "to": [
          "pome-agent@pome-twin.test"
        ],
        "cc": [],
        "bcc": [],
        "subject": "Production export is stuck",
        "text": "Our production export has been stuck for an hour. Can you investigate?",
        "html": "",
        "date": "2026-07-19T12:00:00.000Z",
        "messageId": "support-001@example.com",
        "references": [],
        "attachments": [],
        "labels": [
          "INBOX",
          "UNREAD"
        ]
      }
    ],
    "drafts": [
      {
        "id": "draft_ack",
        "threadId": "thread_draft_ack",
        "to": [
          "bob@example.com"
        ],
        "cc": [],
        "bcc": [],
        "subject": "Draft acknowledgment",
        "text": "Thanks — I'll follow up shortly.",
        "html": "",
        "date": "2026-07-19T13:00:00.000Z",
        "messageId": "draft-ack@pome-twin.test",
        "references": [],
        "attachments": []
      }
    ],
    "filters": [],
    "forwardingAddresses": [],
    "sendAs": []
  },
  "mailboxes": [],
  "deliveryMode": "sender-only",
  "clock": "2026-07-20T00:00:00.000Z",
  "faults": []
}

Set twins: ["gmail"] in the task’s ## Config block and name the file <task>.seed.json, beside the task’s .md. That ## Config is the only place the twin gets named: the file above is flat, so it carries no twin id of its own.

Seed file

A task is not the only way in. pome twin start and pome sandbox create take that very same file — no wrapper, no second shape, nothing to convert — and each takes the twin’s name beside it, since the file cannot supply one:

pome twin start gmail --seed gmail.seed.json
pome sandbox create --twin gmail --seed gmail.seed.json

Omit the name and neither door guesses; both stop and say the seed is flat. Add a second twin and the file becomes a per-twin envelope instead, one key each — pome twin new-seed gmail slack writes it:

{ "gmail": { /* exactly the world above */ }, "slack": { /* that twin's world */ } }

One twin, one flat file: the twin’s own world with no wrapper, which means it says nothing about which twin it is for. That is why twin start and sandbox create want the name as well, and why a task’s sidecar does not — the ## Config beside it already named the twin. From two twins up the file is a per-twin envelope { <twin>: <seed> }, which does name its twins, though twin start still has to be told which one of them to boot. Replace, not merge, applies wherever the file lands. Build your own world is that job end to end — generating the file, editing it down, both doors, and how to tell whether every field you wrote actually landed.

Example tasks

Ready-made examples you can run or copy to see the twin in action:

pome tasks gmail
pome tasks gmail --copy

Catalog

#	Task	What it exercises
22	Inbox triage (`22-gmail-inbox-triage.md`)	Find an unread support thread, label it for follow-up, and prepare a draft reply.
23	First-party parity (`23-gmail-first-party-parity.md`)	Exercise the full 13-tool Gmail MCP workflow over one deterministic mailbox.
27	Gmail → GitHub support escalation (`27-gmail-github-support-escalation.md`)	Label a Gmail support thread, then open a labeled GitHub bug for the same incident (cross-twin: gmail + github).

Run one

pome run tasks/22-gmail-inbox-triage.md --agent "<your agent command>"

Or let the coach pick and run a matching task for you — the pome-suggest-tasks and pome-run-task skills, installed by the graded capstone.

​By use case

​Triage an unread inbox

​Draft and send a reply

​Organize threads and mailboxes with labels

​Search and read a thread’s history

​Manage mailbox settings

​What you can rely on

​Out of scope

​Known divergence, ruled

​Quickstart

​Point your agent at it

​Task seed shape

​Seed file

​Example tasks

​Catalog

​Run one

By use case

Triage an unread inbox

Draft and send a reply

Organize threads and mailboxes with labels

Search and read a thread’s history

Manage mailbox settings

What you can rely on

Out of scope

Known divergence, ruled

Quickstart

Point your agent at it

Task seed shape

Seed file

Example tasks

Catalog

Run one