# Security model for agent email

> What an agent's API key can and cannot do in Trotta Mail: held mail, sealed sign-in codes, scopes, unclaimed agents, two-factor and the audit log.

Source: https://trotta.email/docs/security

Agents believe what they read. So the guard decides before delivery, and an agent's key cannot overrule it. A human can.

## What an agent's key can never do

These take a human signed in to the web app, or a key a human created with `guard:release`. Keys made by sign-up do not have it.

- Read held or refused mail. Not by get, list, search, thread, context, events, webhooks or MCP.
- Release held mail, approve a pending send, or discard either.
- Loosen `guard_mode` or `send_approval`. It can always tighten.
- Create an inbox weaker than the strictest one it already has.
- Delete an inbox that holds mail the guard stopped.
- Add an allow entry, remove a block entry, or remove a send allow entry.
- Relabel, trash or delete what the guard stopped. That is the record of what was tried.
- Delete any mail for good, or empty the trash. It can move delivered mail to trash.
- Create a key with scopes it does not hold, or revoke a stronger key.

And two things no key can do at all, whatever its scopes, unless a signed-in human changes the inbox:

- See [login mail](https://trotta.email/docs/security#sealed-login-mail) in a human's inbox.
- [Send](https://trotta.email/docs/security#agent-writes) from a human's inbox. It can leave a draft.

Reading mail as it was sent (original text, HTML, raw) is a separate scope, `mail:full`. Without it a key gets the safe view. MCP tools return the safe view always.

## Sealed login mail

A hijacked agent with your mailbox could ask a site for a password reset, read the email, and own the account. So login mail is sealed.

- Login mail is inbound mail that carries a one-time code, a password reset link or a sign-in link. The guard decides from the content, whoever sent it. It sets `auth_kind` to `code`, `reset` or `sign_in_link`.
- An inbox has `auth_mail`: `sealed` or `open`. A human's inbox starts sealed. An agent's own inbox starts open, because that is where it receives its own sign-up codes.
- To any API key a sealed message does not exist. Not redacted: absent. `404` by id, the same as an unknown id. Left out of lists, search, threads, context, `wait`, events, the stream, webhooks, counts and MCP. No scope changes that, `mail:full` and `guard:release` included.
- A human sees it as usual, marked sealed. In the web app a fresh code floats up to be copied.
- Only a signed-in human can open an inbox's login mail to keys. A key can seal it. Both are in the audit log as `inbox.auth_mail`.

## What an agent may write

An inbox has `agent_write`. It governs API keys only. A human always writes as before.

| Level | A key can | Otherwise |
| --- | --- | --- |
| `none` | Read. Write nothing. | `403 agent_write_off` |
| `drafts` | Leave a draft, and edit or delete its own draft until a human edits it. | Send, reply, forward, send a draft: `403 agent_drafts_only` |
| `send` | Send, reply and forward. Approval for outgoing mail still applies. | As before |

- A human's inbox starts at `drafts`. An agent's own inbox starts at `send`.
- Raising the level takes a signed-in human. A key can lower it.
- A draft a key wrote carries `drafted_by`. The web app marks it and says so again in the composer.
- It is screened with the agent rules when it is sent, whoever presses send.
- A key can draft a reply only to mail it can read. Never to sealed or held mail.

## Scopes

| Scope | Allows |
| --- | --- |
| `mail:read` | Read mail in the safe view. Wait for mail. Move mail to trash. |
| `mail:send` | Send. Replying and forwarding quote mail, so they need mail:read too. |
| `mail:full` | Read mail as it was sent. Not for agents. |
| `guard:release` | Read and release held mail. Loosen protection. Not for agents. |
| `admin` | Manage inboxes, keys, webhooks, lists and domains. |

A key with `inbox_id` set sees and affects that inbox only: its mail, its events, its webhooks, its list entries. Anything organization-wide answers `403 key_limited_to_one_inbox`.

## Unclaimed agents

- An agent that signed itself up replies only to senders whose mail arrived authenticated.
- It cannot start a conversation with a new outside address.
- 2 inboxes, 50 recipients a day.
- Its `claim_url` works once, for 30 days. If the agent named a human, only that human can claim it.
- After a claim its key reads and sends for its own inbox and loses `admin`. Its webhooks and list entries are held to that inbox. It never reaches the human's mailbox.

## Human sessions

- The session is an httpOnly cookie. Scripts cannot read it.
- It is never in a response body, never a bearer token, never in a URL.
- A change made with the cookie must come from the web app's own origin, or it answers `403 cross_site_request`.
- You can list where you are signed in, end one session, or sign out everywhere.
- Changing the password signs every other session out.

## Sign-in

- Passwords need 10 characters and cannot be common or built from your name.
- A wrong password and an unknown address get the same answer, in the same time.
- Repeated failures lock sign-in, for longer each time.

## Two-factor

Turn it on in the [console](https://trotta.email/console/security). It is a standard authenticator code. You get ten recovery codes, shown once, each good once. The secret is stored encrypted, and a code cannot be used twice.

## Audit log

`GET /v1/audit` lists who did what, from where, newest first. Secrets, passwords and message content are never written to it.

| Prefix | What is recorded |
| --- | --- |
| `auth.` | Sign-up, sign-in, failed sign-in, sign-out, sessions ended, two-factor on and off, password changed. |
| `key.` | Keys created and revoked. |
| `agent.` | Agents claimed. |
| `inbox.` | Inboxes created and deleted. Every change to guard_mode or send_approval. |
| `list.` | Allow and block entries added and removed. |
| `webhook.` | Webhooks created, changed, deleted. Secrets rotated. |
| `domain.` | Domains added, connected and removed. |
| `message.` | Held mail released, approved, discarded or reported. |

## Webhooks

- Every request is signed. The secret is shown on create and on rotate, and never again.
- In production a webhook must be `https` and resolve only to public addresses. Loopback, private, link-local and cloud metadata addresses are refused.
- The check runs again on every delivery, against the exact address the request goes to.
- Redirects are never followed.
