Skip to main content

​
Overview

The Suppression List automatically prevents you from sending emails to addresses that have:
  • Hard bounced - Invalid or non-existent email addresses
  • Spam complained - Recipients who marked your email as spam
  • Manually suppressed - Emails you’ve added to prevent sending
  • Unsubscribed - Recipients who unsubscribed from your emails
When you send an email, Unosend automatically checks the suppression list and filters out any suppressed recipients. This protects your sender reputation and deliverability.

​
Suppression Reasons

Hard Bounce

Email address doesn’t exist

Spam Complaint

Recipient reported spam

Manual

Added via API or dashboard

Unsubscribe

Recipient unsubscribed

​
List Suppressions

GET/v1/suppressions
Retrieve a paginated list of suppressed emails.

​
Query Parameters

​
limit
number
default:"50"
Number of results per page (max 100)
​
cursor
string
Pagination cursor from previous response
​
reason
string
Filter by reason: hard_bounce, spam_complaint, manual, unsubscribe
cURL
curl https://www.unosend.co/api/v1/suppressions?limit=10&reason=hard_bounce \
  -H "Authorization: Bearer un_your_api_key"

​
Response

200 OK
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "reason": "hard_bounce",
      "source_email_id": "email_abc123",
      "metadata": {
        "bounce_type": "Permanent",
        "bounce_subtype": "NoEmail"
      },
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "email": "[email protected]",
      "reason": "spam_complaint",
      "source_email_id": "email_def456",
      "metadata": {
        "feedback_type": "abuse"
      },
      "created_at": "2024-01-14T08:15:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "2024-01-14T08:15:00.000Z"
}

​
Add Suppression

POST/v1/suppressions
Manually add an email to your suppression list.

​
Request Body

​
email
string
required
Email address to suppress
​
reason
string
default:"manual"
Reason for suppression: hard_bounce, spam_complaint, manual, unsubscribe
cURL
curl -X POST https://www.unosend.co/api/v1/suppressions \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "reason": "manual"
  }'

​
Response

201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "reason": "manual",
  "created_at": "2024-01-15T10:30:00.000Z"
}

​
Get Suppression

GET/v1/suppressions/:id
Retrieve details of a specific suppression.

​
Path Parameters

​
id
string
required
Suppression ID
cURL
curl https://www.unosend.co/api/v1/suppressions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer un_your_api_key"

​
Response

200 OK
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "reason": "hard_bounce",
  "source_email_id": "email_abc123",
  "metadata": {
    "bounce_type": "Permanent",
    "bounce_subtype": "NoEmail",
    "diagnostic_code": "550 5.1.1 User unknown"
  },
  "created_at": "2024-01-15T10:30:00.000Z"
}

​
Remove Suppression

DELETE/v1/suppressions/:id
Remove an email from your suppression list. This allows you to send to this email again.
Be careful when removing hard bounce or spam complaint suppressions. Sending to these addresses again may harm your sender reputation.

​
Path Parameters

​
id
string
required
Suppression ID
cURL
curl -X DELETE https://www.unosend.co/api/v1/suppressions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer un_your_api_key"

​
Response

204 No Content

​
Remove by Email

DELETE/v1/suppressions?email=:email
Remove a suppression by email address instead of ID.
cURL
curl -X DELETE "https://www.unosend.co/api/v1/[email protected]" \
  -H "Authorization: Bearer un_your_api_key"

​
Response

204 No Content

​
Automatic Suppression

Unosend automatically adds emails to your suppression list when:
  1. Hard Bounce - When an email permanently bounces (invalid address, domain doesn’t exist)
  2. Spam Complaint - When a recipient marks your email as spam via feedback loop

​
How It Works

When you send an email via the API:
  1. Unosend checks the suppression list for all recipients
  2. Suppressed emails are automatically filtered out
  3. The email is sent only to non-suppressed recipients
  4. The API response includes a suppressed array showing filtered emails
{
  "id": "email_abc123",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "status": "sent",
  "suppressed": ["[email protected]", "[email protected]"]
}
If all recipients are suppressed, the API returns a 422 error to prevent sending empty emails.