Suppression

Download schema

List suppressed recipients, add addresses or domains yourself, and remove entries once they can be mailed again.

List all suppressions for the team

GET

https://api.lettermint.co/v1

/suppressions

Bearer

Returns current team, project, and route suppressions for the team.

List all suppressions for the team › query Parameters

page[size]

integer

The number of results that will be returned per page.

Default: 30

page[cursor]

string

The cursor to start the pagination from.

sort

string[]

Enum values:

value

-value

created_at

-created_at

reason

-reason

Default: ["-created_at"]

filter[scope]

string

Filter by scope (team, project, route)

filter[route_id]

string

Filter by route ID

filter[project_id]

string

Filter by project ID

filter[value]

string

Search by email/domain value (partial match)

filter[reason]

SuppressionReason · enum

Reason that the recipient is suppressed.

Enum values:

spam_complaint

hard_bounce

unsubscribe

manual

disposable_email

filter[startDate]

string

Filter suppressions created or updated on or after this ISO 8601 date or datetime

filter[endDate]

string

Filter suppressions created or updated on or before this ISO 8601 date or datetime

List all suppressions for the team › Responses

Paginated set of SuppressedRecipientData

SuppressedRecipientData[] · required

path

string | null · required

Base path for paginator generated URLs.

per_page

integer · min: 0 · required

Number of items shown per page.

next_cursor

string | null · required

The "cursor" that points to the next set of items.

next_page_url

string | null · uri · required

prev_cursor

string | null · required

The "cursor" that points to the previous set of items.

prev_page_url

string | null · uri · required

GET/suppressions

curl https://api.lettermint.co/v1/suppressions \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "id",
      "type": "email",
      "value": "value",
      "reason": "spam_complaint",
      "scope": "global",
      "applies_to": "all",
      "project_id": "project_id",
      "route_id": "route_id",
      "source_message": {
        "id": "id",
        "available": true,
        "subject": "subject",
        "created_at": "2024-08-25T15:00:00Z"
      },
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "path": "path",
  "per_page": 0,
  "next_cursor": "next_cursor",
  "next_page_url": "https://www.example.com/path/to/resource",
  "prev_cursor": "prev_cursor",
  "prev_page_url": "https://www.example.com/path/to/resource"
}

json

application/json

Add emails or domains to suppression list

POST

https://api.lettermint.co/v1

/suppressions

Bearer

Adds one email address or up to 1,000 addresses, and one domain or up to 1,000 domains. A domain blocks every address at that exact domain. An equal record is skipped. Manual suppressions block all mail unless applies_to is broadcast.

Add emails or domains to suppression list › Request Body

StoreSuppressionData

reason

SuppressionCreateReason · enum · required

Reason that the recipient is suppressed. The disposable_email reason is reserved for route policies.

Enum values:

spam_complaint

hard_bounce

unsubscribe

manual

scope

SuppressionCreateScope · enum · required

Where the suppression applies. The global and subscription_group scopes cannot be created through the API.

Enum values:

team

project

route

email

string | null · email · maxLength: 255

emails

array | null · minItems: 1 · maxItems: 1000

route_id

string | null · uuid

project_id

string | null · uuid

domain

string | null · maxLength: 255

Domain to suppress. Blocks every address at this exact domain, so subdomains need their own entry. Domains accept the manual and hard_bounce reasons

domains

array | null · minItems: 1 · maxItems: 1000

Domains to suppress. Each blocks every address at that exact domain, so subdomains need their own entry. Domains accept the manual and hard_bounce reasons

Add emails or domains to suppression list › Responses

Suppressions added

The outcome of adding addresses or domains to the suppression list.

SuppressionStoreResponse

message

string · required

Human-readable summary

SuppressionStoreResult · required

The addresses and domains that were added and those that were already suppressed.

POST/suppressions

curl https://api.lettermint.co/v1/suppressions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "email": "test@example.com",
  "emails": [
    "test@example.com"
  ],
  "reason": "spam_complaint",
  "scope": "team",
  "route_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "applies_to": "all",
  "domain": "domain",
  "domains": [
    "string"
  ]
}'

Example Request Body

{
  "email": "test@example.com",
  "emails": [
    "test@example.com"
  ],
  "reason": "spam_complaint",
  "scope": "team",
  "route_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "applies_to": "all",
  "domain": "domain",
  "domains": [
    "string"
  ]
}

json

Example Responses

{
  "message": "message",
  "data": {
    "created": [
      "string"
    ],
    "skipped": [
      "string"
    ]
  }
}

json

application/json

Remove suppression from suppression list

DELETE

https://api.lettermint.co/v1

/suppressions/{suppressionId}

Bearer

Deletes the selected suppression. Spam complaint suppressions stay active while Lettermint opens or reuses a support review ticket.

Remove suppression from suppression list › path Parameters

suppressionId

string · required

Remove suppression from suppression list › Responses

Suppression removed

Confirmation that a suppression was removed.

SuppressionDeletedResponse

success

boolean · const · required

Const value:

status

string · const · required

Const value: removed

message

string · required

Human-readable confirmation

confidence

number

Confidence of the automated removal assessment, when one ran

Message