Mail actions

26 actions. Each action calls the same API route with the same scopes on every surface.

mail_account

Get a Mail account.

Route	GET /api/v1/mail/accounts/{id}
Tool name	calternal_api_mail_account
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_account --input '{"path":{"id":"<id>"}}' --json

mail_accounts

List Mail accounts.

Route	GET /api/v1/mail/accounts
Tool name	calternal_api_mail_accounts
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run mail_accounts --input '{}' --json

mail_cached_image

Read cached Mail content.

Route	GET /api/v1/mail/accounts/{id}/content/{resource_id}
Tool name	calternal_api_mail_cached_image
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response base64

path

Field	Type	Required	Description
id	string	yes
resource_id	string	yes

calternal action run mail_cached_image --input '{"path":{"id":"<id>","resource_id":"<resource_id>"}}' --json

mail_change_preferences

Update Mail preferences. Body fields: load_remote_content, read_marking..

Route	PATCH /api/v1/mail/preferences
Tool name	calternal_api_mail_change_preferences
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
load_remote_content	boolean | null	no	The one Load remote content switch (#726). Absent keeps the stored value.
read_marking	"on_open" | "after_one_second" | "manually" or null	no

calternal action run mail_change_preferences --input '{}' --confirm --json

mail_change_read_state

Set a Message read state. Body fields: read..

Route	POST /api/v1/mail/messages/{id}/read-state
Tool name	calternal_api_mail_change_read_state
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
read	boolean	yes

calternal action run mail_change_read_state --input '{"path":{"id":"<id>"}}' --confirm --json

mail_correct_sender_category

Set a sender Category. Body fields: category..

Route	POST /api/v1/mail/messages/{id}/category
Tool name	calternal_api_mail_correct_sender_category
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
category	string	yes

calternal action run mail_correct_sender_category --input '{"path":{"id":"<id>"}}' --confirm --json

mail_create_account

Connect a Mail account. Body fields: app_password, email, imap_host, imap_port, imap_tls_mode, provider, smtp_app_password, smtp_host, smtp_port, smtp_tls_mode, smtp_username, username..

Route	POST /api/v1/mail/accounts
Tool name	calternal_api_mail_create_account
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
app_password	string	yes
email	string	yes
imap_host	string	yes
imap_port	integer, int32 (0–)	yes
imap_tls_mode	"implicit" | "starttls"	yes	IMAP transport mode. Cleartext authentication is never allowed.
provider	"gmail" | "icloud" | "fastmail" | "custom"	yes
smtp_app_password	string | null	no
smtp_host	string	yes
smtp_port	integer, int32 (0–)	yes
smtp_tls_mode	"implicit" | "starttls"	yes	IMAP transport mode. Cleartext authentication is never allowed.
smtp_username	string	yes
username	string	yes

calternal action run mail_create_account --input '{}' --confirm --json

mail_download_attachment

Download a Mail attachment in byte chunks up to 720 KiB; continue at the returned content-range..

Route	GET /api/v1/mail/messages/{id}/attachments/{section_id}
Tool name	calternal_api_mail_download_attachment
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response base64

path

Field	Type	Required	Description
id	string	yes
section_id	string	yes

headers

Field	Type	Required	Description
Range	string | null	no

calternal action run mail_download_attachment --input '{"path":{"id":"<id>","section_id":"<section_id>"}}' --json

mail_events

Stream only User-scoped folder invalidations so Mail badges can refresh after durable cache changes. The initial event and lag recovery both ask the client to reread snapshots; message contents never enter this stream (#771). Continuation: Reduce poll_ms after an overflow. Read current snapshots after reconnect; this stream does not replay events..

Route	GET /api/v1/mail/events
Tool name	calternal_api_mail_events
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response sse

calternal action run mail_events --input '{}' --json

mail_folders

List Mail folders.

Route	GET /api/v1/mail/accounts/{id}/folders
Tool name	calternal_api_mail_folders
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_folders --input '{"path":{"id":"<id>"}}' --json

mail_message

Get a Message.

Route	GET /api/v1/mail/messages/{id}
Tool name	calternal_api_mail_message
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_message --input '{"path":{"id":"<id>"}}' --json

mail_messages

List messages in a Folder Continuation: Pass both next fields unchanged. Reduce limit after an overflow..

Route	GET /api/v1/mail/folders/{id}/messages
Tool name	calternal_api_mail_messages
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

query

Field	Type	Required	Description
before_id	string	no
before_received_ms	integer, int64	no
category	string	no
limit	integer (0–)	no

calternal action run mail_messages --input '{"path":{"id":"<id>"}}' --json

mail_mutate_preferences

Proving adapter for the shared receipt primitive; no provider I/O (#667, §58).. Body fields: expected_revision, operation_id, read_marking..

Route	POST /api/v1/mail/preferences/mutations
Tool name	calternal_api_mail_mutate_preferences
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
expected_revision	integer, int64	yes
operation_id	string	yes
read_marking	"on_open" | "after_one_second" | "manually"	yes

calternal action run mail_mutate_preferences --input '{}' --confirm --json

mail_preference_receipt

Reconcile uncertain acknowledgements after reconnect; access is checked again..

Route	GET /api/v1/mail/preferences/mutations/{id}
Tool name	calternal_api_mail_preference_receipt
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_preference_receipt --input '{"path":{"id":"<id>"}}' --json

mail_preference_state

Read one authoritative preference/revision pair before a conditional mutation..

Route	GET /api/v1/mail/preferences/state
Tool name	calternal_api_mail_preference_state
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run mail_preference_state --input '{}' --json

mail_preferences

Get Mail preferences.

Route	GET /api/v1/mail/preferences
Tool name	calternal_api_mail_preferences
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

calternal action run mail_preferences --input '{}' --json

mail_remove_account

Remove a Mail account.

Route	DELETE /api/v1/mail/accounts/{id}
Tool name	calternal_api_mail_remove_account
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_remove_account --input '{"path":{"id":"<id>"}}' --confirm --json

mail_sync_now

Start a Mail sync.

Route	POST /api/v1/mail/accounts/{id}/sync
Tool name	calternal_api_mail_sync_now
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_sync_now --input '{"path":{"id":"<id>"}}' --confirm --json

mail_sync_status

Get Mail sync status.

Route	GET /api/v1/mail/accounts/{id}/sync
Tool name	calternal_api_mail_sync_status
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_sync_status --input '{"path":{"id":"<id>"}}' --json

mail_test_connection

Test a Mail account connection. Body fields: app_password, email, imap_host, imap_port, imap_tls_mode, provider, smtp_app_password, smtp_host, smtp_port, smtp_tls_mode, smtp_username, username..

Route	POST /api/v1/mail/accounts/test
Tool name	calternal_api_mail_test_connection
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

body

Field	Type	Required	Description
app_password	string	yes
email	string	yes
imap_host	string	yes
imap_port	integer, int32 (0–)	yes
imap_tls_mode	"implicit" | "starttls"	yes	IMAP transport mode. Cleartext authentication is never allowed.
provider	"gmail" | "icloud" | "fastmail" | "custom"	yes
smtp_app_password	string | null	no
smtp_host	string	yes
smtp_port	integer, int32 (0–)	yes
smtp_tls_mode	"implicit" | "starttls"	yes	IMAP transport mode. Cleartext authentication is never allowed.
smtp_username	string	yes
username	string	yes

calternal action run mail_test_connection --input '{}' --confirm --json

mail_thread_attachments

List Thread attachments.

Route	GET /api/v1/mail/threads/{id}/attachments
Tool name	calternal_api_mail_thread_attachments
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_thread_attachments --input '{"path":{"id":"<id>"}}' --json

mail_thread_messages

List messages in a Thread Continuation: Pass both next fields unchanged. Reduce limit after an overflow..

Route	GET /api/v1/mail/threads/{id}/messages
Tool name	calternal_api_mail_thread_messages
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

query

Field	Type	Required	Description
before_id	string	no
before_received_ms	integer, int64	no
category	string	no
limit	integer (0–)	no

calternal action run mail_thread_messages --input '{"path":{"id":"<id>"}}' --json

mail_thread_oldest_unread

Find the oldest unread message.

Route	GET /api/v1/mail/threads/{id}/oldest-unread
Tool name	calternal_api_mail_thread_oldest_unread
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

path

Field	Type	Required	Description
id	string	yes

calternal action run mail_thread_oldest_unread --input '{"path":{"id":"<id>"}}' --json

mail_undo_preferences

Undo uses the server’s inverse and current revision; replay is idempotent.. Body fields: operation_id..

Route	POST /api/v1/mail/preferences/mutations/{id}/undo
Tool name	calternal_api_mail_undo_preferences
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
operation_id	string	yes

calternal action run mail_undo_preferences --input '{"path":{"id":"<id>"}}' --confirm --json

mail_unified_inbox

List Inbox messages Continuation: Pass both next fields unchanged. Reduce limit after an overflow..

Route	GET /api/v1/mail/inbox/messages
Tool name	calternal_api_mail_unified_inbox
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	read only
Encoding	request none, response json

query

Field	Type	Required	Description
before_id	string	no
before_received_ms	integer, int64	no
category	string	no
limit	integer (0–)	no

calternal action run mail_unified_inbox --input '{}' --json

mail_update_account

Update an unlinked Mail account. Body fields: app_password, email, enabled, imap_host, imap_port, imap_tls_mode, provider, smtp_app_password, smtp_host, smtp_port, smtp_tls_mode, smtp_username, username..

Route	PATCH /api/v1/mail/accounts/{id}
Tool name	calternal_api_mail_update_account
Surfaces	cli, mcp, webmcp
Scopes	data
Effect	destructive, needs --confirm
Encoding	request json, response json

path

Field	Type	Required	Description
id	string	yes

body

Field	Type	Required	Description
app_password	string | null	no
email	string | null	no
enabled	boolean | null	no
imap_host	string | null	no
imap_port	integer | null, int32 (0–)	no
imap_tls_mode	"implicit" | "starttls" or null	no
provider	"gmail" | "icloud" | "fastmail" | "custom" or null	no
smtp_app_password	string | null	no
smtp_host	string | null	no
smtp_port	integer | null, int32 (0–)	no
smtp_tls_mode	"implicit" | "starttls" or null	no
smtp_username	string | null	no
username	string | null	no

calternal action run mail_update_account --input '{"path":{"id":"<id>"}}' --confirm --json