Suppressions
The Suppressions API allows you to manage the list of suppressed emails (bounces, complaints, unsubscribes).
Base URL
https://api.unsent.dev/v1/suppressionsFeatures
Suppression List
View all suppressed emails
Management
Manually add emails to the suppression list
Removal
Remove emails from the suppression list
Overview
The Suppressions API manages your email suppression list, which prevents emails from being sent to addresses that have bounced, complained, unsubscribed, or been manually blocked. This helps maintain sender reputation and comply with email best practices.
Suppression Reasons
| Reason | Description |
|---|---|
HARD_BOUNCE | Email address is invalid or mailbox doesn't exist |
COMPLAINT | Recipient marked email as spam |
MANUAL | Manually added to suppression list |
UNSUBSCRIBE | Recipient opted out from receiving emails |
Quick Start
List Suppressions
Retrieve a paginated list of suppressed emails with optional filtering.
# Basic usage
curl -X GET "https://api.unsent.dev/v1/suppressions?page=1&limit=20" \
-H "Authorization: Bearer your-api-key"Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | number | No | 1 | Page number (min: 1) |
limit | number | No | 20 | Results per page (min: 1, max: 100) |
search | string | No | - | Search filter for email addresses |
reason | string | No | - | Filter by reason: HARD_BOUNCE, COMPLAINT, MANUAL, or UNSUBSCRIBE |
Filter by Reason:
curl -X GET "https://api.unsent.dev/v1/suppressions?reason=COMPLAINT&limit=50" \
-H "Authorization: Bearer your-api-key"Search by Email:
curl -X GET "https://api.unsent.dev/v1/suppressions?search=example.com" \
-H "Authorization: Bearer your-api-key"Example Response:
{
"suppressions": [
{
"id": "supp_abc123",
"email": "bounced@example.com",
"reason": "HARD_BOUNCE",
"source": "smtp-server-1",
"createdAt": "2026-01-05T10:30:00.000Z"
},
{
"id": "supp_xyz789",
"email": "complaint@example.com",
"reason": "COMPLAINT",
"source": null,
"createdAt": "2026-01-04T14:20:00.000Z"
}
],
"total": 42
}Add a Suppression
Manually add an email to the suppression list.
curl -X POST https://api.unsent.dev/v1/suppressions \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"email": "bad@example.com",
"reason": "MANUAL",
"source": "customer-request"
}'Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to suppress (must be valid email format) |
reason | enum<Reason> | Yes | HARD_BOUNCE, COMPLAINT, MANUAL, UNSUBSCRIBE |
source | string | No | Optional source identifier for tracking |
Example Response:
{
"id": "supp_new123",
"email": "bad@example.com",
"reason": "MANUAL",
"source": "customer-request",
"createdAt": "2026-01-06T02:00:00.000Z"
}Delete a Suppression
Remove an email from the suppression list to allow sending again.
curl -X DELETE https://api.unsent.dev/v1/suppressions/email/bad@example.com \
-H "Authorization: Bearer your-api-key"Success Response (200):
{
"success": true
}Error Response (404):
{
"success": false,
"error": "Suppression not found"
}[!WARNING] Removing a suppression allows emails to be sent to that address again. Only do this if you're certain the issue is resolved (e.g., typo was fixed, recipient confirmed they want to receive emails).
Response Schema
Suppression Object
| Field | Type | Description |
|---|---|---|
id | string | Unique suppression identifier |
email | string | The suppressed email address |
reason | string | Why the email was suppressed |
source | string | null | Optional source identifier |
createdAt | string | ISO 8601 timestamp of when suppression was added |
Best Practices
Regular Monitoring
Periodically review your suppression list to identify patterns
Respect Unsubscribes
Never remove UNSUBSCRIBE suppressions without explicit consent
Clean Lists
Use the suppression list before importing contacts to maintain reputation