Suppressions & Unsubscribes

When a recipient unsubscribes from your marketing email — by clicking the footer link or via a one-click request from their email client — Altermail records a suppression for that address scoped to your account only. Future category: "marketing" sends to that address are skipped automatically; see Quota & Billing for how suppressed sends are billed. Transactional email always bypasses this check.

This is separate from the unsubscribe link itself

You don't need to build anything for the unsubscribe click to work — Altermail injects the List-Unsubscribe header and footer link automatically on every marketing send, and handles the click/one-click request for you. The endpoints below are for a fully self-hosted opt-out/opt-in experience instead: run your own unsubscribe page and preference center on your website, and wrap these calls behind it so end users never see an Altermail-branded link at all.

List suppressed addresses

GET/v1/user/email/suppressions

Query params: page (default 1), limit (default 50, max 100).

{
  "suppressions": [
    { "email": "user@example.com", "suppressedAt": 1758901234000, "source": "one_click" }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "hasMore": false }
}

Suppress an address

POST/v1/user/email/suppressions

Body: { "email": "user@example.com" }. Wrap this behind your own website's unsubscribe page so end users can opt out without ever seeing an Altermail-branded link. Response 200: { "message": "user@example.com has been unsubscribed." }

curl -X POST "https://api.altermail-console.com.ng/v1/user/email/suppressions" \
  -H "token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

Re-subscribe an address

DELETE/v1/user/email/suppressions/:email

Call this from your own backend when a user opts back in — from your account settings page, a support request, or a re-engagement flow. Response 200: { "message": "user@example.com has been re-subscribed." } — or 404 if that address had no unsubscribe on record.

curl -X DELETE "https://api.altermail-console.com.ng/v1/user/email/suppressions/user@example.com" \
  -H "token: YOUR_API_TOKEN"

Scope and safety

Property	Behaviour
Authentication	All three endpoints require your account's Bearer token in the token header, same as every other API call.
Scope	Every read/write is scoped to your own account automatically — there is no field to target another account's suppression list, so you can only manage unsubscribes for your own recipients.
Hard bounces	These endpoints only ever touch unsubscribe records. A hard-bounced address (which is suppressed platform-wide, not per-account) is never affected by re-subscribing — Altermail still won't deliver to a confirmed-dead address.

!Re-subscribing an address only removes the suppression record — it does not verify the person actually wants your email again. Only call the re-subscribe endpoint in response to an explicit opt-in action on your side (e.g. a checked box, a confirmed request), the same way you would before adding anyone to a mailing list.