Email API

Send transactional and marketing emails with industry-leading deliverability. Track opens, clicks, and bounces in real-time.

99.9% Deliverability

Enterprise-grade infrastructure with automatic IP warming.

Real-time Analytics

Track opens, clicks, bounces, and complaints instantly.

DKIM & SPF

Automatic email authentication with guided DNS setup.

Quick Start

Send your first email in seconds. Canary handles all the complexity of email deliverability so you can focus on your product.

POST/v1/email

curl -X POST https://api.canarymsg.dev/v1/email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
  {
    "from": "hello@yourcompany.com",
    "to": "user@example.com",
    "subject": "Welcome to our platform!",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
  }
'

Response

{
  "id": "email_abc123xyz",
  "from": "hello@yourcompany.com",
  "to": "user@example.com",
  "subject": "Welcome to our platform!",
  "status": "queued",
  "created_at": "2024-01-01T12:00:00Z"
}

Request Parameters

Parameter	Type	Required	Description
`from`	string		Sender email address (must be verified)
`to`	string \| array		Recipient email address(es)
`subject`	string		Email subject line
`html`	string	*	HTML content of the email
`text`	string	*	Plain text content of the email
`cc`	string \| array	Optional	CC recipient email address(es)
`bcc`	string \| array	Optional	BCC recipient email address(es)
`reply_to`	string	Optional	Reply-to email address
`attachments`	array	Optional	File attachments (base64 encoded)
`headers`	object	Optional	Custom email headers
`tags`	array	Optional	Tags for categorization and analytics

* Either html or text is required

Email Templates

Create reusable email templates with dynamic variables. Templates support Handlebars syntax for personalization.

Create a Template

POST/v1/email/templates

{
  "name": "welcome_email",
  "subject": "Welcome to {{company_name}}, {{first_name}}!",
  "html": "<h1>Welcome, {{first_name}}!</h1><p>Thanks for joining {{company_name}}.</p>"
}

Send with Template

POST/v1/email

{
  "from": "hello@yourcompany.com",
  "to": "user@example.com",
  "template": "welcome_email",
  "variables": {
    "first_name": "Alice",
    "company_name": "Acme Inc"
  }
}

Domain Verification

Verify your domain to improve deliverability and enable custom sender addresses. Canary guides you through the DNS configuration process.

Add a Domain

POST/v1/email/domains

{
  "domain": "yourcompany.com"
}

DNS Records Response

{
  "domain": "yourcompany.com",
  "status": "pending",
  "dns_records": [
    {
      "type": "TXT",
      "name": "_dmarc.yourcompany.com",
      "value": "v=DMARC1; p=none; rua=mailto:dmarc@canarymsg.dev"
    },
    {
      "type": "TXT",
      "name": "canary._domainkey.yourcompany.com",
      "value": "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4..."
    },
    {
      "type": "TXT",
      "name": "yourcompany.com",
      "value": "v=spf1 include:_spf.canarymsg.dev ~all"
    }
  ]
}

Email Tracking

Track email engagement with open tracking, click tracking, and delivery status. All tracking is enabled by default but can be disabled per message.

Tracking Options

{
  "from": "hello@yourcompany.com",
  "to": "user@example.com",
  "subject": "Your weekly report",
  "html": "<p>Here's your report...</p>",
  "tracking": {
    "opens": true,
    "clicks": true,
    "unsubscribe": true
  }
}

Email Events

Event	Description
queued	Email is queued for sending
sent	Email was sent to the receiving server
delivered	Email was accepted by the receiving server
opened	Recipient opened the email
clicked	Recipient clicked a link in the email
bounced	Email bounced (hard or soft)
complained	Recipient marked email as spam
unsubscribed	Recipient clicked the unsubscribe link

SDK Examples

Node.js

import Canary from '@canary/node';

const canary = new Canary('YOUR_API_KEY');

const email = await canary.email.send({
  from: 'hello@yourcompany.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our platform!</h1>',
});

console.log('Email sent:', email.id);

Python

from canary import Canary

canary = Canary("YOUR_API_KEY")

email = canary.email.send(
    from_="hello@yourcompany.com",
    to="user@example.com",
    subject="Welcome!",
    html="<h1>Welcome to our platform!</h1>"
)

print(f"Email sent: {email.id}")

Next Steps

SMS API OTP & Verification