Skip to main content
MailChannels supports two ways to let recipients opt out of future email:
  • An unsubscribe link that you place inside the message body.
  • List-Unsubscribe headers that email clients render as a native unsubscribe control.
Insert the mc-unsubscribe-url placeholder anywhere in your text/html or text/plain content. At render time, MailChannels replaces it with a unique URL that opens a one-click unsubscribe page hosted by MailChannels. To use the placeholder:
  • The content part must set template_type to mustache.
  • Each personalization must contain exactly one recipient, so the generated URL is unique to that recipient.
Only text/html and text/plain content parts are supported. The placeholder is ignored in other content types.

​
HTML content

Place the placeholder in the href of an <a> element so it renders correctly across email clients: 
#!/usr/bin/env bash
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
: "${TO_EMAIL:?Set TO_EMAIL}"

curl -X POST https://api.mailchannels.net/tx/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    { "to": [{ "email": "$TO_EMAIL", "name": "Recipient" }] }
  ],
  "from": {
    "email": "$FROM_EMAIL",
    "name": "Your Name"
  },
  "subject": "Hello from MailChannels",
  "content": [
    {
      "type": "text/html",
      "value": "<html><body><a href='{{mc-unsubscribe-url}}'>Unsubscribe</a></body></html>",
      "template_type": "mustache"
    }
  ]
}
JSON

​
Plain text content

Include the placeholder inline: 
#!/usr/bin/env bash
set -u
: "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY before running}"
: "${FROM_EMAIL:?Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)}"
: "${TO_EMAIL:?Set TO_EMAIL}"

curl -X POST https://api.mailchannels.net/tx/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
  -d @- <<JSON
{
  "personalizations": [
    { "to": [{ "email": "$TO_EMAIL", "name": "Recipient" }] }
  ],
  "from": {
    "email": "$FROM_EMAIL",
    "name": "Your Name"
  },
  "subject": "Hello from MailChannels",
  "content": [
    {
      "type": "text/plain",
      "value": "To unsubscribe, visit: {{mc-unsubscribe-url}}",
      "template_type": "mustache"
    }
  ]
}
JSON

​
List-Unsubscribe headers

Clients such as Gmail and Apple Mail render a native Unsubscribe control when a message carries List-Unsubscribe and List-Unsubscribe-Post headers. We automatically add both headers when the transactional field is set to false in the send request. When transactional is false, the following conditions must also be met:
  • Each personalization contains exactly one recipient
  • The email is DKIM signed