Suppressions

What gets suppressed

A hard bounce or a complaint puts the recipient's address on your account's suppression list. letr.dev then refuses to send to it: a send that names a suppressed address answers 422 recipient_suppressed and names the addresses. This protects your reputation and the shared sending reputation of every account.

Each entry has the email, a reason (bounced, complained or manual) and the time it was added.

List and remove

curl https://api.letr.dev/v1/suppressions \
  -H "Authorization: Bearer $LETR_API_KEY"

curl -X DELETE https://api.letr.dev/v1/suppressions/[email protected] \
  -H "Authorization: Bearer $LETR_API_KEY"

The list is newest first, 50 entries a page (limit up to 100). Pass the answer's nextCursor as cursor for the next page; it is null on the last. q finds the entries whose address contains it (3 to 200 characters). Listing needs read_only or full_access, removing full_access; a sending_access key gets 403 insufficient_permission. An address that is not on the list answers 404 not_found. The dashboard does both, and the API reference lists every field. Remove an address only when you know the reason is gone, for example a mailbox that exists again. Another bounce or complaint puts it back.

Add an address

curl https://api.letr.dev/v1/suppressions \
  -H "Authorization: Bearer $LETR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Adding needs full_access and puts the address on the list with reason manual. The answer is 201 with the new entry, or 200 with the existing one when the address is already on the list. An invalid address answers 422 invalid_email.

Import a list

curl https://api.letr.dev/v1/suppressions/import \
  -H "Authorization: Bearer $LETR_API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @suppressions.csv

Send one address per line, as CSV or plain text. A first line email is read as a header and skipped, and of a CSV line only the first column counts. An import holds at most 10'000 lines and 1 MB; above that the answer is 413 import_too_large. Imported addresses get reason manual, and addresses already on the list are counted, not changed. Importing needs full_access.

{ "added": 182, "alreadySuppressed": 4, "invalidCount": 1, "invalidLines": [57] }

invalidLines holds the line numbers (counted from 1) that held no valid address, at most the first 100.

Erase a recipient's address

When a recipient asks you to erase their data, remove their address from letr.dev:

curl -X DELETE https://api.letr.dev/v1/recipients/[email protected] \
  -H "Authorization: Bearer $LETR_API_KEY"

This replaces the address with erased in every email of your account (to, cc, bcc), in their events and in the webhook deliveries that name it, and deletes its suppression entry. The content of every email addressed to it or naming it in its subject or tags is deleted at once. A scheduled email that only names the address in its subject or tags is still sent at its time, and letr.dev's queue keeps it until then. The emails stay, and so do their counts toward your usage and your bounce and complaint rates, so erasure never changes your limits, billing or reputation. Add ?keepSuppression=true to keep the entry, so letr.dev keeps refusing to send to the address. The answer says how many emails the address was erased from: { "emails": 3, "suppressionRemoved": true }. It needs full_access, and cannot be undone.