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 findsWhat the sending server is toldWhere the message goes
Malicious, known or newRefused, with an errorBlocked, for a human to check in case it was a mistake. Never an inbox.
DangerousAcceptedHeld outside the inbox until a human releases it.
Worth a second lookAcceptedThe inbox, with the caution attached.
NothingAcceptedThe 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.

actionlevelWhat happens
deliversafeDelivered. Nothing was found.
flagcautionDelivered with the caution attached.
holddangerKept out of the inbox until a human releases it.
rejectdangerRefused 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}.

ModeBehaviour
monitorNever holds. Every message is delivered with its verdict. Use it to watch what the guard would do.
guardThe default. Holds danger, flags caution, refuses malicious mail at SMTP time (a copy waits in Blocked).
lockdownOnly 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.
  • html is null.

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.

OutcomeWhat you see
deliverThe message is sent. status is sent or queued.
holdstatus is pending_approval. A human approves or discards it.
rejectHTTP 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.