> ## Documentation Index > Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Gmail > Gmail Scenario seeding parameters, nested fields, and examples 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](https://docs.argalabs.com/api-reference/post-create-a-scenario.md). You can also import it with `arga test-runner scenarios import --file scenario.json`. ```json theme={null} { "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": "", "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": "", "references": [ "" ] } ] } } } ``` ## 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-`. | | `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.` | 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.` | 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](https://docs.argalabs.com/features/google-workspace-cli) **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](https://docs.argalabs.com/features/google-oauth.md) 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](https://docs.argalabs.com/twins/seeding.md) for saving, provisioning, and resetting fixtures. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.