Custom Headers

Attach custom headers to your outgoing emails using the headers object on the send request.

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

Naming restriction: any header outside of the reserved list below must start with X-. This is enforced to prevent header injection and protect RFC-reserved fields.

Reserved headers

These headers don't need the X- prefix. For the unsubscribe headers, see Unsubscribe Headers.

List-Id
Identifies the mailing list the email belongs to.
X-Report-Abuse
A URL where recipients can report abuse.
Feedback-ID
Identifier mailbox providers use to group feedback-loop reports.
List-Unsubscribe
Unsubscribe methods (mailto: and/or https:).
List-Unsubscribe-Post
Enables one-click unsubscribe.

Any other header

Must be prefixed with X-. Anything else is rejected before the email is queued.

Valid

"X-MyCustomHeader": "testcustom0"
"X-CUSTOM-X": "testcustom1"

Invalid

"MyCustomHeader": "testcustom0"
→ HEADER_NOT_ALLOWED

Quick start

import axios from 'axios';

await axios.post(
  'https://mail.sendcorex.com/v3.0/send',
  {
    to: 'user@example.com',
    from: 'noreply@yourdomain.com',
    senderName: 'My App',
    subject: 'Welcome aboard!',
    body: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
    replyTo: 'support@yourdomain.com',
    headers: {
      'List-Id': 'My List <mylist.yourdomain.com>',
      'X-Report-Abuse': 'https://yourdomain.com/report-abuse',
      'Feedback-ID': 'campaign123:subscriber456:list789:youraccount',
      'List-Unsubscribe':
        '<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>',
      'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
      'X-MyCustomHeader': 'testcustom0',
      'X-CUSTOM-X': 'testcustom1',
    },
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } }
);

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, code and responseTime.

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).