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

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Query parameters

emailstring · emailOptional

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

Example: [e-mail]

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

400

Bad request - invalid parameters.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

429

Rate limit exceeded for the current account.

application/json

get

/api/suppressions

cURLNode.jsPHPPythonRuby.NETJava

# 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=[e-mail]' \
  -H 'Authorization: Bearer YOUR_API_KEY'

[
  {
    "id": "64d71bf3-1276-417b-86e1-8e66f138acfe",
    "type": "hard bounce",
    "created_at": "2025-01-15T10:30:00Z",
    "email": "[e-mail]",
    "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

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Body

application/json

emailstring · emailRequired

Email address to suppress

Example: [e-mail]

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

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

422

Validation errors

application/json

429

Rate limit exceeded for the current account.

application/json

post

/api/suppressions

cURL

curl -X POST https://mailtrap.io/api/suppressions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[e-mail]",
    "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": "[e-mail]",
    "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

HeaderAuthBearerAuth

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

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

delete

/api/suppressions/{suppression_id}

cURLNode.jsPHPPythonRuby.NETJava

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": "[e-mail]",
  "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
}