> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# Unsubscribe Links and One-Click Headers

> Learn when AhaSend adds one-click List-Unsubscribe headers, how to add a signed unsubscribe link with {{unsubscribe_url}}, and what a click does.

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](/docs/deliverability#what-do-gmail-and-yahoo-require).

| Mail | Unsubscribe headers |
| - | - |
| API and SMTP mail from a domain with the sending type marketing | Always |
| API and SMTP mail from a domain with the sending type transactional | Only when the message uses `{{unsubscribe_url}}` |
| Campaigns | They use their own unsubscribe link and headers. This page does not apply to them |
| [Sandbox](/docs/send-api/sandbox) mail and mail to a suppressed address | No. AhaSend does not deliver this mail |

To choose the sending type of a domain, see [which sending type to use](/docs/deliverability#which-sending-type-should-my-domain-use).

The headers look like this:

```text theme={null}
List-Unsubscribe: <https://subscriptions.example.com/unsubscribe/SIGNED_TOKEN>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

AhaSend signs both headers with DKIM, together with the rest of the message. The link uses your [subscription management domain](/docs/domains) when you set one up. Otherwise, it uses an AhaSend hostname.

## How Do I Add the Link to My Email?

Put `{{unsubscribe_url}}` in the HTML or text content. AhaSend replaces it with a signed link for each recipient.

```html theme={null}
<p><a href="{{unsubscribe_url}}">Unsubscribe</a></p>
```

`{{unsubscribe_url}}` works in these send paths:

* [API v2](/docs/send-api/send-email), with inline content or with a saved template. Inline content works with and without `substitutions`.
* [SMTP](/docs/smtp).
* [API v1](/docs/api-reference/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.

```json API v2 Example theme={null}
{
  "from": {
    "email": "news@yourdomain.com",
    "name": "Your Company"
  },
  "recipients": [
    {
      "email": "user@example.com",
      "name": "John Doe"
    }
  ],
  "subject": "Our October news",
  "html_content": "<p>Here is what is new this month.</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>",
  "text_content": "Here is what is new this month. Unsubscribe: {{unsubscribe_url}}"
}
```

**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](/docs/tracking/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.

<Note>
  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.
</Note>

## 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](/docs/deliverability#how-do-i-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:

```text theme={null}
List-Unsubscribe: <mailto:unsubscribe@yourdomain.com>
```

the delivered message has these headers:

```text theme={null}
List-Unsubscribe: <https://subscriptions.example.com/unsubscribe/SIGNED_TOKEN>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

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](/docs/bounces) 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](/docs/api-reference/suppressions/get-suppressions) to find addresses that unsubscribed.

## What If AhaSend Cannot Make the Link?

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.

## Related Guides

* [Deliverability best practices](/docs/deliverability), [bounces and suppressions](/docs/bounces) and [domain setup](/docs/domains).
* [REST API](/docs/send-api/send-email), [SMTP settings](/docs/smtp), [SMTP errors](/docs/smtp/errors) and [click tracking](/docs/tracking/click-tracking).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.