Skip to content
Start here

Bulk import account Email Sending suppressions

email_sending.suppressions.import_(SuppressionImportParams**kwargs) -> SuppressionImportResponse
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
ParametersExpand Collapse
account_id: str

Cloudflare account ID.

items: Iterable[Item]

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

email: str

The email address to suppress.

expires_at: Optional[Union[str, datetime, null]]

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

formatdate-time
note: Optional[str]

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

maxLength1000
scope: Optional[ItemScope]

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

One of the following:
class ItemScopeType: …
type: Literal["account"]

Blocks the recipient for every sending domain of the account.

class ItemScopeUnionMember1: …
type: Literal["sending_domain"]

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

value: str

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
class SuppressionImportResponse: …
deduplicated: int

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

errors: int

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

invalid: int

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

items: List[Item]

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

index: int

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

status: Literal["processed", "invalid", "error", "skipped"]

Outcome for this item.

One of the following:
"processed"
"invalid"
"error"
"skipped"
id: Optional[str]

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

formatuuid
email: Optional[str]

The submitted email address for this item.

formatemail
error: Optional[str]

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

scope: Optional[ItemScope]

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:
class ItemScopeType: …
type: Literal["account"]

Blocks the recipient for every sending domain of the account.

class ItemScopeUnionMember1: …
type: Literal["sending_domain"]

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

value: str

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

maxLength1024
processed: int

Number of items successfully created or promoted.

skipped: int

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

total: int

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

Bulk import account Email Sending suppressions

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.email_sending.suppressions.import_(
    account_id="12345678",
    items=[{
        "email": "user@example.com"
    }, {
        "email": "other@example.com"
    }],
)
print(response.invalid)
{
  "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
}