> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Allow and block lists
> Control who an agent will accept mail from, reply to, or send to.
Lists gate mail per inbox, in three independent directions.
```
/v0/inboxes/{inbox_id}/lists/{direction}/{type}
```
| Segment | Values |
| ----------- | -------------------------- |
| `direction` | `receive`, `reply`, `send` |
| `type` | `allow`, `block` |
The three directions are separate on purpose. An agent can be permitted to *receive* from an address while being blocked from *replying* to it — which is exactly what you want for a mailing list or a noreply sender: keep the mail for context, never answer it.
## Adding an entry
```bash theme={null}
curl -X POST "$BASE/v0/inboxes/ava@agent.waterr.ai/lists/reply/block" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"entry": "noreply@vendor.com",
"reason": "automated sender, replies bounce"
}'
```
An entry is either a full address (`dana@example.com`) or a bare domain (`example.com`), which covers every address at it.
`reason` is free text, stored and returned. Write something a colleague could act on six months from now — a block with no reason is one nobody is willing to remove.
## Reading and removing
```bash theme={null}
GET /v0/inboxes/{inbox_id}/lists/receive/block
GET /v0/inboxes/{inbox_id}/lists/receive/block/{entry}
DELETE /v0/inboxes/{inbox_id}/lists/receive/block/{entry}
```
URL-encode the entry in the path when it contains an `@`.
## What happens on a match
**A blocked inbound message is still stored.** It is labelled `blocked`, kept out of the normal flow, and emits `message.received.blocked` instead of `message.received`. The event names what matched, in `blocked_by`.
This is deliberate. A blocked message that vanished would make the block impossible to debug, and would lose evidence in exactly the cases — abuse, a spam wave — where you most want it. Your agent simply never sees it, because it subscribes to `message.received`.
A blocked **reply** or **send** is refused at the API with `403 forbidden`, before the mail transport is touched. The error body names the direction, the recipient and whether it was a block-list hit or an allow-list miss. No event is emitted — nothing was attempted.
## Allow lists
Adding anything to an allow list for a direction makes that direction **deny-by-default** — only listed entries pass. An empty allow list means no restriction.
```bash theme={null}
# Lock this agent to one customer domain
POST /v0/inboxes/ava@agent.waterr.ai/lists/send/allow
{ "entry": "acme-corp.com" }
```
Adding a single allow entry silently narrows the direction to that entry alone. Add every address the agent legitimately needs before you add the first one, or its next send fails.
## Patterns worth copying
Block `reply` for `noreply@`, `no-reply@` and bulk senders. Combine with the `auto_reply` flag on the event, which catches vacation responders that do not use an obvious address.
On a test inbox, allow `send` only to your own domain. A prompt-injected agent cannot then email a real customer.
Allow `send` to the tenant's domain only, so a bug in routing cannot leak one customer's mail to another.
Block `receive` for the sender, then read the stored `blocked` messages when you need the evidence.
The staging pattern is the load-bearing one. An agent that reads untrusted email and can send email is a prompt-injection target: the content it processes is written by whoever emailed it. A `send/allow` list is the control that holds even when the model is talked into something.