Suppressions

The suppression list is the set of addresses mailstein will not email on your behalf. Three things put an address on it:

Why you want this

Continuing to mail an address that hard-bounced is the fastest way to lose a sending reputation. Mailbox providers treat a high bounce rate as the signature of a purchased list, and the penalty lands on your domain, not on the bad address.

Mailing someone who already reported you as spam is worse.

So suppression is enforced on send and cannot be bypassed. A message addressed to a suppressed recipient has that recipient removed; if every to recipient is suppressed, the message is recorded as SUPPRESSED and nothing is sent.

Importing from another provider

Bring the list with you. Do not start clean — a suppression list is the record of every mistake you have already paid for.

curl -X POST https://app.mailstein.com/api/v1/suppressions/bulk \
  -H "Authorization: Bearer $MAILSTEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["one@example.com","two@example.com"],"reason":"HARD_BOUNCE"}'

Up to 10,000 addresses a call. Duplicates and addresses already suppressed are both fine.

Checking before you send

curl https://app.mailstein.com/api/v1/suppressions/someone@example.com \
  -H "Authorization: Bearer $MAILSTEIN_API_KEY"

404 means not suppressed. You do not need to do this before sending — the send path checks anyway — but it is useful for showing a state in your own UI.

Removing an address

curl -X DELETE https://app.mailstein.com/api/v1/suppressions/someone@example.com \
  -H "Authorization: Bearer $MAILSTEIN_API_KEY"

Removing a MANUAL suppression is routine. Removing a HARD_BOUNCE means you are asserting the address exists after a provider told us it does not — only do that when you know something the bounce did not, such as the mailbox having been recreated.

Removing a COMPLAINT is almost never right. Someone told a mailbox provider your mail was spam. Emailing them again is how a domain gets blocked outright.

Bulk removal is a POST to /v1/suppressions/bulk/remove rather than a DELETE with a body — a body on DELETE is legal and dropped by enough proxies and HTTP clients to be unreliable.

Normalisation

Addresses are matched lower-cased and trimmed, the same way the send path normalises them. Suppressing Someone@Example.com blocks someone@example.com.