Gmail

Use gmail in twins and put this configuration under seed_config.gmail. Gmail mailbox with labels, messages, threads, and drafts.

Example seed

This is the complete Scenario request body for creating a Scenario. You can also import it with arga test-runner scenarios import --file scenario.json.

{
  "name": "Gmail eval fixture",
  "twins": [
    "gmail"
  ],
  "seed_config": {
    "gmail": {
      "profile": {
        "email": "owner@gmail-twin.local",
        "name": "Gmail Twin Owner"
      },
      "labels": [
        {
          "name": "Launch"
        }
      ],
      "gemini": {
        "enabled": true,
        "response_mode": "scenario",
        "responses": [
          {
            "prompt": "Write an Atlas update",
            "text": "Atlas is on schedule. Design review is Friday."
          }
        ]
      },
      "messages": [
        {
          "subject": "Launch readiness",
          "body": "Please review the launch checklist.",
          "from": "sender@example.com",
          "to": [
            "owner@gmail-twin.local"
          ],
          "labels": [
            "Launch",
            "INBOX"
          ],
          "message_id": "<launch-readiness@example.com>",
          "thread_id": "thread-launch-readiness",
          "attachments": [
            {
              "filename": "launch-photo.png",
              "mime_type": "image/png"
            }
          ]
        }
      ],
      "drafts": [
        {
          "subject": "Follow up",
          "body": "Thanks for the update.",
          "to": [
            "reviewer@example.com"
          ],
          "thread_id": "thread-launch-readiness",
          "in_reply_to": "<launch-readiness@example.com>",
          "references": [
            "<launch-readiness@example.com>"
          ]
        }
      ]
    }
  }
}

Parameters

Top-level fields: `seed_config.gmail`

Parameter	Type	Description
`email_address`	string	Owner’s mailbox address. Falls back to `profile.email`, then `owner@gmail-twin.local`.
`base_time`	datetime string	Reference clock. Accepts ISO-8601 or an RFC email date. Omit to use the current clock.
`labels`	array of strings or objects	Custom label names, or objects containing `name`. Example: `["Customers"]` or `[{"name":"Customers"}]`. Only `name` is consumed from a label object.
`messages`	object[]	Messages to seed. See message fields below.
`drafts`	object[]	Drafts to seed. See draft fields below.
`profile`	object	Owner’s identity/profile.
`tokens`	object[]	Additional test credentials and their mailbox/scopes.
`browser_accounts`	object keyed by email	Browser account settings.
`browser_connections`	object keyed by service	Browser connections to sibling service twins.
`gemini`	object	Writing-assistant behavior and deterministic responses.
`client_id`	string	Test OAuth client ID. Must be nonempty.
`client_secret`	string	Test OAuth client secret. Must be nonempty.
`redirect_uris`	string[]	Allowed absolute HTTP(S) OAuth callback URLs, without embedded credentials or fragments.
`require_pkce`	boolean	Require PKCE for OAuth. Default: `false`.
`access_token_ttl_seconds`	integer >= 1	Access-token lifetime. Default: `3600`.
`authorization_code_ttl_seconds`	integer >= 1	Authorization-code lifetime. Default: `600`.
`oidc_issuer`	URL string	Absolute HTTP(S) OIDC issuer without credentials, query, or fragment. Default: `https://accounts.google.com`.

Messages: `gmail.messages[]`

Parameter	Type	Description
`subject`	string	Subject. Default: `Seed message`.
`body` / `body_text` / `text`	string	Plain-text message body. Default: empty.
`from` / `from_email` / `sender`	string	Sender. Default: `sender@example.com`.
`to`	string or string[]	Recipients. Defaults to the owner’s address.
`cc`	string or string[]	CC recipients.
`bcc`	string or string[]	BCC recipients.
`reply_to` / `replyTo`	string	`Reply-To` header.
`date`	datetime string	ISO-8601 or RFC email date.
`thread_id` / `threadId`	string	A shared seed-local alias that groups messages into a conversation. It can also link a later draft to that conversation.
`message_id` / `messageId`	string	MIME `Message-ID` header, rather than the generated Gmail resource ID.
`in_reply_to` / `inReplyTo`	string	MIME `In-Reply-To` header.
`references`	string or string[]	MIME reference chain.
`attachments`	object[]	MIME attachments. See attachment fields below.
`raw`	string	Base64url-encoded MIME. Replaces composition from subject/body/address/attachment fields.
`labels` / `label_names`	string or string[]	System label names or names declared in top-level `labels`.
`labelIds` / `label_ids`	string or string[]	Explicit label IDs. Takes precedence over label-name fields.
`send`	boolean	Seed through the twin’s send operation instead of inserting an incoming message. Default: `false`.

Behavior:

Messages without dates are distributed oldest-first within the preceding 30 days relative to base_time, or the seeding time when base_time is omitted.
Imported MIME Date headers are preserved. A missing header is filled from the explicit or generated date.
Ordinary messages default to INBOX; send: true messages default to SENT. Add UNREAD explicitly when needed.
Name-based labels normally include the default location label. SENT, DRAFT, TRASH, or SPAM suppress that addition. An explicit empty label list seeds no labels.
Thread aliases are resolved as messages are created. Linked drafts should follow the messages they reference.

Drafts: `gmail.drafts[]`

Drafts accept the same composition fields as messages: subject, body / body_text / text, from / from_email / sender, to, cc, bcc, reply_to / replyTo, date, thread_id / threadId, message_id / messageId, in_reply_to / inReplyTo, references, attachments, and raw. Draft defaults differ: subject defaults to Draft, and sender and recipient default to the owner. Drafts do not apply send, labels, or labelIds. Drafts without a date do not receive the message list’s automatic date distribution.

