# Unsubscribe links

> A `POST /emails` send carries an opt-out only when it sets `topic_id`; campaigns inject a per-contact unsubscribe link and List-Unsubscribe header automatically.

How unsubscribe is handled depends on what you are sending: a **transactional** email, a **topic** email (`POST /emails` with `topic_id`), or a **campaign**.

| Send | Unsubscribe footer + `List-Unsubscribe` | What an opt-out does |
| --- | --- | --- |
| `POST /emails` **without** `topic_id` | No — never added | — |
| `POST /emails` **with** `topic_id` | Yes — added automatically | Removes that address from **that one topic** |
| Campaign | Yes — added automatically | Unsubscribes the contact from **all** your email |

## Transactional emails (sender-driven)

For `POST /emails` **without** a `topic_id`, SendPing does **not** add an unsubscribe link or `List-Unsubscribe` header. Transactional sends — receipts, password resets, confirmations — are sender-driven: if a message needs an unsubscribe mechanism, you add it to your own HTML. This keeps SendPing from injecting footers into messages where they don't belong.

> **Warning:** This is deliberate, not an omission. In SendPing an unsubscribe writes a [suppression](https://www.sendping.co/docs/emails/suppressions), and a suppressed address is skipped by **every** later send to it — password resets and receipts included. A footer on a password-reset email would let one stray click permanently break that recipient's own account recovery. Mark a send as subscription mail with `topic_id` and you get an opt-out that is scoped to the topic instead.

> **Note:** If a recipient should be able to opt out of a transactional email, include your own unsubscribe link in the `html` body. You can record the resulting opt-out as a [suppression](https://www.sendping.co/docs/emails/suppressions) so future sends to that address are skipped.

If you manage your own list and want a native one-click control on transactional mail, you can set the headers yourself via the [`headers`](https://www.sendping.co/docs/emails/headers) object — a `List-Unsubscribe` header pointing at your unsubscribe URL, plus `List-Unsubscribe-Post: List-Unsubscribe=One-Click` for [RFC 8058](https://datatracker.ietf.org/doc/html/rfc8058) one-click support.

```json
"headers": {
  "List-Unsubscribe": "<https://example.com/unsubscribe>",
  "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
}
```

When honoring a one-click request, your endpoint should accept a `POST` from that URL and return a blank `200 OK` or `202 Accepted` (and serve the normal unsubscribe page on `GET`). Ensure the recipient stops receiving email within **48 hours**. Mailbox providers such as Gmail and Yahoo require RFC 8058 compliance for bulk senders (more than 5,000 messages per day to their domains).

## Topic emails (automatic, scoped to the topic)

A `POST /emails` send that sets [`topic_id`](https://www.sendping.co/docs/topics/overview) is subscription mail: SendPing already skips recipients who have left that topic, so it also gives every recipient a way to leave. Both mechanisms are added automatically, exactly as they are for a campaign:

- An **unsubscribe footer** appended to the HTML body — unless your body already contains a SendPing unsubscribe link (see the merge tag below), in which case yours is left alone.
- An RFC 8058 **`List-Unsubscribe`** header with **`List-Unsubscribe-Post`**, so mailbox providers can render their native one-click unsubscribe control.

The link is minted **per recipient** from that recipient's own address, so every `to`, `cc`, and `bcc` address is delivered its own copy carrying only its own opt-out link — one recipient can never opt out another. The recipient does **not** have to be a contact: the opt-out is recorded against the address itself.

> **Note:** The scope of the opt-out is **that one topic**. It is not a suppression and not an audience-wide unsubscribe: the address keeps receiving your other topics, your campaigns, and your transactional mail. Only later sends carrying the same `topic_id` — from `POST /emails`, a scheduled send, or a campaign targeting that topic — skip it.

To place the link yourself instead of taking the default footer, include `{{{SENDPING_UNSUBSCRIBE_URL}}}` in your `html` (triple braces so the URL is inserted raw). SendPing substitutes each recipient's own URL and then skips the default footer, so you get one opt-out link, where you put it — not two.

Topic opt-outs are listed per topic in the dashboard under **Audiences → Topics → View opt-outs**, showing both contacts who opted out and addresses that used a topic unsubscribe link.

## Campaigns (automatic)

For campaigns (marketing email to an [audience](https://www.sendping.co/docs/audiences/overview)), SendPing injects unsubscribe handling automatically for every recipient:

- A **per-contact unsubscribe link** is appended to the message footer. Each recipient gets a unique link, so one click opts that individual out.
- An RFC 8058 **`List-Unsubscribe`** header (with `List-Unsubscribe-Post`) is emitted so mailbox providers can render a native one-click unsubscribe control.

When a contact unsubscribes through either path, they are added to your [suppression list](https://www.sendping.co/docs/emails/suppressions) and skipped on subsequent sends. The unsubscribe link is appended after any click-tracking rewrite, so the opt-out link is never wrapped by the click tracker.

> **Warning:** Don't set a `List-Unsubscribe` header by hand on a campaign — SendPing manages it. See [Custom headers](https://www.sendping.co/docs/emails/headers) for transactional header usage.