API Reference

Email Sending

Suppressions

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Bulk import account Email Sending suppressions

client.EmailSending.Suppressions.Import(ctx, params) (*SuppressionImportResponse, error)

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

params SuppressionImportParams

AccountID param.Field[string]

Path param: Cloudflare account ID.

Items param.Field[[]SuppressionImportParamsItem]

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

Email string

The email address to suppress.

ExpiresAt TimeOptional

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

formatdate-time

Note stringOptional

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

maxLength1000

Scope SuppressionImportParamsItemsScopeOptional

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

One of the following:

type SuppressionImportParamsItemsScopeType struct{…}

Type SuppressionImportParamsItemsScopeTypeType

Blocks the recipient for every sending domain of the account.

type SuppressionImportParamsItemsScopeObject struct{…}

Type SuppressionImportParamsItemsScopeObjectType

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

type SuppressionImportResponse struct{…}

Deduplicated int64

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

Errors int64

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

Invalid int64

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

Items []SuppressionImportResponseItem

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

Index int64

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

Status SuppressionImportResponseItemsStatus

Outcome for this item.

One of the following:

const SuppressionImportResponseItemsStatusProcessed SuppressionImportResponseItemsStatus = "processed"

const SuppressionImportResponseItemsStatusInvalid SuppressionImportResponseItemsStatus = "invalid"

const SuppressionImportResponseItemsStatusError SuppressionImportResponseItemsStatus = "error"

const SuppressionImportResponseItemsStatusSkipped SuppressionImportResponseItemsStatus = "skipped"

ID stringOptional

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

formatuuid

Email stringOptional

The submitted email address for this item.

formatemail

Error stringOptional

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

Scope SuppressionImportResponseItemsScopeOptional

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 SuppressionImportResponseItemsScopeType struct{…}

Type SuppressionImportResponseItemsScopeTypeType

Blocks the recipient for every sending domain of the account.

type SuppressionImportResponseItemsScopeObject struct{…}

Type SuppressionImportResponseItemsScopeObjectType

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 int64

Number of items successfully created or promoted.

Skipped int64

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

Total int64

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

Bulk import account Email Sending suppressions

Go

HTTP

TypeScript

Python

Go

Terraform

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/email_sending"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.EmailSending.Suppressions.Import(context.TODO(), email_sending.SuppressionImportParams{
    AccountID: cloudflare.F("12345678"),
    Items: cloudflare.F([]email_sending.SuppressionImportParamsItem{email_sending.SuppressionImportParamsItem{
      Email: cloudflare.F("user@example.com"),
    }, email_sending.SuppressionImportParamsItem{
      Email: cloudflare.F("other@example.com"),
    }}),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Invalid)
}

200 example

{
  "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

200 example

{
  "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
}