Return the JMAP session: capabilities, account IDs, username, and feature availability.

Use this to discover what features and scopes are available with your API token.

List all mailboxes (folders) in the account.

Returns name, role (inbox/sent/drafts/trash/etc.), parent, email counts.

Create a new mailbox (folder).

Args: name: Display name for the mailbox. parent_id: ID of the parent mailbox for nested folders (empty for top-level).

Update a mailbox (rename or move under a different parent).

Args: mailbox_id: ID of the mailbox to update. name: New display name (empty to leave unchanged). parent_id: New parent mailbox ID (empty to leave unchanged; "null" moves to top-level).

Destroy (delete) a mailbox. Fails if the mailbox has children or is a system role.

Search for emails with structured filters. Returns matching emails with preview.

Args: in_mailbox: Mailbox ID to search within. text: Full-text search across all fields (from, to, subject, body). from_addr: Filter by sender address or name. to_addr: Filter by recipient address or name. subject: Filter by subject text. after: Emails received after this date (ISO 8601, e.g. "2024-01-01T00:00:00Z"). before: Emails received before this date (ISO 8601). has_keyword: Require keyword/flag ("$flagged", "$seen", "$draft", "$answered"). not_keyword: Exclude emails with this keyword. has_attachment: Filter by attachment presence. filter_json: Raw JSON FilterCondition for complex queries (overrides other filter params). sort_property: Sort field — receivedAt, sentAt, from, to, subject, size. sort_ascending: Sort direction (default: newest first). limit: Max results (1–100, default 20).

Get full details for one or more emails by ID.

Args: email_ids: Comma-separated email IDs. fetch_body: Include text body content (default true). max_body_bytes: Max bytes per body part (default 10 000; protects LLM context).

Get the most recent emails in a mailbox (sorted by date, newest first).

Args: mailbox: Mailbox name or role (e.g. "inbox", "sent", "drafts", "trash", or a custom name). limit: Max results (1–50, default 25).

Get all emails in a conversation thread.

Provide either an email_id (the thread is looked up automatically) or a thread_id directly.

Args: email_id: An email ID whose thread to fetch. thread_id: A thread ID to fetch directly. max_body_bytes: Max bytes per body part (default 5000).

List attachments on an email (metadata only — use download_attachment for content).

Args: email_id: ID of the email.

Get a download URL for an email attachment.

Returns the fully-resolved URL only — does not write to the filesystem. Safe for hosted deployments.

Args: blob_id: Blob ID of the attachment (from get_email_attachments). name: Filename for the download. content_type: MIME type for the download.

Get email count statistics for one or all mailboxes.

Args: mailbox_id: Specific mailbox ID (empty for all mailboxes).

Get an aggregate account summary: total emails, unread count, mailbox breakdown.

List sending identities (email addresses you can send from).

Requires the urn:ietf:params:jmap:submission scope.

Compose and send an email immediately.

Args: to: Recipients (comma-separated, e.g. "user@example.com, Name other@example.com"). subject: Email subject line. text_body: Plain-text body content. html_body: HTML body content (optional; both text and HTML can be provided). cc: CC recipients (comma-separated, same format as to). bcc: BCC recipients (comma-separated, same format as to). identity_id: Sending identity ID (use list_identities to see options; empty for default). in_reply_to: Message-ID of the email being replied to. references: Space-separated Message-IDs for the References header.

Save a new email as a draft (not sent).

At least one of to, subject, or a body field should be provided.

Args: to: Recipients (comma-separated). subject: Email subject line. text_body: Plain-text body content. html_body: HTML body content. cc: CC recipients (comma-separated). bcc: BCC recipients (comma-separated). in_reply_to: Message-ID being replied to. references: Space-separated Message-IDs for References header.

Replace a draft with updated content.

JMAP emails are immutable — this creates a new draft and destroys the old one atomically. Empty fields keep the original value.

Args: draft_id: ID of the existing draft to replace. to: Recipients (comma-separated). Empty keeps original. subject: Email subject. Empty keeps original. text_body: Plain-text body. Empty keeps original. html_body: HTML body. Empty keeps original. cc: CC recipients. Empty keeps original. bcc: BCC recipients. Empty keeps original.

Send an existing draft email.

Args: draft_id: ID of the draft to send. identity_id: Sending identity ID (empty for default).

