Unsubscribe Headers

Add List-Unsubscribe headers to your emails so recipients (and mailbox providers like Gmail and Yahoo) can unsubscribe without marking your email as spam. This significantly improves deliverability for bulk and marketing sends.

POSThttps://mail.sendcorex.com/v3.0/send

Mailbox providers strongly recommend (and in some cases require) List-Unsubscribe on any bulk mail. Missing this header on high-volume sends can hurt inbox placement.

Headers go in the headers object of the send request. For the naming rules that apply to every other header, see Custom Headers.

Supported headers

List-Unsubscribeoptional
Comma-separated list of unsubscribe methods, wrapped in angle brackets. Supports both a mailto: and an https: link.
e.g. "<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>"
List-Unsubscribe-Postoptional
Enables Gmail/Yahoo one-click unsubscribe. Required if you want the "Unsubscribe" button to appear directly in the inbox UI. Must be exactly:
e.g. "List-Unsubscribe=One-Click"
List-Idoptional
Identifies the mailing list this email belongs to.
e.g. "My List <mylist.yourdomain.com>"

Automatic unsubscribe link

If you don't have your own unsubscribe engine, Sendcorex can generate and manage the unsubscribe link and mailto for you. Set unsubscribe: true on the send request, and include one of the supported placeholders in your body where you want the link inserted.

Supported placeholders

[unsubscribe_url]
[unsubscribe]
[unsub_url]
[opt_out_url]

Use any one of them inside an href (or anywhere in the body). Sendcorex replaces it with the real per-recipient unsubscribe link before sending.

unsubscribe: true, no engine of your own

{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "senderName": "My App",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "replyTo": "support@yourdomain.com",
  "unsubscribe": true
}

If unsubscribe: true is set but none of the supported placeholders are found in the body, the request fails with MISSING_UNSUBSCRIBE_PLACEHOLDER. See the 400 response.

Contact list

optional

contact_list is not required. It only controls which list the recipient is saved to for tracking and organization. It has nothing to do with the unsubscribe link itself.

Without contact_list (default)

The contact is automatically saved to a default list called "API Contacts". This name can't be changed. You can review it anytime in your contact lists.

{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "unsubscribe": true
}

With contact_list (custom name)

If the list doesn't exist yet, it's created automatically. This is useful for separating audiences, for example one list per campaign or platform.

"CRM 2026 - Gmail"
"Newsletter - Trial Users"
"Support Tickets"

{
  "to": "contact@gmail.com",
  "from": "noreply@yourdomain.com",
  "subject": "Welcome aboard!",
  "body": "<h1>Welcome!</h1><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
  "unsubscribe": true,
  "contact_list": "CRM 2026 - Gmail"
}

Quick start

import axios from 'axios';

const response = await axios.post(
  'https://mail.sendcorex.com/v3.0/send',
  {
    to: 'contact@gmail.com',
    from: 'noreply@yourdomain.com',
    senderName: 'My App',
    subject: 'Welcome aboard!',
    body: '<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href="[unsubscribe]">Unsubscribe</a></p>',
    unsubscribe: true,
    contact_list: 'CRM 2026 - Gmail',
    headers: {
      'List-Id': 'My List <mylist.yourdomain.com>',
      'List-Unsubscribe':
        '<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>',
      'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
    },
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } }
);

const { id } = response.data;

Response

{
  "success": true,
  "message": "Email queued successfully",
  "code": "EMAIL_QUEUED_SUCCESS",
  "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f"
}

Errors

All error codes →

Errors return a JSON object with error and code.

401MISSING_AUTH_HEADER
No Authorization header present.
401INVALID_API_KEY
The API key is invalid or revoked.
401ACCOUNT_BLOCKED
Account has been blocked.
401NO_CREDITS_LEFT
No email credits remaining.
401DOMAIN_NOT_VALIDATED
Sender domain not verified.
401LISTED_SPAM_HAUS
Sender domain is listed on Spamhaus.
401ISP_DOMAIN_BLOCKED
Sending from well-known domains (gmail.com, outlook.com, etc) is not allowed.
401FROM_HEADER_DOMAIN_MISMATCH
From header domain not authorized for this sender.
401USER_NOT_FOUND
User not found.
401MISSING_USER_PRIVILEGES
Missing user privileges.
401EMAIL_CREDITS_NOT_FOUND
Error fetching email credits.
429CREDENTIAL_TEMPORARILY_BLOCKED
API key temporarily blocked due to repeated policy violations.
429IP_TEMPORARILY_BLOCKED
Requesting IP temporarily blocked due to repeated policy violations.
400MISSING_FROM
The from field is missing or empty.
400INVALID_FROM_FORMAT
The from field must be a valid email address.
400MISSING_SENDERNAME
The senderName field is missing or empty.
400INVALID_SENDERNAME_FORMAT
The senderName field contains invalid characters.
400MISSING_SUBJECT
The subject field is missing or empty.
400MISSING_BODY
The body field is missing or empty.
400MISSING_TOADDRESS
The to field is missing or empty.
400MISSING_TO
The to field is missing or empty.
400INVALID_TOADDRESS
One or more recipient addresses are malformed.
400TOADDRESS_LIMIT_EXCEEDED
More than 50 recipients in the to array.
400INVALID_SCHEDULED_AT
scheduled_at is not a valid date or is in the past.
400INVALID_SENDER_FORMAT
The sender email format is invalid.
400HEADER_NOT_ALLOWED
Custom header key is not on the allowed list (List-Unsubscribe, List-Id, X-*, etc).
400INVALID_HEADER_VALUE
Header value contains invalid characters (CR/LF not allowed).
400DANGEROUS_ATTACHMENT
One or more attachments were blocked for security reasons.
403ACCOUNT_RESTRICTED
Account is temporarily restricted.
403DAILY_LIMIT
Daily email sending limit reached.
403SPAM_DETECTED
Email content flagged as spam. Response includes quarantine_id and release instructions.
403SENDER_NAME_MISMATCH
Multiple sender names detected for same address.
403FOLLOWUP_PATTERN_DETECTED
Email content flagged as repeated suspicious follow-up pattern.
403SCAM_PATTERN_DETECTED
Email content flagged as scam pattern.
403ACCOUNT_SUSPENDED_SPOOFING
Account suspended due to repeated From header spoofing attempts.
500INTERNAL_SERVER_ERROR
Unexpected server error. Try again.
500PARSE_ERROR
Failed to process email content (MIME parse failure).
500PERSIST_FAILED
Failed to queue email (database persistence failure).