Skip to main content
This feature automatically manages unsubscribe requests to help you stay compliant with email regulations like CAN-SPAM and GDPR.

​
Overview

Simple Email API provides a complete unsubscribe system with:
  • Automatic unsubscribe links via {{unsubscribe_link}} placeholder
  • RFC 8058 one-click unsubscribe headers for email clients
  • Per-recipient tracking with secure, signed tokens
  • Automatic filtering of unsubscribed recipients before sending

​
Using the Placeholder

Add {{unsubscribe_link}} anywhere in your email body or HTML: 
<p>
  Don't want these emails anymore? 
  <a href="{{unsubscribe_link}}">Unsubscribe</a>
</p>

​
Placeholder Behavior

For sync requests (async: false) with exactly one recipient, the placeholder is replaced with a unique unsubscribe link before sending.
For async requests with multiple recipients, the email is automatically split into individual sends. Each recipient receives their own unique unsubscribe link for proper tracking.
Billing Impact: Each split email counts as a separate send. Sending to 5 recipients with {{unsubscribe_link}} = 5 individual email sends.
For sync requests with multiple recipients, the placeholder is not replaced. Use async: true to enable automatic splitting with per-recipient links.

​
List-Unsubscribe Headers

All emails sent through the async path include RFC-compliant headers: 
List-Unsubscribe: <https://api.simpleemailapi.dev/unsubscribe?token=...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Modern email clients like Gmail and Outlook display a native “Unsubscribe” button from these headers, making it easy for recipients to opt out.

​
Filtering Unsubscribed Recipients

Before sending any email, the API automatically checks the unsubscribe list:
  1. All recipients (To, Cc, Bcc) are checked against the unsubscribe list
  2. Unsubscribed recipients are silently removed
  3. If all recipients are unsubscribed, the API returns success with a message
No action required — filtering happens automatically.

​
Best Practices

Use async for bulk sends

Set async: true when sending to multiple recipients with unsubscribe links to ensure proper per-recipient tracking.

Always include unsubscribe

CAN-SPAM and GDPR require clear unsubscribe options in marketing emails.

Check response messages

The API returns informative messages when recipients are filtered out.

Test before production

Use dry-run mode to verify unsubscribe link handling without sending.

​
Example Request

await client.sendEmail({
  from: "[email protected]",
  to: ["[email protected]", "[email protected]"],
  subject: "Your Weekly Newsletter",
  html: `
    <h1>Weekly Updates</h1>
    <p>Here's what happened this week...</p>
    <hr>
    <p style="font-size: 12px; color: #666;">
      <a href="{{unsubscribe_link}}">Unsubscribe</a> from these emails
    </p>
  `,
  async: true  // Enables automatic splitting for multi-recipient
});

​
Technical Details

FeatureSingle RecipientMultiple Recipients (sync)Multiple Recipients (async)
Placeholder replaced✅ Yes❌ Skipped✅ Yes (split)
List-Unsubscribe header✅ Yes✅ Yes✅ Yes
Recipient filtering✅ Yes✅ Yes✅ Yes
Individual tracking✅ Yes❌ No✅ Yes
Email count11N (one per recipient)