Manage suppressions

Manage recipients that Email Service must not contact. For suppression scope, triggers, and expiration rules, refer to Suppression lists.

Each suppression has a scope. An account suppression applies to every sending domain and subdomain in the account. A sending_domain suppression applies to one sending domain only. For details, refer to Suppression scope.

The table displays each recipient, reason, scope, creation time, and expiration. Never means the entry has no scheduled expiration.

Entries created in the dashboard have the manual reason. You cannot change the scope of an existing entry. To change it, delete the entry and add a new one.

You can paste addresses or upload .csv, .json, or .txt files. Supported file contents are:

• .csv or .txt: Put one entry on each line as <EMAIL_ADDRESS>, <EMAIL_ADDRESS>,<EXPIRATION_TIMESTAMP>, or <EMAIL_ADDRESS>,<EXPIRATION_TIMESTAMP>,<SCOPE>. Use an RFC 3339 ↗︎ timestamp and omit the header row. <SCOPE> is account or a sending domain.
• .json: Use an array of address strings or objects. Each object requires email and can include an RFC 3339 expires_at timestamp and a scope. scope is account, a sending domain, or a scope object such as { "type": "sending_domain", "value": "mail.myappexample.com" }.

To remove a mutable entry, select Delete for that recipient. Read-only entries do not provide a delete action.

Deleting an entry permits future delivery attempts. Verify that the recipient should receive mail before deleting an automatic suppression.

The account Email Sending suppression management REST API supports listing, adding, importing, updating, and deleting entries. Requests require an API token with the Email Sending: Edit permission.

API clients must use read_only to determine whether an entry is mutable. Do not infer mutability from the reason value.

Every entry in an API response includes a scope object:

{ "type": "account" }

{ "type": "sending_domain", "value": "mail.myappexample.com" }

To add an entry for one sending domain, include scope in the request body. If you omit scope, the API creates an account entry.

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email/sending/suppressions \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "user@example.net",
    "scope": { "type": "sending_domain", "value": "mail.myappexample.com" }
  }'

The API lowercases value and removes trailing dots. The value can contain letters, digits, ., -, and _, up to 253 characters. For an internationalized domain, use its ASCII (xn--) form. Other values return 400 with the invalid_scope_value error code.

The API does not check that your account sends from the domain. An entry for a domain that you do not send from never blocks mail.

Bulk imports accept the same optional scope on each item. The API removes duplicate items that have the same address and scope.

The list returns sending_domain entries first, then account entries. Entries are sorted newest first within each scope. To list one scope only, use these query parameters:

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email/sending/suppressions?scope_type=sending_domain&scope_value=mail.myappexample.com" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

A scope_value without scope_type=sending_domain returns 400 with the scope_value_requires_type error code.

To find every suppression for one address, use the email parameter. The results can include one account suppression and one sending_domain suppression for each sending domain.

You cannot change the scope of an existing entry. A PATCH request that includes scope returns 400 with the scope_immutable error code. To change the scope, delete the entry and create a new one.

Each address can have one active account suppression and one active sending_domain suppression for each sending domain. For page size, import, and rate limits, refer to Suppression list limits.