Blacklist monitoring

Keep an eye on the addresses and domains you send from. Enroll a target once and we re-check it on a schedule; call the check endpoint when you want an answer right now — after requesting a delisting, say.

Method	Path	Purpose
POST	/v1/blacklist/targets	Add a domain or IP to watch.
GET	/v1/blacklist/targets	List your targets.
GET	/v1/blacklist/targets/{id}	Retrieve one target.
POST	/v1/blacklist/targets/{id}/check	Run a check right now.
GET	/v1/blacklist/targets/{id}/checks	Page through the check history.
DELETE	/v1/blacklist/targets/{id}	Remove a target and its history.

Every endpoint takes a secret key in the Authorization header — see Authentication.

The flow

1. Enroll a domain or IP with POST /v1/blacklist/targets. The first check runs on the next scheduled pass.
2. Poll GET /v1/blacklist/targets for anything whose status is listed.
3. Re-check on demand with POST /v1/blacklist/targets/{id}/check once you’ve asked a list to remove you, instead of waiting for the next pass.

Step 2 has an alternative worth taking: set a webhook on the target and we POST each listing and delisting to you as it happens, signed, instead of you polling for it. See Blacklist webhooks.

The target object

Field	Description
id	Use this in every other call on this page.
kind	domain, ipv4 or ipv6, decided when the target was added.
value	The normalized target, in the form the lists are queried with.
status	See the table below.
monitoring_enabled	Whether scheduled checks run. Pausing keeps the history.
listed_on	Stable blocklist ids currently listing the target, e.g. spamhaus_zen.
last_checked_at	When we last completed a check, or null if never.
next_check_at	When the next scheduled check is due.
webhook_configured	Whether transition webhooks are wired up for this target.

status	Meaning
pending	Added, not yet checked.
clean	The last check found no listing.
listed	On at least one blocklist. See listed_on.
unknown	The last check established nothing — every applicable list refused or failed.

unknown is not clean

A list that refuses to answer has told you nothing about your standing, so we never fold that into clean. Treat unknown as “check again”, not as “you’re fine” — a transient fault reported as clean is how you find out your mail is being rejected from your customers instead of from us.

Checks are scheduled by state, not on a fixed clock: a listed target is re-checked roughly hourly because somebody is usually waiting on a delisting, and everything else roughly every six hours.

See also

• Blacklist webhooks
• Authentication
• Errors