Suppressions API
Manage suppressed contacts. Suppressed contacts are excluded from all future sends. Contacts can be suppressed manually or automatically (bounces, complaints, unsubscribes).
GET /v1/suppressions
List all suppressed contacts with pagination and optional filtering by reason.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Results per page (max 100) |
offset | integer | 0 | Offset for pagination |
reason | string | - | Filter by reason: bounce, complaint, manual |
cURL
curl https://api.yoursend.dev/v1/suppressions?reason=bounce \
-H "Authorization: Bearer ys_live_..."Response
{
"suppressions": [
{
"id": "con_abc123",
"email": "bounced@example.com",
"phone": null,
"name": "Jane Doe",
"reason": "bounce",
"suppressed_at": "2026-03-19T12:00:00Z",
"email_ok": false,
"sms_ok": false,
"tags": ["vip"],
"created_at": "2026-01-01T00:00:00Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}SDK
const { suppressions, total } = await ys.suppressions.list();GET /v1/suppressions/:id
Get detailed information about a suppressed contact.
cURL
curl https://api.yoursend.dev/v1/suppressions/con_abc123 \
-H "Authorization: Bearer ys_live_..."Response
{
"id": "con_abc123",
"email": "bounced@example.com",
"phone": null,
"name": "Jane Doe",
"reason": "bounce",
"suppressed_at": "2026-03-19T12:00:00Z",
"email_ok": false,
"sms_ok": false,
"voice_ok": true,
"whatsapp_ok": true,
"tags": ["vip"],
"metadata": { "plan": "pro" },
"total_sent": 42,
"created_at": "2026-01-01T00:00:00Z"
}POST /v1/suppressions
Manually suppress a contact. Identify the contact by ID, email, or phone number. Suppressed contacts will be skipped on all future sends.
| Field | Type | Required | Description |
|---|---|---|---|
contact_id | string | * | Contact ID (* one of contact_id, email, or phone required) |
email | string | * | Contact email address |
phone | string | * | Contact phone number |
reason | string | No | Reason for suppression (default: "manual") |
cURL
curl -X POST https://api.yoursend.dev/v1/suppressions \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"reason": "unsubscribed"
}'SDK
await ys.suppressions.create({
email: 'user@example.com',
reason: 'unsubscribed',
});DELETE /v1/suppressions/:id
Remove a suppression, re-enabling the contact for future sends. Channel preferences (email_ok, sms_ok) are restored to true.
cURL
curl -X DELETE https://api.yoursend.dev/v1/suppressions/con_abc123 \
-H "Authorization: Bearer ys_live_..."SDK
await ys.suppressions.delete('con_abc123');Suppression Object
| Field | Type | Description |
|---|---|---|
id | string | Contact ID |
email | string | null | Contact email |
phone | string | null | Contact phone |
name | string | null | Contact name |
reason | string | Suppression reason (bounce, complaint, manual, unsubscribed) |
suppressed_at | string | When the contact was suppressed |
email_ok | boolean | Email channel allowed (false when suppressed) |
sms_ok | boolean | SMS channel allowed (false when suppressed) |