Lists API reference

Named, per-account, small sets your rules can reference: partners to always let in, competitors to keep out, domains to look at twice. Configuration measured in hundreds of rows, not list hygiene measured in millions.

Endpoints

Method	Path	Does
`GET`	`/v1/lists`	Every list, with its entry count.
`POST`	`/v1/lists`	{ name, kind, mode } — create. 201, or 200 if an identical list exists.
`GET`	`/v1/lists/:name`	The list and up to 1,000 entries. Address entries are masked; truncated says whether there were more.
`DELETE`	`/v1/lists/:name`	The list and every entry.
`POST`	`/v1/lists/:name/entries`	{ entries: [...] } — add up to 1,000 per request.
`DELETE`	`/v1/lists/:name/entries`	{ entries: [...] } — remove.
`POST`	`/v1/lists/:name/check`	{ entry } — is it on the list? Returns { member }.

Create a list and add entries

POST /v1/lists
{ "name": "partners", "kind": "domain", "mode": "allow" }

POST /v1/lists/partners/entries
{ "entries": ["acme.com", "globex.com", "*.initech.com"] }

// 200
{ "added": 3, "total": 3, "rejected": [], "warnings": [] }

name: lowercase letters, digits, - and _, starting with a letter or digit, up to 63 characters.
mode: allow, deny or neutral (the default). The mode is a label for you and for the compiler’s default ordering. It does not act by itself; a rule does.
Entries are trimmed and lowercased. Rejected entries are reported by their position in your array, never echoed back — for an address list, a rejected entry is an attempt at an address.
An address pasted into a domain or pattern list is rejected with a warning to use an address list, which is the only kind that hashes its entries.
Above 5,000 entries the response warns that the list is being used for list hygiene rather than policy. To clean a list, use bulk verification; to make addresses fail every check, use the address blocklist.

Kinds

kind	Entries and matching
`domain`	Exact domains, compared case-insensitively. No implicit subdomains: acme.com does not cover eu.acme.com. An entry containing * is treated as a glob, so *.acme.com is how you say every subdomain.
`pattern`	Every entry is a glob over the field value: .edu, .gov.uk. * matches any run of characters and nothing else is special. *.edu does not match edu itself.
`address`	Whole email addresses. Each is hashed with a keyed hash before it is stored; the plaintext is never written. The rule's field is not consulted — membership is checked against the hash of the address being decided.

Using a list in a rule

{
  "id": "r_competitors",
  "label": "Competitors are kept out",
  "when": { "field": "email.domain", "op": "in_list", "list": "competitors" },
  "then": { "action": "deny" },
  "on_unknown": "skip"
}

A list that cannot be loaded makes membership unknown, not “not a member”. That matters most for not_in_list("customers") → deny: with the default on_unknown: "skip", a failed load falls through instead of denying everyone.
A list is not a verifier. An address on an allow list is still verified and the response still carries its bounce probability; the list only affects decision.
Saving or activating a policy that names a list you have not created is a 400 policy_invalid. Compile and replay only warn, so you can draft the rules first.
Changes reach /v1/decide within about a minute, as cached copies expire.

Lists and blocklists

In the dashboard, lists are the Lists tab of Rules → Blocklists, next to the domain and address rules. Rules there act on every check immediately; lists only act when a policy rule references them. See Blocklists.

Address lists cannot be exported

Because only the hash of each address is stored, Sortance can tell you whether an address is on a list (/check hashes your question and looks it up) but cannot give the addresses back. GET /v1/lists/:name shows address entries as hmac: plus the first twelve characters of the hash — enough to tell two entries apart, nothing reversible. Keep your own copy of the source list.

Errors

Status	Code	When
`400`	`invalid_request`	Bad name, kind or mode, entries that are not an array, more than 1,000 entries, a check entry that is not valid for the list's kind, or a name already used by a list of a different kind.
`404`	`not_found`	No list by that name.