Ctrlk
ProductPricingContact supportOpen app
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Suppressions

Manage suppressed email addresses

Control which email addresses should not receive emails from your account.

List suppressions

get

List and search suppressed email addresses. Returns up to 1000 suppressions per request. Use last_id for cursor-based pagination through large lists.

Suppressed addresses will not receive any emails from your account.

Rate limit: 10 requests per minute per account.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Query parameters
emailstring · emailOptional

Filter suppressions by exact email address (case-insensitive).

Example: suppressed@example.com
start_timestring · date-timeOptional

Filter suppressions created at or after this timestamp (ISO 8601 format).

Example: 2025-01-01T00:00:00Z
end_timestring · date-timeOptional

Filter suppressions created at or before this timestamp (ISO 8601 format).

Example: 2025-12-31T23:59:59Z
last_idstring · uuidOptional

The suppression UUID from the last record of the previous response. Returns records after this suppression, enabling cursor-based pagination through large lists.

Example: 64d71bf3-1276-417b-86e1-8e66f138acfe
Responses
200

List of suppressions

application/json
idstring · uuidOptional

The suppression UUID

Example: 64d71bf3-1276-417b-86e1-8e66f138acfe
typestring · enumOptional

Reason for the suppression

Example: hard bouncePossible values:
created_atstring · date-timeOptionalExample: 2025-01-15T10:30:00Z
emailstring · emailOptionalExample: suppressed@example.com
sending_streamstring · enumOptionalExample: transactionalPossible values:
domain_namestring · nullableOptionalExample: example.com
message_bounce_categorystring · nullableOptional
message_categorystring · nullableOptional
message_client_ipstring · nullableOptional
message_created_atstring · nullableOptional
message_esp_responsestring · nullableOptional
message_esp_server_typestring · nullableOptional
message_outgoing_ipstring · nullableOptional
message_recipient_mx_namestring · nullableOptional
message_sender_emailstring · nullableOptional
message_subjectstring · nullableOptional
get/api/suppressions
# Get all suppressions
curl -X GET https://mailtrap.io/api/suppressions \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Search for specific email
curl -X GET 'https://mailtrap.io/api/suppressions?email=suppressed@example.com' \
  -H 'Authorization: Bearer YOUR_API_KEY'

[
  {
    "id": "64d71bf3-1276-417b-86e1-8e66f138acfe",
    "type": "hard bounce",
    "created_at": "2025-01-15T10:30:00Z",
    "email": "suppressed@example.com",
    "sending_stream": "transactional",
    "domain_name": "example.com",
    "message_bounce_category": null,
    "message_category": null,
    "message_client_ip": null,
    "message_created_at": null,
    "message_esp_response": null,
    "message_esp_server_type": null,
    "message_outgoing_ip": null,
    "message_recipient_mx_name": null,
    "message_sender_email": null,
    "message_subject": null
  }
]

Create suppression

post

Add an email address to the suppression list. Suppressed addresses will not receive any emails from your account.

This endpoint requires admin-level access.

Rate limit: 10 requests per minute per account.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Body
emailstring · emailRequired

Email address to suppress

Example: user@example.com
domain_idintegerRequired

ID of the domain to suppress this email for

Example: 12345
sending_streamstring · enumRequired

The sending stream to suppress this email for

Example: transactionalPossible values:
typestring · enumOptional

Reason for the suppression. Defaults to "manual import" if omitted.

Default: manual importExample: manual importPossible values:
Responses
201

Suppression created

application/json
post/api/suppressions
curl -X POST https://mailtrap.io/api/suppressions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "domain_id": 12345,
    "sending_stream": "transactional",
    "type": "manual import"
  }'

{
  "data": {
    "id": "64d71bf3-1276-417b-86e1-8e66f138acfe",
    "type": "hard bounce",
    "created_at": "2025-01-15T10:30:00Z",
    "email": "suppressed@example.com",
    "sending_stream": "transactional",
    "domain_name": "example.com",
    "message_bounce_category": null,
    "message_category": null,
    "message_client_ip": null,
    "message_created_at": null,
    "message_esp_response": null,
    "message_esp_server_type": null,
    "message_outgoing_ip": null,
    "message_recipient_mx_name": null,
    "message_sender_email": null,
    "message_subject": null
  }
}

Delete suppression

delete

Remove an email from the suppression list to allow sending again.

This endpoint requires admin-level access.

Authorizations
Api-TokenstringRequired

API token in Api-Token header

Path parameters
suppression_idstring · uuidRequired

The suppression UUID

Example: 64d71bf3-1276-417b-86e1-8e66f138acfe
Responses
200

Suppression deleted

application/json
idstring · uuidOptional

The suppression UUID

Example: 64d71bf3-1276-417b-86e1-8e66f138acfe
typestring · enumOptional

Reason for the suppression

Example: hard bouncePossible values:
created_atstring · date-timeOptionalExample: 2025-01-15T10:30:00Z
emailstring · emailOptionalExample: suppressed@example.com
sending_streamstring · enumOptionalExample: transactionalPossible values:
domain_namestring · nullableOptionalExample: example.com
message_bounce_categorystring · nullableOptional
message_categorystring · nullableOptional
message_client_ipstring · nullableOptional
message_created_atstring · nullableOptional
message_esp_responsestring · nullableOptional
message_esp_server_typestring · nullableOptional
message_outgoing_ipstring · nullableOptional
message_recipient_mx_namestring · nullableOptional
message_sender_emailstring · nullableOptional
message_subjectstring · nullableOptional
delete/api/suppressions/{suppression_id}
curl -X DELETE https://mailtrap.io/api/suppressions/{suppression_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "64d71bf3-1276-417b-86e1-8e66f138acfe",
  "type": "hard bounce",
  "created_at": "2025-01-15T10:30:00Z",
  "email": "suppressed@example.com",
  "sending_stream": "transactional",
  "domain_name": "example.com",
  "message_bounce_category": null,
  "message_category": null,
  "message_client_ip": null,
  "message_created_at": null,
  "message_esp_response": null,
  "message_esp_server_type": null,
  "message_outgoing_ip": null,
  "message_recipient_mx_name": null,
  "message_sender_email": null,
  "message_subject": null
}
PreviousDomains
NextTracking Opt-Outs

Last updated

Was this helpful?