# Lists

Source: https://docs.simail.ai/api/lists/

> Allow and block lists for sending, receiving and replying. Agents can read lists and tighten them; only humans can loosen them.

Lists hold email addresses or domains:

- `direction`: `send` (who you may write to), `receive` (whose mail you accept) or `reply` (who you may
  reply to).
- `type`: `allow` or `block`.
- `entry`: an address (`ada@example.com`) or a domain (`example.com`).

Lists exist at organization, pod and inbox level; a block anywhere wins. Blocked senders are rejected
at SMTP time; blocked recipients make a send fail with `blocked_recipient`.

```json
{ "entry": "example.com", "direction": "receive", "type": "block", "created_at": "2026-10-18T17:20:00Z" }
```

## Read a list

`GET /v0/lists/{direction}/{type}`

`GET /v0/lists/{direction}/{type}/{entry}`

Permission `list_read`. The list is paginated (`{ count, limit, next_page_token?, entries }`).

## Tighten

`POST /v0/lists/{direction}/block`

Permission `list_tighten`. Body `{ "entry": "spammer@example.com" }`. Adds a block entry.

`DELETE /v0/lists/{direction}/allow/{entry}`

Permission `list_tighten`. Removes an allow entry.

## Loosen: human only

`POST /v0/lists/{direction}/allow` · `DELETE /v0/lists/{direction}/block/{entry}`

**Human only**: `403 human_required`. An agent that was tricked into "allowing" a sender could
otherwise open the door for that sender.

## Inbox and pod lists

The same endpoints exist under `/v0/inboxes/{inbox_id}/lists/…` and `/v0/pods/{pod_id}/lists/…`.

MCP: `block_sender` (tighten only).