Skip to main content
Every broadcast message gives the recipient a way to unsubscribe, and Nuntly skips recipients who did. This page explains the link, what an unsubscribe changes, and how it differs from the suppression list.

​
What every message contains

Nuntly adds two things to every broadcast message.
  • A visible link. You place the unsubscribe token in your template, and Nuntly renders it as the unsubscribe link of the recipient.
  • Unsubscribe headers. The message carries a List-Unsubscribe header with the same link, and a List-Unsubscribe-Post header with the value List-Unsubscribe=One-Click. Mail clients that implement RFC 8058 use them to offer one-click unsubscribe.
The link is unique to each recipient address. The same address receives the same link in every broadcast that your organization sends to it.

​
The unsubscribe token

Write {{system.unsubscribeUrl}} where the link should appear in your template, for example in the href of an unsubscribe link in the HTML.
  • Valid in the HTML body and the text body. Never in the subject.
  • The HTML body of every template version must contain it. When a version has a text body, the text body must contain it too.
  • Nuntly checks this when you publish a version. A version without it is refused with a 422 response and the code template_version_unsubscribe_placeholder_missing.
  • Nuntly checks it again when you send a broadcast.
  • The token is case sensitive. Extra whitespace right inside the braces, such as {{ system.unsubscribeUrl }}, is tolerated.
{{unsubscribeUrl}}, the flat form without the system. prefix, is not a recognized token. It is refused like any other unsupported construct if you try to publish it. Broadcast is pre-GA with no customers, so nothing depends on the old form; if a template version still carries it, replace it with {{system.unsubscribeUrl}} and publish a new version. Nuntly only renders the token at delivery. It never adds a link to content that lacks one, which is why the check happens before sending. The link points to the address /u/ followed by an opaque token on the dashboard host of Nuntly. The token is random and is not derived from the email address. Opening the link never unsubscribes anyone. Only an explicit confirmation or a one-click request does, because link scanners and mail previews open links automatically. The request that unsubscribes always answers 200, whether or not the link is still active, so a caller cannot use the response to find out whether an address is valid. Repeated requests on one link are rate limited and answer 429. The link keeps working after your organization is no longer enabled for Broadcast, and after the send records of the broadcast expire under your data retention window. Each delivery to an address renews the link of that address. The link stays active for 365 days after the last broadcast delivered to the address. After that, or after you delete the contact, the link shows a page saying it is no longer active and unsubscribes nobody.

​
What an unsubscribe changes

An unsubscribe records an opt-out for your organization and the email address.
  • The address is skipped in every later broadcast of your organization, whatever the segment or topic. A broadcast that is already running honors it for the pages of contacts it has not processed yet.
  • Transactional emails are not affected. A recipient who unsubscribes from a newsletter still receives a password reset.
  • The address is not added to the suppression list.
  • The opt-out is tied to the address. It stays when you delete the contact, create it again, or add the address to your list from another source.
  • Reading the topics of the contact reports unsubscribed for every topic, with the source platform_opt_out.
  • The API has no operation to remove an opt-out.

​
Topic subscriptions

A topic subscription is a separate setting that you manage through the API. The unsubscribe link does not change it. Use topics to record preferences that you collect yourself, such as a contact who wants one newsletter but not another. Broadcasts to that topic skip the contacts that are unsubscribed from it. See Topics.

​
Suppression list

The suppression list holds addresses that Nuntly will not send to for your organization. Nuntly adds an address automatically in two cases:
  • An email to the address bounced permanently.
  • The recipient reported an email as spam, which is a complaint.
Temporary bounces do not add an address. An address appears once per organization, and the first record stays in place when later events arrive for the same address. For transactional sending, one suppressed address among the recipients of an email stops that whole email. See Sending events for email.rejected. The API has no operation to list or remove suppression entries. To review or remove an address, contact support.

​
Next steps

Templates

Publish a version that includes the placeholder

Create and send a broadcast

Send your first broadcast