Skip to content

Questions · Published 2026-09-27 · Updated 2026-10-21 · AgentiSend

How do I add an unsubscribe link to my emails?

Add an unsubscribe link to your emails by naming a topic_id on POST /emails, by sending through POST /broadcasts, or by setting List-Unsubscribe yourself from a verified domain; all three put the RFC 8058 one-click unsubscribe headers on the message. Transactional emails such as receipts and sign-in codes do not need one.

Add an unsubscribe link to your emails by naming a topic_id on POST /emails, or by sending the message as a broadcast with POST /broadcasts followed by POST /broadcasts/{id}/send. Both add the RFC 8058 one-click headers, List-Unsubscribe and List-Unsubscribe-Post, so a mailbox that supports them can offer its own unsubscribe control and a click on it is recorded here. Create the topic first with POST /topics. If you already run your own unsubscribe page, set the two headers yourself instead (below). Transactional emails, such as receipts and sign-in codes, do not need an unsubscribe link, and sending them without one is correct.

Topics

POST /topics creates one kind of mail a person can leave. Its summary: "Create a subscription topic. default_subscribed=false makes it opt-in: silence means no." Naming that topic's id as topic_id on POST /emails does three things at once: it screens every recipient against what they have said about the topic, it sends on the marketing stream, and it adds the one-click headers pointing at an unsubscribe for that topic alone. The headers are minted when the send has one recipient and that recipient is a contact; a topic send to several recipients still goes, without them, because a header that unsubscribes the wrong person is worse than none. When every recipient has opted out, the send is refused with suppressed_recipient.

curl -sS -X POST https://api.agentisend.com/topics \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"example"}'
201
{
  "created_at": "2026-09-04T09:14:00.000Z",
  "default_subscribed": false,
  "default_subscription": "opt_in",
  "description": "example",
  "id": "9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42",
  "name": "example",
  "object": "topic",
  "updated_at": "2026-09-04T09:14:00.000Z",
  "visibility": "public"
}
Response

PATCH /contacts/{id}/topics records what a contact said; its summary is "Record this contact’s answer for one or more topics. Answers are absolute — nothing is inferred from what is left out." GET /contacts/{id}/topics reads it back, and its summary adds that "A topic they never answered reports the topic default, and says so."

Broadcasts

A broadcast is one message to one segment. POST /broadcasts drafts it and POST /broadcasts/{id}/send sends it, and every message carries the one-click headers for its contact. The lint rule below points here: its fix is "Set List-Unsubscribe and List-Unsubscribe-Post in headers (from a verified domain), or send via POST /broadcasts or with a topic_id, which add them for you." A contact who has unsubscribed is skipped, and the broadcast's detail page names the rule that skipped them. Broadcasts has the rest.

When your application already records unsubscribes, pass the headers on a plain POST /emails from a domain you have verified here. If that domain is not verified, the refusal is domain_not_verified and the message names the header. The onboarding sender cannot carry them: that refusal is invalid_parameter.

"headers": {
  "List-Unsubscribe": "<https://acme.com/unsubscribe/abc>, <mailto:unsubscribe@acme.com>",
  "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
}

List-Unsubscribe takes one or two links in angle brackets, https or mailto; an http link is refused. List-Unsubscribe-Post must be exactly List-Unsubscribe=One-Click and needs an https link beside it, because a mailbox's one-click unsubscribe posts to that link. Your page then has to honour the unsubscribe, since the click goes to you and not to us. On a send with a topic_id, and on a broadcast, our own pair goes out instead, and the response's warnings says so.

Check before you send

POST /emails/lint runs without sending and reports no_unsubscribe_bulk when the to list is long enough to read as bulk and there is no List-Unsubscribe header. The finding's message is "Bulk send without one-click unsubscribe — Gmail/Yahoo require it and filter without it." and its fix is "Set List-Unsubscribe and List-Unsubscribe-Post in headers (from a verified domain), or send via POST /broadcasts or with a topic_id, which add them for you."

What an unsubscribe does

A one-click unsubscribe lands the address on the suppression list as a row scoped to marketing mail, so receipts and password resets to the same person still send. An API key cannot lift that row; How do I remove an address from the suppression list? says who can. Audience covers contacts, segments and topics in the console.

Next