Suppression Lists

A suppression list contains email addresses that should not receive emails. RelayPost automatically checks the suppression list before every send and rejects emails to suppressed addresses.

Why suppression matters

Sending to addresses that have bounced or complained damages your sender reputation. ISPs track this — too many bounces or complaints and your emails start going to spam for everyone.

RelayPost automatically adds addresses to your suppression list when:

A hard bounce occurs (mailbox doesn’t exist)
A complaint is received (recipient marked your email as spam)

View suppression list

GET /api/v1/suppressions

curl "https://relaypost.dev/api/v1/suppressions?page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://relaypost.dev/api/v1/suppressions?page=1&limit=50",
  {
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  }
);

const result = await response.json();
console.log(result.data);
console.log(result.pagination);

import requests

response = requests.get(
    "https://relaypost.dev/api/v1/suppressions",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"page": 1, "limit": 50},
)

result = response.json()
print(result["data"])
print(result["pagination"])

Response (200)

{
  "data": [
    {
      "id": "sup_abc123",
      "email": "bounced@example.com",
      "reason": "hard_bounce",
      "source": "automatic",
      "created_at": "2025-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_count": 15,
    "total_pages": 1
  }
}

Add an address

POST /api/v1/suppressions

curl -X POST https://relaypost.dev/api/v1/suppressions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "email": "bounced@example.com",
    "reason": "hard_bounce"
  }'

const response = await fetch("https://relaypost.dev/api/v1/suppressions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    email: "bounced@example.com",
    reason: "hard_bounce",
  }),
});

const result = await response.json();
console.log(result.data.id);

import requests

response = requests.post(
    "https://relaypost.dev/api/v1/suppressions",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY",
    },
    json={
        "email": "bounced@example.com",
        "reason": "hard_bounce",
    },
)

result = response.json()
print(result["data"]["id"])

Request body

Field	Type	Required	Description
`email`	`string`	Yes	Email address to suppress
`reason`	`string`	Yes	One of: `hard_bounce`, `soft_bounce`, `complaint`, `unsubscribe`, `manual`

Response (201)

{
  "data": {
    "id": "sup_def456",
    "email": "bounced@example.com",
    "reason": "hard_bounce",
    "source": "manual",
    "created_at": "2025-01-15T10:30:00.000Z"
  }
}

Suppression reasons

Reason	Description
`hard_bounce`	Permanent delivery failure — mailbox doesn’t exist
`soft_bounce`	Temporary delivery failure — mailbox full, server down
`complaint`	Recipient reported the email as spam
`unsubscribe`	Recipient unsubscribed
`manual`	Manually added by you

Remove an address

DELETE /api/v1/suppressions/:id

If an address was suppressed by mistake, you can remove it:

curl -X DELETE https://relaypost.dev/api/v1/suppressions/sup_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://relaypost.dev/api/v1/suppressions/sup_abc123",
  {
    method: "DELETE",
    headers: { "Authorization": "Bearer YOUR_API_KEY" },
  }
);

const result = await response.json();
console.log(result.data);

import requests

response = requests.delete(
    "https://relaypost.dev/api/v1/suppressions/sup_abc123",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

result = response.json()
print(result["data"])

Response (200)

{
  "data": {
    "id": "sup_abc123",
    "deleted": true
  }
}

Bulk operations

For bulk import and export of suppression lists, use the RelayPost dashboard under Deliverability → Suppression Lists. The dashboard supports CSV import/export for managing large suppression lists.