Mailboxes and canonical workspaces
Discover Mail and an authorized Auth workspace. Mailbox IDs identify app records inside that workspace and are not workspace resource IDs. Bootstrap, collection, profile, dashboard and widget have different output shapes; inspect their contracts. Hosted, IMAP, Gmail and Microsoft 365 connections have separate setup requirements.
Compose, review and send
Create a draft, read it back and review recipients/content before sending. Immediate send and draft send can contact real recipients and cannot be recalled. A scheduled send is pending until an asynchronous sweep claims it; cancel only while pending and inspect the sent folder after uncertain outcomes.
Inbox organization
Discover messages and folders before updates/moves/deletes. Labels and snooze are local overlays; snooze expiry removes overlays without changing underlying messages. Deletion has no declared restore contract. Export required data before a separately approved destructive operation.
Assistant and audio
Assistant tools can read/search, generate paid summaries/replies/triage or save drafts; they do not send email. Review generated claims against original messages. Transcription uses the canonical inline-base64 upload contract for reviewed non-empty audio up to 8 MiB decoded. The exact candidate Mail web dictation source records microphone audio, strips recorder MIME parameters and submits the inline request; this source closure does not establish SDK/CLI/MCP emitter parity. Transcription creates no draft or email.
Connection and recovery
Provider readiness and an OAuth URL do not establish an active connection. Complete explicitly approved consent and verify connections.get. A mailbox can exist even when OAuth URL creation fails. Disconnect keeps app-owned mail; mailbox deletion permanently removes it. Preserve uncertain outcomes before any repeated effect.
Notification contracts
The pinned Mail source contract contains version 1 and version 2 for connection-expiring, connection-failed, message-received, scheduled-send-failed and send-failed events. The current emitter sends version 2 with generic title/body/CTA plus packaged localized text; the version-2 schemas omit mailbox_address, sender and subject fields that appear in version 1. This snapshot shows both versions but does not establish historical immutability of version 1. Notify acceptance is not delivery proof; inspect downstream delivery results before claiming a notification reached its recipient.
Action guides
- List Mail mailboxes
- Create Mail mailbox
- Create Mail draft
- Send Mail message
- Schedule Mail message
- Run Mail assistant tool
- Get Mail connection
- Export Mail mailbox
Evidence and limits
Identity, permissions, verified workspace grants, provider connection state, OAuth URL generation, mailbox Durable Object operations and content protection are synthetic ports.
Nexus AI and Auth archive are allowlisted in-process responses. No paid generation, billing, live OAuth, encryption custody, email delivery, asynchronous delivery or deployed outcome is proved. External network egress is refused.