Suppression Lists

Note

The RelayPost dashboard uses a separate internal GraphQL API. This documentation covers the public REST API for external integrations.

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

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

JavaScript

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);

Python

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": "[email protected]",
      "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

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

JavaScript

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: "[email protected]",
    reason: "hard_bounce",
  }),
});

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

Python

import requests

response = requests.post(
    "https://relaypost.dev/api/v1/suppressions",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY",
    },
    json={
        "email": "[email protected]",
        "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": "[email protected]",
    "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

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

JavaScript

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);

Python

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
  }
}

Caution

Only remove addresses you’re confident should receive email. Re-sending to addresses that previously bounced or complained can harm your reputation.

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.