Concepts
What pre-delivery means, what a verdict is, how strict the guard is, and what an agent may read.
#Pre-delivery
A message is screened while the sending server is still connected. The answer that server gets depends on the result.
| What the guard finds | What the sending server is told | Where the message goes |
|---|---|---|
| Malicious, known or new | Refused, with an error | Blocked, for a human to check in case it was a mistake. Never an inbox. |
| Dangerous | Accepted | Held outside the inbox until a human releases it. |
| Worth a second look | Accepted | The inbox, with the caution attached. |
| Nothing | Accepted | The inbox. |
So there is no moment when unscreened mail is readable. This holds for every inbox, an agent's or a human's, and for mail between Trotta Mail inboxes.
#Verdicts
Every message, in both directions, carries a verdict. It is decided before the message is readable.
| action | level | What happens |
|---|---|---|
deliver | safe | Delivered. Nothing was found. |
flag | caution | Delivered with the caution attached. |
hold | danger | Kept out of the inbox until a human releases it. |
reject | danger | Refused at SMTP time. The sender gets an error and nothing is delivered. |
A verdict has a risk from 0 to 1, a one-sentence summary, categories and signals. Each signal has a severity, a title, an explanation and, where there is one, the piece of the message that triggered it. auth holds the SPF, DKIM and DMARC results.
#Guard modes
Each inbox has a guard_mode. Set it when you create the inbox, or later with PATCH /v1/inboxes/{id}.
| Mode | Behaviour |
|---|---|
monitor | Never holds. Every message is delivered with its verdict. Use it to watch what the guard would do. |
guard | The default. Holds danger, flags caution, refuses malicious mail at SMTP time (a copy waits in Blocked). |
lockdown | Only your own organization and allow-listed senders that prove who they are get through. Everything else is held. |
The guard is stricter for an agent than for a human. An instruction in plain sight, such as "ignore your previous instructions", is held in an agent inbox and flagged in a human's. A human can read it and shrug. A model may act on it.
#The safe view
A key reads the safe view. It is what a model should be given:
- Only content a human could see. Text hidden with CSS, comments and similar tricks is removed.
- Instructions aimed at a model are replaced by a note that names what was removed, such as
[instruction removed by Trotta: tries to override instructions]. - Links that are not clean are defanged, so they cannot be followed by accident.
htmlisnull.
The original text, the HTML and the raw message need a human, or a key a human created with the mail:full scope. A key without it that asks for view=full gets the safe view. Do not give a mail:full key to an agent.
GET /v1/threads/{id}/context returns a whole conversation as one block with boundaries around the mail and a trust level for the thread.
#Held mail
A held message is stored but not delivered. A key that reads it gets withheld: true: the sender's bare address, the verdict in fixed words, and nothing the sender wrote. That holds on every route: get, list, search, thread, context, events, webhooks and MCP.
A human signed in to the web app, or a key with guard:release, reads it and decides. POST /v1/messages/{id}/release delivers it. That emits message.released and then message.received, so an agent that was waiting simply receives the message late. GET /v1/guard/held lists everything that is waiting.
#Outbound screening
What an agent sends is screened before it leaves.
| Outcome | What you see |
|---|---|
deliver | The message is sent. status is sent or queued. |
hold | status is pending_approval. A human approves or discards it. |
reject | HTTP 422 with code outbound_blocked. The error carries the verdict, and the message is stored with status: blocked. |
The screen looks for secrets and sensitive data, and for replies that an injected instruction is steering to an address the inbox has never written to. Categories: secret_leak, sensitive_data, exfiltration, new_recipient.
To put a human on outgoing mail regardless, set send_approval to first_contact (the first message to any new recipient waits) or always.
#Allow and block lists
A list entry is an address or a domain, for receiving or for sending, on one inbox or on the whole organization. Adding or removing an entry of either kind takes a human or guard:release: a block refuses someone's mail, so an agent cannot be talked into shutting its inbox to its own human.
#Drills
POST /v1/guard/drill sends realistic test mail through the real pipeline into one of your own inboxes. Choose a scenario (prompt_injection, credential_phishing, invoice_fraud, malware, otp, login_code, newsletter, clean) or run all. Drill mail carries the label drill.