Skip to main content
Send an email in a few minutes. This guide walks through sending your first request to the MailChannels Email API. The Node.js SDK is open source. Browse the source code.

​
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 Node.js SDK

Node.js
# npm
npm i mailchannels-sdk

# yarn
yarn add mailchannels-sdk

# pnpm
pnpm add mailchannels-sdk

​
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.
import { MailChannels } from "mailchannels-sdk";

const { MAILCHANNELS_API_KEY, FROM_EMAIL, TO_EMAIL } = process.env;
if (!MAILCHANNELS_API_KEY) throw new Error("Set MAILCHANNELS_API_KEY before running");
if (!FROM_EMAIL) throw new Error("Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)");
if (!TO_EMAIL) throw new Error("Set TO_EMAIL");

const mailchannels = new MailChannels(MAILCHANNELS_API_KEY);

const { data, error } = await mailchannels.emails.send({
  from: { email: FROM_EMAIL, name: "Your Name" },
  to: { email: TO_EMAIL, name: "Recipient" },
  subject: "Hello from MailChannels",
  text: "Hello! This is a plain-text fallback for clients that don't render HTML.",
  html: '<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>',
});

if (error) {
  console.error("Send failed:", error);
  process.exit(1);
}
console.log(data);
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.