How Alcarta works

Alcarta places existing IMAP/SMTP and JMAP accounts behind two authenticated interfaces: REST at /api/v1 and streamable HTTP MCP at /mcp. Both call the same service layer and enforce the same permissions.

The approval queue is the spine

An outbound or destructive operation can be a two-party transaction:

1. An agent declares intent, such as wants_to_move or wants_to_send_draft.
2. Alcarta validates the target and creates a request with a chk_… ID.
3. A human reviews the live message or complete outgoing draft and approves or denies it.
4. Approval dispatches the work. Alcarta performs it exactly once and records both identities.
5. The agent observes the terminal result with email_await, email_requests, or a granular approval tool.

An executed result means the provider action finished. approved is transient and does not, by itself, promise that the provider accepted the operation. Failures end in failed and are not silently revived.

Permanent deletion always requires a request

delete_permanently never becomes a one-call direct action, even for a mailbox owner. It resolves to the approval-backed expunge path.

Live provider state

Alcarta is a gateway rather than a mail store:

• Message lists, bodies, flags, folders, and attachments are read live from the provider.
• Draft content remains in the provider’s Drafts folder. Alcarta stores a pointer and hashes used to detect edits made in another mail client.
• Approval records and draft pointers are time-limited and swept.
• Pagination cursors and message handles are opaque, authenticated values. Do not parse them.

One authorization path

Browser sessions, personal access tokens, and OAuth access tokens ultimately reach the same bearer middleware. The web application exchanges its session for a short-lived JWT and calls the REST API; it has no private route around scope checks.

Effective permission is the intersection of two sets:

effective permissions = subject grants ∩ token scopes

A token can narrow an agent or human, but cannot grant authority the subject does not have. Grant changes are resolved from current data on each request, subject to the configured short cache bound.

Main objects

Object	Prefix	Meaning
Organization	org_	Tenant boundary for mailboxes, agents, grants, and audit records
Mailbox	mbx_	Configuration for one remote account, not an IMAP folder
Agent	agt_	Machine identity with no password or browser session
Token	tok_	Revocable bearer credential belonging to one subject
Grant	grt_	Durable mailbox role and extra scopes for a subject
Approval request	chk_	Declared operation and its decision/execution state
Draft	drf_	Pointer to a draft whose canonical copy is on the provider
Audit event	evt_	Append-only record in the organization’s hash chain

Safety properties worth designing around

• A mailbox that the caller cannot see returns 404, not a revealing 403.
• Provider-authored text is explicitly marked untrusted in tool results and escaped in the UI.
• Stored mailbox credentials are write-only and envelope-encrypted.
• Draft writes use hashes and revisions; there is no force-write switch.
• A send with an indeterminate provider outcome is never retried automatically, avoiding a second copy that Alcarta cannot prove was not already sent.