Email Drafts

Create, edit, and manage email drafts. Each draft is stored as an application state entry keyed compose-{id}. The UI refreshes through the framework polling/query invalidation path and updates the compose panel automatically.

Storage

Drafts are stored in the application_state SQL table via writeAppState("compose-{id}", draft) from @agent-native/core/application-state. Each entry is one draft. Multiple drafts can exist simultaneously — they appear as tabs in the compose panel.

Calling manage-draft

manage-draft's call arguments are NOT the stored draft record below — every call requires a top-level action, and action decides which other fields apply:

action	Other required fields	Notes
create	none	id is optional; the action assigns one when omitted. Recipient/subject/body fields are all optional but should be set to compose real content.
update	id	id must be the id returned by a prior create call — never invent one.
delete	id	Removes the compose state and its saved mailbox copy.
delete-saved	savedDraftId	Use when only the saved mailbox copy remains (compose state already closed).
delete-all	none	Deletes every open compose draft.

There is no standalone "create draft" tool — create is this action's only entry point for a new draft. Always call action: "create" first and use the id it returns for any later update/delete on that same draft; do not call update/delete speculatively before a matching create.

To draft a reply to a specific message, create with mode: "reply" and replyToId set to that message's id:

{
  "action": "create",
  "to": "recipient@example.com",
  "subject": "Re: Meeting follow-up",
  "body": "Hi team,\n\nThanks for the great discussion today...",
  "mode": "reply",
  "replyToId": "18d4a2f9e1b2c3d4"
}

Stored Draft Record (compose-{id})

This is the persisted shape of the compose-{id} application-state row that manage-draft reads and writes — not the manage-draft call arguments above.

{
  "id": "abc123",
  "to": "recipient@example.com",
  "cc": "",
  "bcc": "",
  "subject": "Meeting follow-up",
  "body": "Hi team,\n\nThanks for the great discussion today...",
  "mode": "compose",
  "replyToId": "",
  "replyToThreadId": ""
}

Fields

Field	Type	Required	Description
id	string	yes	Unique draft ID (must match key suffix)
to	string	no	Comma-separated recipient email addresses
cc	string	no	Comma-separated CC addresses
bcc	string	no	Comma-separated BCC addresses
subject	string	no	Email subject line
body	string	no	Email body in markdown (see formatting below)
mode	string	no	One of: "compose", "reply", "forward" (defaults to "compose")
replyToId	string	no	Message ID being replied to (for reply/forward)
replyToThreadId	string	no	Thread ID for grouping (for reply/forward)

Body Formatting

The body field uses markdown. The compose editor (TipTap) renders it as rich text, and the send flow converts markdown to HTML before sending via Gmail. Use standard markdown syntax:

