Allowlists and Blocklists

Allow lists and block lists create exceptions to normal filtering.
Use a token with Allow/Block List Management permission for the relevant filter direction.
Read access permits listing entries; write access also permits creating, updating, and deleting them.

The published API includes incoming sender allow lists, incoming recipient and sender block lists, and outgoing sender block lists.
It also includes custom delivery allow/block rules and submission block rules.
Recipient allow lists and outgoing allow lists are not exposed by this customer-token API.

Use the collection URLs below.
For POST, send a non-empty JSON list with the scope fields in each object rather than adding the domain to the URL.

Incoming filter

Incoming list entries can be scoped by either a non-empty domain or a positive integer admin_id.
The examples use a domain.

Recipient block list

Use POST /api-v1/blocklisted_recipients/ to add a recipient blocklist entry.

Fields:

• local_part, required
• domain or admin_id, at least one required

Send the part before @ as local_part.

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"domain":"example.com","local_part":"reject"}]' \
  "$BASE_URL/api-v1/blocklisted_recipients/"

Sender block list

Use POST /api-v1/blocklisted_senders/ to add a sender blocklist entry.

Fields:

• address, required
• domain or admin_id, at least one required
• local_part, optional, to restrict the entry to a recipient
• sender_flag, optional, with values both_check, envelope, or header

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"domain":"example.com","address":"[email protected]","local_part":"","sender_flag":"both_check"}]' \
  "$BASE_URL/api-v1/blocklisted_senders/"

Restrict the block to [email protected] and check only the envelope sender:

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"domain":"example.com","address":"[email protected]","local_part":"sam","sender_flag":"envelope"}]' \
  "$BASE_URL/api-v1/blocklisted_senders/"

Sender allow list

Use POST /api-v1/allowlisted_senders/ to add a sender allowlist entry.
The fields and scope requirements are the same as for the incoming sender block list.

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"domain":"example.com","address":"[email protected]","local_part":"sam","sender_flag":"envelope"}]' \
  "$BASE_URL/api-v1/allowlisted_senders/"

Outgoing filter

Sender block list

Use POST /api-v1/blocklisted_outgoing_senders/ to add a sender blocklist entry for an outgoing authentication user.

All three fields are required:

• domain
• username
• address

The domain and username identify the outgoing authentication user.

curl -sS \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"domain":"example.com","address":"[email protected]","username":"outgoing"}]' \
  "$BASE_URL/api-v1/blocklisted_outgoing_senders/"

There are no outgoing sender or recipient allowlist endpoints in the published specifications.
For more specific outgoing blocking, use /api-v1/submission_blocklist_rules/.
It supports check types including s_addr for sender-address matching and rcpt_to for recipient matching.
A submission rule requires check_type, name, priority, and rule, plus either a non-empty domain and username pair or a positive admin_id.

List entries for a domain

Use GET with q to select fields and filter entries:

curl -sS --get \
  -H "HTTP-X-AUTH-TOKEN: $API_TOKEN" \
  --data-urlencode 'q={"fields":[{"field":"domain"},{"field":"address"},{"field":"local_part"},{"field":"sender_flag"}],"filters":[{"name":"domain","op":"==","val":"example.com"}]}' \
  "$BASE_URL/api-v1/blocklisted_senders/"

PUT updates entries selected by q with a JSON object.
DELETE removes entries selected by q and takes no request body.
Always use explicit filters with either method to avoid changing every accessible entry.