API Reference

Complete documentation for integrating MailCannon's powerful email tools into your application.

Getting Started

MailCannon's API allows you to automate your communication workflows. Whether you need to trigger a campaign after a user action or verify an email address during signup, our RESTful API has you covered.

Base URL

https://mailcannon.pro/api/v1

Formats

JSON requests & responses

Authentication

API Key Management

All API requests must be authenticated using an API key.

Your API Key should be passed in the X-API-KEY header for every request.

Security Note: Never share your API key or commit it to version control. If a key is compromised, revoke it immediately in the dashboard.

How to get your API Key:

Log in to your MailCannon Dashboard.
Navigate to Settings and click on the API Keys tab.
Click Generate New Key, give it a name, and copy the secret key.

Send Email

/send-email-campaign-by-id

Trigger a campaign to a specific recipient.

POST

Request Parameters

Field	Type	Description
campaign_id	String	Required The ID of the campaign to send.
email	String	Required Recipient's email address.
username	String	Optional Recipient's name for personalization.
replacements	Object	Optional Custom replacement values for dynamic placeholders such as `{{company}}`. See .

Implementation Examples

curl -X POST https://mailcannon.pro/api/v1/send-email-campaign-by-id \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "User Name",
    "campaign_id": "your_campaign_id_here"
  }'

Dynamic Replacements

Personalize emails with placeholders

MailCannon replaces {{placeholders}} inside your campaign templates with recipient-specific values at send time.

How it works

Any placeholder found in your campaign HTML is resolved per recipient, so every contact receives a personalized email. Placeholders that have no value are left untouched.

Template

<p>Hello {{username}},</p>
<p>Welcome to {{company}}.</p>

API request"replacements": { "company": "Acme Inc." }

Result

<p>Hello John,</p>
<p>Welcome to Acme Inc.</p>

Built-in variables

Placeholder	Resolves to
{{username}}	The recipient's name (from the request or the contact record).
{{email}}	The recipient's email address.
{{current_year}}	The current year, e.g. 2026. System generated — cannot be overridden.

Contact fields

Placeholders matching a contact profile field are resolved from the recipient's record automatically: {{company}}, {{city}}, {{country}}, {{phone}}, {{website}}, {{plan}}, {{first_name}} and more. camelCase field names are also accepted ({{firstName}}).

Custom replacements

Pass any additional variables in the optional replacements object of the send request. Keys must be lowercase letters, digits and underscores only (for example company, first_name, discount). Values must be strings, numbers or booleans.

{
  "campaign_id": "campaign_123",
  "email": "customer@example.com",
  "username": "John",
  "replacements": {
    "company": "Acme Inc.",
    "plan": "Professional",
    "discount": "25%"
  }
}

Precedence & safety

System values ({{current_year}}) and recipient identity ({{username}}, {{email}}) are reserved and can never be overridden by replacements.
Explicit replacements take precedence over contact-derived values.
Contact fields fill in everything else, per recipient.
Replacement values are HTML-escaped, so they cannot inject markup or scripts. Values used in href/src attributes are restricted to safe URL schemes (http/https/mailto/tel/relative).
Each recipient's values are resolved independently — values never leak between recipients.

Example with replacements

curl -X POST https://mailcannon.pro/api/v1/send-email-campaign-by-id \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign_123",
    "email": "customer@example.com",
    "username": "John",
    "replacements": {
      "company": "Acme Inc.",
      "plan": "Professional",
      "discount": "25%"
    }
  }'

Backwards compatible: the replacements object is optional. Existing requests without it continue to work exactly as before.

Email Checker

/email-checker

Verify if an email address exists and is reachable.

POST

Request Parameters

Field	Type	Description
email	String	Required Email to verify.

Implementation Examples

curl -X POST https://mailcannon.pro/api/v1/email-checker \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "verify@example.com"
  }'

Response Structure

The API returns a detailed reachability report including syntax check, SMTP handshake, and Gravatar data.

{
  "success": true,
  "data": {
    "is_reachable": "safe",
    "syntax": { "is_valid_syntax": true },
    "smtp": { "can_connect_smtp": true, "is_deliverable": true }
  }
}

Code Examples

MailCannon TypeScript Client

Ready-to-use TypeScript class for integrating MailCannon into your application. Includes all campaign types and proper error handling.

Download the complete TypeScript implementation

Usage Example:

import { MailCannon, MailCannonCampaign } from './MailCannon';

// Send a welcome email
await MailCannon.sendEmail(
  'user@example.com',
  'John Doe',
  MailCannonCampaign.NEW_USER_SIGNUP
);

Features

• Type-safe campaign management
• Built-in error handling
• Environment variable support
• Promise-based API

Requirements

• Node.js 14+
• axios package
• TypeScript (optional)
• MailCannon API Key