Skip to main content
AhaSend can give each recipient a signed one-click unsubscribe link. This page explains when AhaSend adds the unsubscribe headers, how to put the link in your email with {{unsubscribe_url}}, and what happens when a recipient uses it.

​
Which Mail Gets the Unsubscribe Headers?

The unsubscribe headers let mail clients show their own unsubscribe button. Gmail and Yahoo require them for bulk marketing mail. See what Gmail and Yahoo require. To choose the sending type of a domain, see which sending type to use. The headers look like this:
AhaSend signs both headers with DKIM, together with the rest of the message. The link uses your subscription management domain when you set one up. Otherwise, it uses an AhaSend hostname. Put {{unsubscribe_url}} in the HTML or text content. AhaSend replaces it with a signed link for each recipient.
{{unsubscribe_url}} works in these send paths:
  • API v2, with inline content or with a saved template. Inline content works with and without substitutions.
  • SMTP.
  • API v1 (POST /v1/email/send).
It works for both sending types. When a message from a transactional domain uses it, the message also gets the unsubscribe headers.
API v2 Example
Rules:
  • Write the name in lower case: {{unsubscribe_url}}. AhaSend does not replace {{Unsubscribe_URL}}.
  • Spaces inside the braces are allowed: {{ unsubscribe_url }} works.
  • Each recipient gets a different link.
  • Click tracking never changes the AhaSend unsubscribe link.
  • On an inline API v2 send, if you give your own unsubscribe_url value in substitutions, AhaSend uses your value in the content. Mail from a marketing domain still gets the AhaSend headers.
  • You can also put {{unsubscribe_url}} in your own List-Unsubscribe header. AhaSend then writes the header with its link.
AhaSend adds each recipient’s link just before delivery. Thus, the message data in your message logs can show {{unsubscribe_url}} instead of the link.

​
Can I Use My Own List-Unsubscribe Header?

Yes. AhaSend keeps your headers as they are when all of these are true:
  • Each item in List-Unsubscribe is a link in angle brackets, such as <https://example.com/unsubscribe/TOKEN>, and no item is repeated.
  • At least one link is https.
  • The message has List-Unsubscribe-Post: List-Unsubscribe=One-Click.
Your endpoint must then accept the one-click POST. See how to add one-click unsubscribe. If your headers do not meet these rules, and the message needs the unsubscribe headers, AhaSend replaces them. The new List-Unsubscribe header has only the AhaSend link, so that each unsubscribe adds a suppression in AhaSend. AhaSend does not keep your links, also not a mailto: link. An API v2 send with a saved template that uses {{unsubscribe_url}} always gets the AhaSend headers, also when your headers meet the rules. For example, if your message has only this header:
the delivered message has these headers:
AhaSend does not examine or change the headers of transactional mail that does not use {{unsubscribe_url}}.

​
What Happens When a Recipient Unsubscribes?

The recipient can use the unsubscribe button of their mail client, or open the link and confirm on the unsubscribe page. AhaSend then adds a suppression for that address and your sending domain, with the reason Unsubscribed. Like a spam complaint, it is effectively permanent. AhaSend stops sending mail to the address from that domain. Only opening the link does not unsubscribe the recipient. The page asks the recipient to confirm, so link scanners in mail filters do not unsubscribe anyone. Keep the opt-out in your own recipient data too. Use List Suppressions to find addresses that unsubscribed. AhaSend never sends a message that needs the unsubscribe link without it. If AhaSend cannot make the link, it refuses the message with a temporary error:
  • SMTP: 451 4.3.0 Unsubscribe link is not available. Try again later. Your SMTP client sends the message again later.
  • API: the recipient gets an error entry in the response. If AhaSend could not queue any recipient, the API returns a 500 error. Send the request again later.