Reply to an email. Sends immediately by default; set send=false to save as draft.

Builds Re: subject, In-Reply-To, and References headers automatically.

Args: email_id: ID of the email to reply to. text_body: Plain-text reply body. html_body: HTML reply body. reply_all: If true, reply to all original recipients (not just sender). send: If true (default), send immediately; if false, save as draft. identity_id: Sending identity ID (empty for default).

Mark an email as read or unread.

Args: email_id: ID of the email. read: True to mark as read (default), false to mark as unread.

Pin (flag) or unpin an email.

Args: email_id: ID of the email. pinned: True to pin/flag (default), false to unpin.

Move an email to the Trash mailbox.

Move an email to a different mailbox (replaces all current mailbox assignments).

Args: email_id: ID of the email to move. mailbox_id: Target mailbox ID.

Add one or more mailbox labels to an email (without removing existing ones).

Args: email_id: ID of the email. mailbox_ids: Comma-separated mailbox IDs to add.

Remove one or more mailbox labels from an email.

Args: email_id: ID of the email. mailbox_ids: Comma-separated mailbox IDs to remove.

Mark multiple emails as read or unread.

Args: email_ids: Comma-separated email IDs (max 50). read: True to mark as read, false for unread.

Pin (flag) or unpin multiple emails.

Args: email_ids: Comma-separated email IDs (max 50). pinned: True to pin, false to unpin.

Move multiple emails to a mailbox (replaces existing mailbox assignments).

Args: email_ids: Comma-separated email IDs (max 50). mailbox_id: Target mailbox ID.

Move multiple emails to Trash.

Args: email_ids: Comma-separated email IDs (max 50).

Add mailbox labels to multiple emails.

Args: email_ids: Comma-separated email IDs (max 50). mailbox_ids: Comma-separated mailbox IDs to add.

Remove mailbox labels from multiple emails.

Args: email_ids: Comma-separated email IDs (max 50). mailbox_ids: Comma-separated mailbox IDs to remove.

List masked (alias) email addresses with pagination.

Returns a compact summary by default. Set verbose=True for full fields.

Args: state_filter: Filter by state (pending/enabled/disabled/deleted). Empty for all. limit: Max items to return (default 50, max 200). offset: Skip this many items (for pagination). verbose: If True, return all fields; if False, return compact summary.

Create a new masked (alias) email address.

Addresses created in "pending" state expire after 24 hours if not enabled.

Args: for_domain: Domain this masked email is associated with (e.g. "example.com"). description: Human-readable description. url: URL associated with this masked email. state: Initial state — "enabled" (default) or "pending".

Update a masked email address (change state, description, domain, or URL).

Args: masked_email_id: ID of the masked email to update. state: New state (enabled/disabled/deleted). Empty to leave unchanged. description: New description. Empty to leave unchanged. for_domain: New associated domain. Empty to leave unchanged. url: New associated URL. Empty to leave unchanged.

Destroy (permanently delete) a masked email address.

Get the current vacation / out-of-office auto-reply configuration.

Requires the urn:ietf:params:jmap:vacationresponse capability (Fastmail scope: Vacation responses).

Set or update the vacation / out-of-office auto-reply.

Args: is_enabled: Whether the vacation response is active. from_date: Start date (ISO 8601, e.g. "2024-12-20T00:00:00Z"). Empty to leave unchanged. to_date: End date (ISO 8601). Empty to leave unchanged. subject: Auto-reply subject line. Empty to leave unchanged. text_body: Plain-text auto-reply body. html_body: HTML auto-reply body (optional).

List Sieve filter scripts (server-side mail routing rules).

Requires urn:ietf:params:jmap:sieve in the JMAP session. If unavailable, manage filters via the Fastmail web UI (Settings → Filters & Rules).

Get a Sieve script by ID, including its full content (downloaded from blob storage).

Validate Sieve script syntax without saving.

Args: content: The Sieve script source to validate.

Create a new Sieve filter script.

Args: name: Script name. content: Sieve script source. is_active: Activate this script immediately (only one script can be active).

Update an existing Sieve script (name, content, or active state).

Args: script_id: ID of the Sieve script to update. name: New name (empty to leave unchanged). content: New Sieve source (empty to leave unchanged). is_active: Set active state (null to leave unchanged).

Destroy (delete) a Sieve script. Cannot destroy the currently active script.