Bulk import account Email Sending suppressions

POST/accounts/{account_id}/email/sending/suppressions/bulk

Imports up to 1,000 Email Sending suppressions in one request. Each item applies to every sending domain of the account (default) or to one sending domain.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Path ParametersExpand Collapse

account_id: string

Cloudflare account ID.

Body ParametersJSONExpand Collapse

items: array of object { email, expires_at, note, scope }

Suppressions to import. Items with the same email address and scope are deduplicated before processing.

email: string

The email address to suppress.

expires_at: optional string

Expiration timestamp for the suppression. Omit or set to null for a permanent suppression that never expires.

formatdate-time

note: optional string

Advisory note for this suppression. Not enforced or validated beyond length.

maxLength1000

scope: optional object { type } or object { type, value }

Where the suppression applies. Omit for { "type": "account" }, which blocks the recipient for every sending domain of the account.

One of the following:

Type object { type }

type: "account"

Blocks the recipient for every sending domain of the account.

object { type, value }

type: "sending_domain"

Blocks the recipient only for mail whose envelope MAIL FROM uses value.

value: string

The sending domain to suppress for: the domain part of the envelope MAIL FROM. It is lowercased and trailing dots are removed. Internationalized domains must use the ASCII (punycode) form. Ownership is not checked; a domain the account does not send from never matches.

maxLength1024

ReturnsExpand Collapse

errors: array of unknown

messages: array of unknown

result: object { deduplicated, errors, invalid, 4 more }

deduplicated: number

Number of items dropped because their email address and scope repeated an earlier item in this request. Counted once and excluded from items.

errors: number

Number of items that failed to import due to an unexpected error.

invalid: number

Number of items with an invalid email address or sending domain.

items: array of object { index, status, id, 3 more }

Per-item results, in the same order as the request body.

index: number

Zero-based index of this item in the request body.

status: "processed" or "invalid" or "error" or "skipped"

Outcome for this item.

One of the following:

"processed"

"invalid"

"error"

"skipped"

id: optional string

The created or promoted suppression’s identifier. Present when status is processed.

formatuuid

email: optional string

The submitted email address for this item.

formatemail

error: optional string

Human-readable error message. Present when status is invalid, error, or skipped.

scope: optional object { type } or object { type, value }

Where the suppression applies: account for every sending domain of the account, or sending_domain for one envelope MAIL FROM domain.

One of the following:

Type object { type }

type: "account"

Blocks the recipient for every sending domain of the account.

object { type, value }

type: "sending_domain"

Blocks the recipient only for mail whose envelope MAIL FROM uses value.

value: string

The sending domain: the domain part of the envelope MAIL FROM, lowercase, without a trailing dot.

maxLength1024

processed: number

Number of items successfully created or promoted.

skipped: number

Number of items skipped because the existing suppression is not customer-managed (for example, a read-only policy suppression).

total: number

Total number of items in the request body, including duplicates.

success: boolean

Bulk import account Email Sending suppressions

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/email/sending/suppressions/bulk \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "items": [
            {
              "email": "user@example.com"
            },
            {
              "email": "other@example.com",
              "expires_at": "2027-01-01T00:00:00Z",
              "note": "Imported from CRM",
              "scope": {
                "type": "sending_domain",
                "value": "mail.example.com"
              }
            }
          ]
        }'

{
  "errors": [
    {}
  ],
  "messages": [
    {}
  ],
  "result": {
    "deduplicated": 1,
    "errors": 0,
    "invalid": 1,
    "items": [
      {
        "index": 0,
        "status": "processed",
        "id": "396a5436-d4b0-42a6-b3fc-48e8fa522321",
        "email": "user@example.com",
        "error": "Invalid email",
        "scope": {
          "type": "sending_domain",
          "value": "mail.example.com"
        }
      }
    ],
    "processed": 2,
    "skipped": 0,
    "total": 4
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {}
  ],
  "messages": [
    {}
  ],
  "result": {
    "deduplicated": 1,
    "errors": 0,
    "invalid": 1,
    "items": [
      {
        "index": 0,
        "status": "processed",
        "id": "396a5436-d4b0-42a6-b3fc-48e8fa522321",
        "email": "user@example.com",
        "error": "Invalid email",
        "scope": {
          "type": "sending_domain",
          "value": "mail.example.com"
        }
      }
    ],
    "processed": 2,
    "skipped": 0,
    "total": 4
  },
  "success": true
}