Security model
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_modeorsend_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 in a human's inbox.
- Send 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_kindtocode,resetorsign_in_link. - An inbox has
auth_mail:sealedoropen. 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.
404by 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:fullandguard:releaseincluded. - 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 atsend. - 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_urlworks 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. 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
httpsand 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.