Lists and entries

Every check is held against two kinds of list: your own entries, which you add and remove, and the public lists, which the service downloads from their publishers. Both are on the console's Blocklists page; the public lists' schedules are on the Maintenance page.

Your own entries

List	An entry is	Matches
Address	A full mail address, name@example.com	That address only
Domain	A domain, example.com (a leading @ is ignored)	The domain and every subdomain of it, so example.com also holds mail.example.com
Client IP or range	An IPv4 or IPv6 address, or a range in CIDR form, 203.0.113.0/24	Every client IP in it
Exception of a public list	A domain, an IP or a range	Lets it through that one list; see Exceptions

Entries are lower-cased when they are stored. Each can carry a note of up to 300 characters, and the list shows who added it and when. Adding an entry that is already there changes nothing and says so.

Adding and removing entries needs an Operator or an Administrator. Each is a job, and the entry is checked against from the moment its job succeeds; see Every change is a job.

Entries from the deployment

Addresses and @domain entries set in the API container's environment (Blocklist__Entries__0 and on; see Installing Blocklist) are listed first and locked, with "set by the deployment" as their note. Nothing in the console or the API removes them: they change with the deployment.

Through the API

Method	Route	What it does
GET	/api/v1/entries	Every entry: the deployment's first, marked locked, then your own
POST	/api/v1/entries	Queues adding an entry; answers 202 with the job
DELETE	/api/v1/entries/{id}	Queues removing one; answers 202 with the job, or 404 when it is not on the list

An entry is {"kind": "...", "value": "...", "note": "..."}. The kinds are address, domain, ip, and a public list's own exception kind: GET /api/v1/sources gives it for each list as exceptionKind (fakefilter-exception, for example). A value that does not fit its kind is refused with 400 and a sentence: '...' is not an e-mail address., '...' is not a domain. or '...' is not an IP address or a CIDR range.

Exceptions

An exception lets something through one public list although that list holds it: a domain your customers really do use that a throwaway-domain list holds, or an address range of a partner on an IP list.

• An exception names a domain for a list of domains, and an IP address or range for a list of IPs.
• An excepted domain is excepted with its subdomains.
• It changes only the list it belongs to. Another list that holds the same domain still reports it, and your own entries are not affected.
• Each card on the Blocklists page shows how many exceptions its list has.

Add one on the Blocklists page with Exception of and the list's name.

The public lists

The service knows these public lists. Each has a card on the Blocklists page, which shows it only when your license covers it; see Licensing.

List	What it lists	Terms, as its card names them
disposable-email-domains	Throwaway mail domains. Also built into every release	CC0 1.0 (public domain)
FakeFilter	Throwaway mail domains	BSD 3-Clause
burner-email-providers	Throwaway mail domains	MIT
The hijacked network ranges list	IP ranges of hijacked and criminal networks, IPv4 and IPv6	Free of charge under its publisher's terms of use; see A list with a daily limit
Tor exit list	IP addresses of Tor exit nodes	CC0 1.0 (Tor Metrics exit-list data)

On the three throwaway-domain lists, a subdomain of a listed domain counts as listed.

Every card shows:

Line	What it is
Lists	What the list holds
Entries	How many domains, or IP addresses and ranges, are in force
Checked	Whether checks consult it: on or off
Source	The hosts it is downloaded from. These are the hosts the service needs to reach over HTTPS
License	Its license or terms, linked to the publisher's text, with a note where the terms restrict how it may be used
Credit	For a list whose terms ask for it, the copyright line and the date the publisher produced the file in force
Exceptions	How many exceptions you made for it
Refreshed	When the entries in force were downloaded, and by whom (a person, or schedule)

Refresh now on a card downloads the list again at once, for Administrators. The same lists, with their schedules and state, are GET /api/v1/sources.

Use each list as its terms allow

Each list is downloaded by your installation from its own publisher, and used only to answer your checks. Read the terms on each card before relying on a list, and follow the note where there is one: a list's terms may restrict how its data may be used or named.

The built-in list of throwaway domains