• Links: [click here](https://example.com) — renders as a clickable hyperlink in the sent email
• Bold: **bold text**
• Italic: *italic text*
• Lists: - item (unordered) or 1. item (ordered)
• Headings: # Heading (h1–h3)
• Code: `inline code` or fenced code blocks
• Blockquotes: > quoted text
• Bare URLs: https://example.com auto-links

Do NOT use raw HTML tags — use markdown only.

Signature and Style Settings

Before creating or rewriting a draft, read the user's drafting settings with pnpm action get-mail-settings.

• Use signature exactly when it is configured; do not rewrite or duplicate it.
• If no signature is configured, omit the signature. Never derive one from the user's name, email address, or connected profile.
• Follow writingStyle when present.
• Keep generated copy natural and specific. Avoid generic AI email tropes, headings, and over-formal filler unless the user asks for that style.

Updating Durable Drafting Settings

Treat requests to permanently change, add to, or remove a writing-style rule as settings changes, not drafting requests. Route them to update-mail-settings. Do not call manage-draft, open the compose UI, or create a draft unless the user separately asks to create or edit an email draft.

For a durable settings request:

1. Read the current settings with get-mail-settings.
2. Merge the requested rule into the existing writingStyle, preserving unrelated instructions. For a removal, remove only the requested rule.
3. If the requested change is ambiguous, conflicts with existing guidance, or would materially rewrite the style, show the proposed merged wording and ask the user to confirm before changing it.
4. Call update-mail-settings with the complete merged writingStyle value.
5. Re-read the settings with get-mail-settings and confirm the persisted result. Do not report success based only on the update call response.

If the user asks both to change the durable style and to draft an email, update the settings first, then create the separately requested draft using the confirmed settings. A style-setting request alone must leave compose state unchanged.

Autocomplete is a separate presentation preference; it changes inline compose suggestions and never changes generated draft text. Only change it when the user explicitly asks to enable or disable autocomplete. Read the current settings first, update only autocompleteEnabled, and re-read to verify persistence.

How It Works

1. Write writeAppState("compose-{id}", draft) — the shared application state row changes
2. UI polling sees the change — invalidates the compose-drafts React Query cache
3. Compose panel re-renders — shows the updated draft as a tab, switches to it if new

The compose panel opens automatically when any compose draft exists. When the last draft is deleted, the panel closes.

Use the manage-draft action, not raw writeAppState

manage-draft is the real action surface for compose drafts (action: create | update | delete | delete-all). Prefer it over hand-writing compose-{id} state directly — it does things a raw write will not:

• Sanitizes the id. IDs must match /^[a-zA-Z0-9_-]{1,64}$/ (sanitizeDraftId); an invalid id on create silently falls back to a timestamp-based id instead of failing.
• Appends the signature automatically on create via appendSignatureToBody(body, signature), reading the configured signature from mail-settings. This is idempotent (no-ops if the signature text is already in the body) and signature-aware of quoted content — it inserts the signature before any — On ... wrote: or — Forwarded message — block, not after it. update does NOT re-append the signature — only create does, so edit calls should not need to touch the signature themselves.
• Returns a deepLink (via link()) that opens the exact draft in the real Mail compose UI (embedApp/mcpApp resource with contact autocomplete, attachments, and send controls) — surface this link when running outside the first-party UI (e.g. from an MCP host).

pnpm action manage-draft --action=create --to=jane@example.com --subject="Quick question" --body="Hi Jane,\n\nJust wanted to follow up on..."
pnpm action manage-draft --action=update --id=draft1 --body="Hi Jane,\n\nI refined the draft as requested..."
pnpm action manage-draft --action=delete --id=draft1
pnpm action manage-draft --action=delete-all

When the compose state is already closed and only its saved mailbox copy remains, use manage-draft with action: "delete-saved", the exact savedDraftId, savedDraftBackend when known (gmail or local), and accountEmail when known. Use action: "delete" when the compose draft itself still exists; that also removes its saved mailbox copy.

Listing All Drafts

pnpm action view-composer

Or from code:

import { listAppState } from "@agent-native/core/application-state";
const drafts = await listAppState("compose-");

Attaching Files

The send-email action accepts an optional attachments array. Each entry must reference a file that was previously uploaded via the media-upload endpoint (/api/media/upload). Pass the server-side filename (the key returned by the upload endpoint, e.g. abc123.pdf), and optionally originalName (display name for the recipient) and mimeType. The attachment plumbing resolves the file from data/uploads/ or from the configured file-storage URL recorded by the upload endpoint, then includes it as a MIME multipart attachment in the outgoing Gmail message. Do not store or paste attachment bytes, base64, or data: URLs in draft state/settings; files are never sent speculatively — only attach what the user has explicitly provided and confirmed.

Local files from an MCP host

A hosted Mail app cannot read a path on the MCP host's local filesystem. Use create-attachment-upload with the file's display name. It returns a five-minute, owner-bound uploadUrl, a PUT method, and the attachment handle Mail expects. From the local host, upload the raw bytes directly:

curl --fail-with-body --request PUT --header '<Authorization header>' --data-binary @/absolute/path/to/report.pdf '<uploadUrl>'

Use the response's attachment object in the draft/send request. The upload Authorization header is a short-lived bearer credential: do not log, persist, reuse, or share it. Creating or consuming it does not send mail. Keep send-email behind its normal explicit-intent and human-approval gate; for drafting, pass the handle through ask_app or open the returned compose deep link.

Example:

{
  "to": "recipient@example.com",
  "subject": "Q2 Report",
  "body": "Please find the report attached.",
  "attachments": [
    { "filename": "abc123.pdf", "originalName": "Q2-Report.pdf", "mimeType": "application/pdf" }
  ]
}

Attachments are resolved eagerly, before Gmail is touched: if any referenced upload can't be read, send-email throws immediately (nothing is sent) rather than sending a partial message. If you see that error, the fix is re-uploading via the media endpoint, not retrying the same filename.

What Actually Happens on Send

send-email requires explicit user intent to send — it is needsApproval: true and pauses for human approval before the real Gmail call happens. This is the canonical, intentionally rare use of the human-in-the-loop gate in this framework. An authenticated A2A caller may carry the user's exact chat authorization for one matching send; otherwise the loop pauses for approval. Drafting and queueing are unaffected by the gate.

It branches on whether the user has a connected Google account:

• Connected: resolves an access token (refreshing if the account's expiry_date is within 60s), resolves reply threading (inReplyTo / References headers) by fetching the original message metadata when replyToId is set, resolves the sender display name via resolveGoogleSenderIdentity (caching the result), builds the raw MIME message, and calls the real Gmail send API.
• Not connected (no Google account): synthesizes a fake sent message and appends it to the user's local-emails setting so the UI still shows a "Sent" item — this is a demo/fallback path, not a queued real send. Do not tell the user the email left their real inbox in this mode.
• Open/click tracking: if mail-settings.tracking.opens or .clicks is enabled, send-email rewrites the outgoing body with a tracking pixel and per-link click tokens before building the MIME message, and persists the token map keyed by the real Gmail message id. get-tracking --id=<messageId> reads back open count and per-link click stats for a previously sent message; it returns tracked: false (not an error) for messages that were sent before tracking was enabled or when tracking is off.
• Multiple connected Google accounts: send-email's optional account param picks the sender; when replying, it also tries each connected account until one can fetch the original message, and uses that account as the sender if account wasn't explicit.

Send + Mark Done

get-mail-settings.sendAndArchive controls whether ordinary reply sends also mark the source thread Done. An explicit Send + Mark Done request takes precedence when the preference is off. For action-based sends, call send-email first and only call archive-email for the original reply message after the send succeeds. If archiving then fails, report that the reply was sent but the thread was not marked Done; never retry the send to recover the archive failure. This preference does not apply to new messages or forwards.

Scheduled Sends

Scheduled sends use job ids prefixed scheduled-; send-scheduled-email-now and cancel-scheduled-email both strip that prefix internally before looking up the job — pass the id as shown to the user either way.

Use create-scheduled-send to create one from an agent call. It is approval gated like send-email and is not a page-local WebMCP tool. Its payload must include to, subject, and body; it may also include cc, bcc, the selected accountEmail, reply/thread ids, and previously uploaded attachments. The top-level accountEmail and threadId identify the selected sender and thread, while the same fields in payload are persisted for the worker. Pass a future epoch-millisecond runAt and use only a connected account resolved for the current owner. create-scheduled-job is the page-local action for snoozes.

Snippets

manage-snippets lists, creates, updates, and deletes saved reply snippets. Users insert them from the compose slash menu, so a snippet the agent saves becomes available there immediately.

Aliases Are Settings-UI Only

Aliases (Settings → Aliases) are managed only through raw /api/* routes from the Settings UI — there is no manage-aliases action, so the agent cannot add, edit, or remove an alias on the user's behalf. Point the user at Settings → Aliases instead.

Important Notes

• The id field in the JSON MUST match the {id} in the key name (compose-{id})

• The UI debounces writes by 300ms — if the user is actively typing, your write will be visible after a brief moment

• Always use valid JSON with proper escaping (especially newlines in body: use \n)

• Multiple drafts can exist simultaneously — each appears as a tab in the compose panel

• When the user asks you to "draft" or "compose" an email, write a compose entry — don't use the send API directly

• When the user asks you to "edit" or "improve" a draft, list drafts first, then read and update the relevant one

• When called from the compose Generate button: the context tells you which draft to update (e.g. compose-abc123). Always update THAT entry — do NOT create a new one with a different ID. Read, modify, and write back to the same key.

• When drafting from scratch (no compose window open): create a new entry with any unique ID

• The id field in the JSON MUST match the {id} in the key name (compose-{id})

• The UI debounces writes by 300ms — if the user is actively typing, your write will be visible after a brief moment

• Always use valid JSON with proper escaping (especially newlines in body: use \n)

• Multiple drafts can exist simultaneously — each appears as a tab in the compose panel

• When the user asks you to "draft" or "compose" an email, write a compose entry — don't use the send API directly

• When the user asks you to "edit" or "improve" a draft, list drafts first, then read and update the relevant one

• When called from the compose Generate button: the context tells you which draft to update (e.g. compose-abc123). Always update THAT entry — do NOT create a new one with a different ID. Read, modify, and write back to the same key.

• When drafting from scratch (no compose window open): create a new entry with any unique ID