# List the address suppression list

`GET /api/v1/address/suppressions`

- Authentication: Secret API key as a bearer token
- Billing: Free.
- Group: Address

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 | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | The page to return. Default: 1. |

## Example request

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

## Responses

### 200 — One page of entries.

```json
{
    "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
    }
}
```

### 401 — The key is missing, malformed, or revoked.

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

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

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

## Error codes

- `UNAUTHENTICATED` — https://spaw.co/docs/errors/UNAUTHENTICATED
- `RATE_LIMITED` — https://spaw.co/docs/errors/RATE_LIMITED

---

Canonical page: https://spaw.co/docs/api/list-address-suppressions · OpenAPI document: https://spaw.co/openapi.json · All endpoints: https://spaw.co/docs/api