disposable-email-domains is also built into every release, so a new installation, or one without a license, still knows the common throwaway domains:

• Without a license that covers downloading it, the built-in copy is the one checked, and it is never downloaded. Its card says the list built into this release is in force.
• With one, the built-in copy is in force until the first good download, and the downloaded copy from then on.

It is the one public list that is shown and checked without a license. Switching it off on the Maintenance page stops it being checked either way.

A list with a daily limit

One IP list - the hijacked network ranges list - allows at most one download every 24 hours; its card in the console says so. The service holds to that:

• Refresh now and Run now are refused within 24 hours of its last good download, with the time it may be downloaded again.
• Its schedule cannot be hourly or every fewer than 24 hours; such a schedule is refused when saved.
• A scheduled run that falls inside the 24 hours waits for the first slot of its schedule after them, and Run at startup does not download it again inside them.

Its terms also ask that the copyright line of its file stays with the data, which its card shows as Credit, and that the list is used to refuse requests only: never named to your visitors or in promotion. Keep the reason of a check (which names the list) in your own logs and reports rather than showing it on your forms.

A download that fails

All the files a list is made of must download for a refresh to count. A refresh that cannot reach its host fails, and one whose file holds fewer entries than any sound copy of that list would is treated as a broken download, not a refresh. Either way the job fails with a sentence saying which file and why, and the entries in force are kept: a list is never emptied by a bad download.

A download may take up to a minute and be up to 32 MB. The service names itself in each request, as Antelao-Blocklist and its version, so a publisher can tell who is asking.

Schedules

The Maintenance page holds one task per public list your license covers: whether it is on, and when it is refreshed. Changing a task needs an Administrator.

Schedule	Runs
Daily (the default)	Once a day at the time given, 03:00 UTC unless changed
Weekly	On the day and at the time given
Hourly	Every hour at the minute given
Every N hours	Every 1 to 720 hours after the last run

• Times are entered and stored in UTC; the list on the page shows them in your own time zone.
• Run at startup also refreshes the list each time the service starts.
• A list that has never run is refreshed a minute after the service starts. A run that was missed while the service was down runs at once.
• Switching a task off also stops its list being checked, not only its refresh. Every list is on on a new installation.
• Run now refreshes the list straight away, as Refresh now does on its card.
• Blocklist__ScheduledRefresh=false in the API container's environment stops every scheduled refresh; lists are then refreshed only by hand.

A list's task is PUT /api/v1/sources/{key}, and a refresh by hand POST /api/v1/sources/{key}/refresh, where key is the list's key in GET /api/v1/sources. A refresh of a list that is already queued or running answers 409.

Every change is a job

Every change to the entries, the lists, the firewall and threat protection is a job. The API answers at once with 202 Accepted, the job in the body and its address in Location (/api/v1/jobs/{id}), and the service runs the job in the background. The console waits for it and shows how it ended; a program reads the job until it has ended.

{
  "id": "0193f6a2-...",
  "type": "list.add",
  "detail": "Add discard.example to the domain blocklist",
  "status": "Succeeded",
  "requestedBy": "jane",
  "createdUtc": "2026-11-05T09:12:03+00:00",
  "startedUtc": "2026-11-05T09:12:03+00:00",
  "finishedUtc": "2026-11-05T09:12:03+00:00",
  "result": "discard.example is on the domain blocklist.",
  "error": null
}

status	Meaning
Queued	Waiting its turn. Jobs run one at a time, in the order they were asked for
Running	Being done now
Succeeded	Done; result says what came of it
Failed	Not done; error says why, in a sentence
Interrupted	The service stopped while it ran, so its effect is unknown: check what it changed and ask again

A job still queued when the service stops runs at the next start. The scheduled refreshes are jobs too, queued by the service itself, so they show on the Jobs page beside everything people asked for. Finished jobs are kept for 90 days.

Method	Route	What it does
GET	/api/v1/jobs	The newest jobs first; ?take= up to 1,000, 200 by default
GET	/api/v1/jobs/{id}	One job and how it ended

Related

• Checks
• Licensing
• Reference