Skip to content

Update suppressions API spec #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
VladimirTaytor wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update suppressions API spec #32

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
81c8394
Update suppresion API docs
VladimirTaytor Apr 27, 2026
e4e8041
Use 'type' for suppression create request body
VladimirTaytor May 5, 2026
112e8f5
Merge origin/main into update-suppressions-api
VladimirTaytor May 5, 2026
6d05852
Fix linter
VladimirTaytor May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 140 additions & 23 deletions specs/email-sending.openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -916,9 +916,11 @@ paths:
get:
summary: List suppressions
description: |
List and search suppressed email addresses. Returns up to 1000 suppressions per request.
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.
operationId: getSuppressions
tags:
- suppressions
Expand Down Expand Up @@ -1072,25 +1074,32 @@ paths:
- $ref: '#/components/parameters/account_id'
- name: email
in: query
description: Search for specific email address
description: Filter suppressions by exact email address (case-insensitive).
schema:
type: string
format: email
example: suppressed@example.com
- description: Search emails suppressed after this timestamp
name: start_time
- name: start_time
in: query
description: Filter suppressions created at or after this timestamp (ISO 8601 format).
schema:
type: string
format: date-time
example: '2025-01-01T00:00:00Z'
- description: Search emails suppressed after this timestamp
name: end_time
- name: end_time
in: query
description: Filter suppressions created at or before this timestamp (ISO 8601 format).
schema:
type: string
format: date-time
example: '2025-12-31T23:59:59Z'
- name: last_id
in: query
description: The suppression UUID from the last record of the previous response. Returns records after this suppression, enabling cursor-based pagination through large lists.
schema:
type: string
format: uuid
example: 64d71bf3-1276-417b-86e1-8e66f138acfe
responses:
'200':
$ref: '#/components/responses/GetSuppressionsResponse'
Expand All @@ -1102,10 +1111,82 @@ paths:
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/LIMIT_EXCEEDED'
post:
summary: Create suppression
description: |
Add an email address to the suppression list. Suppressed addresses will not receive any emails from your account.

{% hint style="warning" %}
This endpoint requires admin-level access.
{% endhint %}

Rate limit: 10 requests per minute per account.
operationId: createSuppression
tags:
- suppressions
x-codeSamples:
- lang: shell
label: 'cURL'
source: |
curl -X POST https://mailtrap.io/api/accounts/{account_id}/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"
}'
Comment thread
VladimirTaytor marked this conversation as resolved.
parameters:
- $ref: '#/components/parameters/account_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email, domain_id, sending_stream]
properties:
email:
type: string
format: email
description: Email address to suppress
example: user@example.com
domain_id:
type: integer
description: ID of the sending domain to suppress this email for
example: 12345
sending_stream:
type: string
enum: [transactional, bulk]
description: The sending stream to suppress this email for
example: transactional
type:
type: string
enum: [hard bounce, unsubscription, spam complaint, manual import]
default: manual import
description: Reason for the suppression. Defaults to "manual import" if omitted.
example: manual import
responses:
'201':
$ref: '#/components/responses/CreateSuppressionResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/LIMIT_EXCEEDED'
/api/accounts/{account_id}/suppressions/{suppression_id}:
delete:
summary: Delete suppression
description: Remove an email from the suppression list to allow sending again
description: |
Remove an email from the suppression list to allow sending again.

{% hint style="warning" %}
This endpoint requires admin-level access.
{% endhint %}
operationId: deleteSuppression
tags:
- suppressions
Expand Down Expand Up @@ -1963,10 +2044,11 @@ components:
name: suppression_id
in: path
required: true
description: Suppression ID
description: The suppression UUID
schema:
type: integer
example: 1
type: string
format: uuid
example: 64d71bf3-1276-417b-86e1-8e66f138acfe

sending_message_id:
name: sending_message_id
Expand Down Expand Up @@ -2425,19 +2507,51 @@ components:
type: object
properties:
id:
type: integer
example: 1
type: string
format: uuid
description: The suppression UUID
example: 64d71bf3-1276-417b-86e1-8e66f138acfe
type:
type: string
enum: [hard bounce, unsubscription, spam complaint, manual import]
description: Reason for the suppression
example: hard bounce
created_at:
type: string
format: date-time
example: '2025-01-15T10:30:00Z'
email:
type: string
format: email
example: suppressed@example.com
reason:
Copy link
Copy Markdown
Contributor Author

@VladimirTaytor VladimirTaytor May 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually it was a mistake we never had reason here filed should be named type and all SDKs support type

type: string
enum: [bounce, complaint, unsubscribe, manual]
example: bounce
created_at:
sending_stream:
type: string
enum: [transactional, bulk, any]
example: transactional
domain_name:
type: [string, 'null']
example: example.com
message_bounce_category:
type: [string, 'null']
message_category:
type: [string, 'null']
message_client_ip:
type: [string, 'null']
message_created_at:
type: [string, 'null']
format: date-time
message_esp_response:
type: [string, 'null']
message_esp_server_type:
type: [string, 'null']
message_outgoing_ip:
type: [string, 'null']
message_recipient_mx_name:
type: [string, 'null']
message_sender_email:
type: [string, 'null']
message_subject:
type: [string, 'null']

Webhook:
type: object
Expand Down Expand Up @@ -3453,14 +3567,17 @@ components:

DeleteSuppressionResponse:
description: Suppression deleted
content:
application/json:
schema:
$ref: '#/components/schemas/Suppression'

CreateSuppressionResponse:
description: Suppression created
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Suppression removed successfully
data:
$ref: '#/components/schemas/Suppression'
Comment thread
VladimirTaytor marked this conversation as resolved.
Loading