Add Unsubscribe Links to Transactional Emails

Use this for messages that should honor a recipient preference, such as product updates, education, lifecycle nudges, or notifications that are not strictly required for account security or purchase completion.

Placeholder

Add the OpenSend unsubscribe placeholder to your HTML or text body:

<p>
  You can stop these product updates at any time:
  <a href="{{{RESEND_UNSUBSCRIBE_URL}}}">unsubscribe</a>.
</p>

Stop these product updates: {{{RESEND_UNSUBSCRIBE_URL}}}

When the send is accepted, OpenSend looks up the sole to recipient in your tenant's contacts. If the contact exists and is not already unsubscribed, OpenSend replaces every placeholder occurrence with /unsubscribe/{contactId}?token=... and adds:

• List-Unsubscribe: <https://your-opensend-host/unsubscribe/{contactId}?token=...>
• List-Unsubscribe-Post: List-Unsubscribe=One-Click

Example send

curl -X POST https://opensend.namuh.co/emails \
  -H "Authorization: Bearer os_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <updates@example.com>",
    "to": "ada@example.com",
    "subject": "Product activity summary",
    "html": "<p>Your workspace processed 42 events today.</p><p><a href=\"{{{RESEND_UNSUBSCRIBE_URL}}}\">Unsubscribe from product summaries</a></p>",
    "text": "Your workspace processed 42 events today. Unsubscribe: {{{RESEND_UNSUBSCRIBE_URL}}}"
  }'

Requirements and boundaries

• The email must have exactly one to recipient. Multi-recipient sends are left unchanged.
• The recipient must already exist as a contact for the authenticated tenant.
• If the contact is already unsubscribed, OpenSend leaves the placeholder unchanged and does not add unsubscribe headers.
• The public unsubscribe route marks the contact as unsubscribed after verifying the HMAC token.
• Production deployments must set UNSUBSCRIBE_SECRET to at least 16 characters so signed links remain stable and private across deploys.

Transactional vs marketing use

OpenSend does not decide whether a message is legally transactional or marketing. Your application owns that classification. If a message is optional, promotional, or preference-based, include the placeholder or use topics/broadcasts so recipients can opt out. If a message is required for account security, fraud prevention, or a purchase the recipient requested, keep it focused on that purpose and avoid adding unrelated marketing content.

Related dashboard surfaces

• Audience → Contacts shows contact unsubscribe state.
• Audience → Topics manages preference categories.
• Audience → Topics → Unsubscribe page customization edits the hosted confirmation page.
• Settings → Unsubscribe Page currently shows a preview-only settings tab; use the Topics editor for live customization.