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_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 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_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.

LevelA key canOtherwise
noneRead. Write nothing.403 agent_write_off
draftsLeave a draft, and edit or delete its own draft until a human edits it.Send, reply, forward, send a draft: 403 agent_drafts_only
sendSend, 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

ScopeAllows
mail:readRead mail in the safe view. Wait for mail. Move mail to trash.
mail:sendSend. Replying and forwarding quote mail, so they need mail:read too.
mail:fullRead mail as it was sent. Not for agents.
guard:releaseRead and release held mail. Loosen protection. Not for agents.
adminManage 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. 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.

PrefixWhat 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.