# Pre-delivery, verdicts and held mail

> The ideas behind Trotta Mail: pre-delivery screening, the verdict on each message, guard modes, the safe view an agent reads, held mail and drills.

Source: https://trotta.email/docs/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.
- `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.

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