Skip to main content
Send an email in a few minutes. This guide walks through sending your first request to the MailChannels Email API.

​
Prerequisites

Before your first request, complete the following steps.
1

Create a MailChannels account

Sign up if you don’t already have an account.
2

Generate an API key

Open Account > API Keys and click Create API Key. Add a descriptive label and set the scope to api. Copy the key; you won’t be able to see it again.
Treat your API key like a password. Don’t commit it to source control or expose it in client-side code.
3

Add a Domain Lockdown DNS record

For each domain you’ll send from, add a TXT record on the _mailchannels subdomain authorizing your account to send. Replace examplecorp with your MailChannels account ID (visible in the panel footer when you log in):
_mailchannels.example.com  TXT  "v=mc1 auth=examplecorp"
See the Domain Lockdown guide for details.
4

Update your SPF DNS record

Add MailChannels to the SPF record on each sending domain so recipient servers accept your mail:
example.com  TXT  "v=spf1 include:relay.mailchannels.net ~all"
If you already have an SPF record, merge in include:relay.mailchannels.net rather than creating a second record. A domain must have only one SPF record.

​
Install the cURL SDK

cURL
# cURL ships with macOS and most Linux distributions. If it's missing,
# install it with your platform's package manager:

# macOS (Homebrew)
brew install curl

# Debian / Ubuntu
sudo apt-get install curl

# Windows (winget) — note: curl ships with Windows 10 (1803+) and Windows 11
winget install cURL.cURL

# Verify the install
curl --version

​
Send your first email

To send an email, provide the recipients, sender, subject, and message content. The example below sends an HTML email to a single recipient.
Until you add a payment method, sending is restricted to addresses belonging to verified Users on your account. Add a user, click the link in the verification email, then use that address as the to email below.
#!/usr/bin/env bash
# Check that the required variables are set. This is just a sanity check for
# this example script
  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": "Hello! This is a plain-text fallback for clients that don't render HTML."
    },
    {
      "type": "text/html",
      "value": "<p>Hello,</p><p>This is my first <strong>HTML</strong> email sent via the <a href=\"https://www.mailchannels.com/email-api/\">MailChannels Email API</a>.</p>"
    }
  ]
}
JSON
Set the following before running:
  • MAILCHANNELS_API_KEY — the API key generated above.
  • FROM_EMAIL — an address on the domain you configured with Domain Lockdown and SPF above (e.g. hello@example.com if you used example.com in the Domain Lockdown and SPF DNS records).
  • TO_EMAIL — a recipient inbox you can check, e.g. the address you use to sign up for MailChannels.

​
Next steps

  • Read the webhooks guide to learn how to get real-time notifications about email delivery, bounces, and complaints.
  • Explore the API reference to see what else you can do with the API.