Suppression Notices

The short version

Delivr sends your organization a Suppression Notice about once a week when people have opted out since your last notice. Each notice is a CSV of hashed emails you must stop using.
The same notice is emailed to your suppression contact (or your Owners and Admins). The API below lets you pull it instead of, or as well as, reading the email.
Two endpoints: list your notices, then download one notice's file as CSV or JSON.
Authenticate with your API key and secret, the same as every other data endpoint.

Cadence

Notices go out on a weekly cadence. A week with no new opt-outs produces no notice. Each notice covers the opt-outs recorded since the previous one, so processing every notice in order keeps your suppression list complete.

List your notices

curl "https://api.delivr.ai/api/v1/suppression-notices?limit=25&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Returns notices that were sent to your organization, newest first:

{
  "notices": [
    {
      "id": "3f6c1e2a-9b7d-4c1e-8a52-0d4e6f7a8b90",
      "created_at": "2026-10-13T21:00:00Z",
      "watermark_from": "2026-10-06T20:56:29Z",
      "watermark_to": "2026-10-13T20:50:00Z",
      "row_count": 412,
      "file_sha256": "9b1c...e04a",
      "has_file": true
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}

Field	Meaning
`watermark_from`, `watermark_to`	The notice covers opt-outs recorded after `watermark_from` and up to `watermark_to`.
`row_count`	Number of hashes in the file.
`file_sha256`	SHA-256 of the CSV file, the same value quoted in the notice email.
`has_file`	Whether the file can be downloaded. `false` only for notices sent before files were kept.

Page with limit (default 25, maximum 100) and offset. total is the number of sent notices.

Download a notice

curl "https://api.delivr.ai/api/v1/suppression-notices/NOTICE_ID/file" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -o suppression-notice.csv

By default the response is the exact CSV that was emailed (text/csv), with a one-column header sha256_lc_hem and one SHA-256 of a trimmed, lowercased email per line.

For JSON, send Accept: application/json or add ?format=json:

{
  "notice_id": "3f6c1e2a-9b7d-4c1e-8a52-0d4e6f7a8b90",
  "row_count": 412,
  "file_sha256": "9b1c...e04a",
  "sha256_lc_hem": ["0a1b...", "0c2d..."]
}

Both formats come from the same stored file, and the service checks it against file_sha256 before returning it. You can check it too: the SHA-256 of the CSV bytes equals file_sha256.

Errors

Status	When
`401`	Missing or invalid API key or secret.
`403`	The key is bound to a project outside its organization. A key bound to one of your projects reads your organization's notices.
`404`	No sent notice with that id in your organization, or the notice was sent before files were kept (`"file not retained for notices sent before <date>"`).
`400`	`format` is something other than `csv` or `json`.

In the dashboard, the same endpoints answer with your sign-in session and an organization_id query parameter.