List the address suppression list

GET/api/v1/address/suppressions

authentication: Secret API key as a bearer token
billing: Free.

The account's postal suppression list, newest first, 100 entries per page. Your own delivery reports add an address with source feedback: moved or refused at once, returned on the second report with no later delivery. Imports arrive with source imported. Batch, bulk and monitor runs answer a suppressed address free, with valid false, reason suppressed and meta.suppressed true; a single lookup always runs fresh. Entries untouched for 90 days are re-checked rather than trusted: the lookup keeps the entry while your reports still stand behind it, and drops it once they do not.

The list is per account and is never read for anybody else.

Parameters

name	in	type	description
page	query	integer	The page to return. Default: 1.

Example request

curl https://spaw.co/api/v1/address/suppressions \
  -H "Authorization: Bearer sk_live_…"

const response = await fetch('https://spaw.co/api/v1/address/suppressions', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_…',
  },
});
const result = await response.json();

import requests

response = requests.get(
    'https://spaw.co/api/v1/address/suppressions',
    headers={'Authorization': 'Bearer sk_live_…'},
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/address/suppressions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…'],
]);
$result = json_decode(curl_exec($ch), true);

Responses

200One page of entries.

{
    "success": true,
    "data": {
        "suppressions": [
            {
                "id": 412,
                "address": "221B Baker Street, London NW1 6XE",
                "reason": "returned",
                "source": "feedback",
                "added_at": "2026-09-05T08:30:00+00:00"
            },
            {
                "id": 411,
                "address": "10 Downing Street, London, SW1A 2AA",
                "reason": "imported",
                "source": "imported",
                "added_at": "2026-09-04T17:02:11+00:00"
            }
        ]
    },
    "meta": {
        "page": 1,
        "per_page": 100,
        "total": 2
    }
}

401The key is missing, malformed, or revoked.

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

429Over 5 requests per second for the key. Retry after the limit resets.

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

Error codes

Failures answer { success: false, error: { code, message, request_id } }. Each code has its own page.

markdown version·openapi.json