Attachments: `messages[].attachments[]` or `drafts[].attachments[]`

Parameter	Type	Description
`filename` / `name`	string	Filename. Defaults to `attachment-<index>`.
`mimeType` / `mime_type`	string	MIME type. Default: `application/octet-stream`.
`content_base64` / `data`	base64 string	Encoded bytes. Supports base64url decoding. Takes precedence over `content`.
`content`	string	UTF-8 text content. The Scenario attachment field is `content`, rather than `content_text`.
`inline`	boolean	Use inline disposition. Default: `false`.
`content_id` / `contentId`	string	MIME Content-ID, useful for inline attachments.

For HTML email, supply raw MIME with the desired HTML body.

Profile: `gmail.profile`

Parameter	Type	Description
`email`	string	Fallback owner address when top-level `email_address` is omitted.
`sub`	string or null	Identity subject.
`name`	string	Display name. Default: `Gmail Twin Owner`.
`given_name`	string or null	Given name.
`family_name`	string or null	Family name.
`picture`	string or null	Profile image URL.
`email_verified`	boolean	Default: `true`.
`hd`	string or null	Hosted domain.

Test credentials: `gmail.tokens[]`

Parameter	Type	Description
`token`	string, required	Nonempty, unique test token.
`email_address`	string, required	Mailbox associated with the token.
`scopes`	string[]	Explicit OAuth scopes. Omission uses the twin’s default full-access scope set; `[]` grants no scopes.

The seeder also installs its owner credential automatically.

Browser accounts: `gmail.browser_accounts.<email>`

Parameter	Type	Description
`name`	string	Account name; maximum 200 characters.
`password`	string	Browser sign-in password; 8-200 characters when supplied.
`admin`	boolean	Browser administrator flag.
`organization`	string	Organization label; maximum 200 characters.

Map keys must be trimmed, lowercase email addresses. Unknown account fields are rejected.

Browser connections: `gmail.browser_connections.<service>`

Parameter	Type	Description
`base_url`	URL string, required	HTTP(S) sibling service URL without embedded credentials.
`tokens`	object mapping email to token	Explicit per-account credentials for that connection. Default: `{}`.

Writing assistant: `gmail.gemini`

Parameter	Type	Description
`enabled`	boolean	Default: `false`.
`response_mode`	`"scenario"` or `"live"`	Default: `scenario`.
`eligible_accounts`	string[]	Eligible account addresses.
`responses`	object[]	Up to 250 configured responses.
`delay_ms`	integer, 0-30000	Simulated response delay. Default: `0`.

Each gemini.responses[] entry accepts:

Parameter	Type	Description
`prompt`	string, required	1-20,000 characters.
`text`	string, required	1-200,000 characters.
`email_address`	string or null	Account match.
`draft_id`	string or null	Draft match.
`surface`	`"compose"`, `"sidebar"`, or null	Surface match.
`thread_id`	string or null	Thread match.
`source_message_ids`	string[] or null	Source message matches.

Snapshot restore

You can alternatively supply the complete exported object containing runtime_snapshot and mailboxes. Reuse the export intact.

API coverage and limitations

Twin name: gmail CLI quickstart: Use the Google Workspace CLI with Arga twins Supports

Gmail API workflows for inboxes, threads, messages, drafts, labels, attachments, search, send behavior, and watch events.
Authorization-code OAuth, S256 PKCE, offline refresh, and signed OIDC ID tokens. See Google OAuth and OIDC setup for callback registration and token verification.
Seeded mailbox state, deterministic message/thread IDs, and resettable state for repeatable email-agent tests.
File attachment metadata and download flows for agents that inspect or transform message attachments.

Known limitations

Mailboxes start empty unless seeded or populated by the app under test.
Delivery, spam classification, and provider reputation behavior are deterministic approximations rather than live Gmail infrastructure.
The twin focuses on Gmail API-compatible agent workflows; broad Google Workspace admin behavior is outside the primary fidelity target.

MCP tools: get_twin_catalog, provision_twins, start_url_validation, get_validation_results. See Scenario seeding for saving, provisioning, and resetting fixtures.

Get started

Digital twins

Tests

Setup

Integrations

Resources

Example seed

Parameters

Top-level fields: `seed_config.gmail`

Messages: `gmail.messages[]`

Drafts: `gmail.drafts[]`

Attachments: `messages[].attachments[]` or `drafts[].attachments[]`

Profile: `gmail.profile`

Test credentials: `gmail.tokens[]`

Browser accounts: `gmail.browser_accounts.<email>`

Browser connections: `gmail.browser_connections.<service>`

Writing assistant: `gmail.gemini`

Snapshot restore

API coverage and limitations

​Example seed

​Parameters

​Top-level fields: seed_config.gmail

​Messages: gmail.messages[]

​Drafts: gmail.drafts[]

​Attachments: messages[].attachments[] or drafts[].attachments[]

​Profile: gmail.profile

​Test credentials: gmail.tokens[]

​Browser accounts: gmail.browser_accounts.<email>

​Browser connections: gmail.browser_connections.<service>

​Writing assistant: gmail.gemini

​Snapshot restore

​API coverage and limitations

Example seed

Parameters

Top-level fields: `seed_config.gmail`

Messages: `gmail.messages[]`

Drafts: `gmail.drafts[]`

Attachments: `messages[].attachments[]` or `drafts[].attachments[]`

Profile: `gmail.profile`

Test credentials: `gmail.tokens[]`

Browser accounts: `gmail.browser_accounts.<email>`

Browser connections: `gmail.browser_connections.<service>`

Writing assistant: `gmail.gemini`

Snapshot restore

API coverage and limitations