cURL quickstart

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.

Create a MailChannels account

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.

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.

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.

Your sending domain must resolve. It needs a valid A or MX record. Without one, mail from the domain is rejected with 550 5.1.2 [SDNF] Sender Domain Not Found. Most registered domains already have these records. Confirm yours with the check-domain tool. See Troubleshooting for details.

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.

Get Started

API Reference

Authentication & Account Setup

Sending Email

Email Authentication

Webhooks & Delivery Events

Platform & Multi-tenant

Reputation and Abuse Control

Metrics & Monitoring

Operate in production

Migration guides

Integrations

For AI Agents

Prerequisites

Install the cURL SDK

Send your first email

Next steps

​Prerequisites

​Install the cURL SDK

​Send your first email

​Next steps

Prerequisites

Install the cURL SDK

Send your first email

Next steps