> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noresponse.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Allow and block lists

> Block or allow the accounts that use an email or an email domain, whatever their score. Read the list with GET, add an entry with POST and delete one with DELETE on /v1/workspaces/{workspace_id}/lists/{environment}.

Each environment of your workspace, `live` and `test`, has its own list. An entry of the list is an exact email or an email domain, with the action `block` or `allow`. The entry decides each account that it matches, whatever the score of the account.

Use a block entry when your team finds a source of abuse, such as a domain that a signup burst uses. Use an allow entry for addresses that you trust, such as the accounts of your staff or of your test robots.

| Route | What it does | Who can call it |
| - | - | - |
| `GET /v1/workspaces/{workspace_id}/lists/{environment}` | Pages through the entries, newest first. | An API key with `settings` or `management`, or an authorized member. |
| `POST /v1/workspaces/{workspace_id}/lists/{environment}` | Adds one entry. | An API key with `settings` and `policy_publish`, or `management`, or an authorized member. |
| `DELETE /v1/workspaces/{workspace_id}/lists/{environment}/{list_entry_id}` | Deletes one entry. | An API key with `settings` and `policy_publish`, or `management`, or an authorized member. |

`environment` is `live` or `test`. A key reads and changes the list of its own environment only. The other environment answers 404 [`not_found`](https://docs.noresponse.org/problems/not-found). [Scopes](https://docs.noresponse.org/authentication.md#scopes) explains the separate read and publication permissions.

Pass `next_cursor` back as `cursor` to read the next page. Set `expires_at` when an entry should stop applying at a known time.

## Add an entry

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -X POST "https://api.noresponse.org/v1/workspaces/$WORKSPACE_ID/lists/live" \
  -H "Authorization: Bearer $NORESPONSE_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "email_domain", "value": "throwaway.example", "action": "block", "note": "Signup burst"}'
```

**kind** `string` *required*

`email` matches one address. `email_domain` matches every address of the domain and of its subdomains.

**value** `string` *required*

The email or the domain. NoResponse keeps it in a canonical form and answers that form. An email is lower case, so `Jane.Doe@Example.com` matches `jane.doe@example.com`. An email is also folded to the mailbox it delivers to. A `+tag` is dropped, so `jane+signup@example.com` matches `jane@example.com`. At Gmail the dots are dropped too, so `j.ane@googlemail.com` matches `jane@gmail.com`. A domain becomes its registrable domain, so `mail.example.co.uk` becomes `example.co.uk`. Domains under a hosting suffix keep their own name, so `jane.blogspot.com` matches only that domain. A public suffix alone, such as `co.uk` or `blogspot.com`, answers 400.

**action** `string` *required*

`block` or `allow`.

**note** `string`

Why the entry exists, at most 200 characters. The list shows it with the entry. It decides nothing.

The answer is 201 with the entry and its `id`. A value already on the list answers 409 [`list_entry_exists`](https://docs.noresponse.org/problems/list-entry-exists). A list holds at most 10,000 entries. A full list answers 409 [`list_limit_reached`](https://docs.noresponse.org/problems/list-limit-reached).

Use `POST /v1/workspaces/{workspace_id}/lists/{environment}/preview` to inspect matches before changing the list. It does not publish the change. The answer comes from retained assessments, so a member also needs `history.read` and `evidence.read`. A key also needs `history`, or `investigate` with `evidence` or `detailed`.

Use the `/bulk` route to add and delete entries atomically with an idempotency key. Poll the returned list change to track propagation through matching accounts. Propagation continues in bounded batches, including matches beyond the former 5,000-account limit.

## How an entry decides an account

An account matches an entry when one of its assessments sent the email, or an email of the domain.

* A `block` entry makes the decision `block` for each flow.
* An `allow` entry makes the decision `allow` for each flow.
* When a block entry and an allow entry match the same account, `block` wins.
* A flow that is `held` stays `held` until its investigation completes. See [Admission and late decisions](https://docs.noresponse.org/guides/late-results.md).

The risk of the account carries the reason [`list_match`](https://docs.noresponse.org/reference/reason-codes#accounts). Its `list_entry_id` names the entry. The score does not change, so you still see what the facts of the account show. The `detail.risk` of an assessment does not carry `list_match`.

A change to the list propagates through retained matching accounts. NoResponse sends [`account.risk_changed`](https://docs.noresponse.org/guides/webhooks#account-risk_changed) when an account decision changes. Your enforcement handler can then apply the new decision without a new assessment. Deleting an entry or reaching its expiry also schedules propagation.

An entry matches the assessments that NoResponse made from this release on. NoResponse did not keep the keys of earlier emails.

## Privacy and the audit log

NoResponse compares a keyed digest of each value, never the value itself. The list keeps the value that you sent, so that you can read it. It goes with the entry, or with the workspace.

Each change goes into the audit log of the workspace as `list_entry.created` or `list_entry.deleted`, with the member or the key that made it. The event names the kind and the action, never the value.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.