Skip to content
spacepostdocs

Unsubscribe

Every broadcast email gets two unsubscribe mechanisms, with nothing for you to configure.

Section titled “The link”

{{{SPACEPOST_UNSUBSCRIBE_URL}}} expands to a URL like https://app.spacepost.dev/u/<token>. The token is signed per contact, so it cannot be guessed or changed.

  • Opening the link shows a confirmation page (“Stop receiving emails at j***@example.com?”). A GET never unsubscribes anyone, so link scanners and mail security tools do not unsubscribe people by accident. The address is masked on the page.
  • Pressing the button sends a POST that sets the contact’s unsubscribed flag to true.

If your HTML has no unsubscribe placeholder, a footer with a link is appended for you (and a plain-text line in the text part). Put the placeholder in your own design to control the wording and position.

The headers

Section titled “The headers”

SpacePost adds the headers Gmail and Yahoo require for bulk mail:

List-Unsubscribe: <https://app.spacepost.dev/u/<token>>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

With these, Gmail and Apple Mail show a native Unsubscribe button next to the sender. A click makes the mail client POST to the URL, which unsubscribes the contact immediately, as specified in RFC 8058. This is much better for your reputation than recipients using the spam button.

What happens after

Section titled “What happens after”
  • The contact is skipped by all future broadcasts to that audience.
  • Nothing is sent to your webhooks for unsubscribes at the moment; read the unsubscribed flag from GET /audiences/{id}/contacts/{idOrEmail} or list contacts to sync your own database.
  • To resubscribe someone who asks, PATCH the contact with { "unsubscribed": false }. Only do this on an explicit request.

Transactional email

Section titled “Transactional email”

Unsubscribe links are for marketing mail. Password resets, receipts and security notices do not need one. If you send marketing content through POST /emails, add the headers yourself (see Custom headers) and handle opt-outs on your side, or use broadcasts.