> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/twins/available-twins/gmail.md). # Gmail The Gmail twin, what it covers, how to seed a mailbox, and what to know about how it behaves. A private copy of Gmail v1 that your agent reaches over MCP, as the mailbox's owner. | | | | ------------------- | ------------------------------------------------------------------------------------------------ | | **Copies** | Gmail v1 | | **Covers** | Messages, threads, labels, drafts, attachments, filters and mailbox settings | | **Seed section** | `## World: gmail` | | **Run environment** | `TWIN_GMAIL_MCP` and `TWIN_GMAIL_TOKEN`, beside the calendar's `TWIN_MCP` and `TWIN_TOKEN` | | **Watch out** | Only the bundled `twin-agent` encodes and decodes mail for you. Your own agent gets no such help | A world can hold a mailbox alone, or a mailbox beside a calendar, and your agent reaches both in the same run. ## Copy this A mailbox beside a calendar. Save it as `seed.md`: ```markdown ## Setup twin: calendar, gmail now: Mon 09:00 ## World: gmail Fri 16:42 Priya Shah -> me "Offsite planning call" #offsite // Could we do an hour on {Thu}, any time between 2 and 4pm? Thu 09:05 Ines Okafor -> me "Intro call" #intro // Would {Tue} 3-5pm work? ## World: calendar Thu 14:00-15:00 Board prep ``` ## What your agent sees To list every tool a world serves: ```bash twin api world --list ``` ## Seeding a mailbox Mail goes under `## World: gmail`, one email per line. Each World section names its twin. The shape of one line: ``` when from -> to [cc a@b.test] "subject" [LABELS] #thread +file.pdf // body ``` | Part | What it does | Example | | --------- | -------------------------------------------------------------------------------------------------------- | -------------------------- | | when | The most recent such weekday before the clock. `Tue-2` is two weeks before that. `today 08:30` is today. | `Sat 10:15` | | from / to | `Name
`, or `me` for the mailbox's owner. | `me -> Mira ` | | labels | Optional. Received mail defaults to `INBOX, UNREAD`; mail from `me` defaults to `SENT`. | `[INBOX, STARRED]` | | #thread | Lines with the same key share a thread. | `#offsite` | | +file | An attached file. Only the name is real; the content is a stand-in. | `+invoice-4471.pdf` | | `[DRAFT]` | On a line from `me`: a draft already waiting, which your agent can edit or send. | See below | | body | The text, after `//`. `{Tue+1}` is written out as a date, such as "Tuesday 20 October". | `// Free {Thu} 2-4pm` | A draft already waiting: ``` me -> Priya "Re: Offsite" [DRAFT] ``` {% hint style="info" %} Write days in bodies as `{Thu}` or `{Thu+1}`, not "next week's Thursday". An email sent on a Saturday that says "next week" reads two ways; a date does not. The token becomes a date when the world is seeded, so your seed never goes out of date. {% endhint %} ### Mailbox settings Filters, vacation reply, forwarding, send-as (with S/MIME), delegates, IMAP, POP, language and client-side encryption can be set up in the seed too, with lines such as: ``` filter: from priya@acme.test -> label Project X ``` More on seeds: [Describe a world](/twins/using-twins/describe-a-world.md). ## Mail that arrives while your agent works Two ways to make new mail show up: * **In the seed.** A line starting `after message.send#1:` arrives while your agent works. It is seeded out of sight, then moved into its thread, unread, on your agent's first send. * **By hand, now.** `twin world trigger` adds the mail and events a file describes to the world as it stands. It uses the seed's own syntax, and `now` in place of a day and time dates the email by the twin's clock. An email whose `#thread` (or subject) matches mail already in the world joins that thread. ```markdown ## World: gmail now Priya Shah -> me "Re: Offsite dates" #offsite // Thursday is out, sorry. ``` ```bash twin world trigger world new-mail.md ``` Mail added with `twin world trigger` is the world's doing, not your agent's, so `twin world calls` leaves it out. ## Behaviour to know * **A seed with mail makes two worlds.** `twin world create` from a seed with `twin: calendar, gmail` makes a calendar world and a mailbox world, in one folder. `twin world list` shows one line per folder. * **Two addresses, two tokens.** When you run your agent with `twin world run`, it gets the mailbox's address and token in `TWIN_GMAIL_MCP` and `TWIN_GMAIL_TOKEN`, beside the calendar's `TWIN_MCP` and `TWIN_TOKEN`. * **Your agent sees the twin's tools as they are.** The example agent that ships with the CLI, `twin-agent`, encodes the mail it sends and decodes the mail it reads for you. Your own agent gets no such help. * **Read one app's calls.** `twin world calls world --app gmail` shows only the mailbox's calls. Read the mailbox yourself: ```bash twin api world message.list --app gmail -f q="is:unread" ``` ## Next * [Google Calendar](/twins/available-twins/calendar.md): seed the calendar beside the mailbox. * [Run your agent](/twins/using-twins/run-your-agent.md): make mail arrive mid-run and control the world's clock. * [See what your agent did](/twins/using-twins/see-what-your-agent-did.md): read every call your agent made. *** *Last updated: 27 October 2026*