> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js quickstart

> Send an email with the MailChannels Email API using Node.js.

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](https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js/).

## Prerequisites

Before your first request, complete the following steps.

<Steps>
  <Step title="Create a MailChannels account">
    [Sign up](https://dash.mailchannels.com) if you don't already have an account.
  </Step>

  <Step title="Generate an API key">
    Open [Account > API Keys](https://dash.mailchannels.com/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.

    <Warning>
      Treat your API key like a password. Don't commit it to source control or expose it in client-side code.
    </Warning>
  </Step>

  <Step title="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](/email-api/domain-lockdown) for details.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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](https://dash.mailchannels.com/domain-health). See [Troubleshooting](/email-api/troubleshooting) for details.
</Warning>

## Install the Node.js SDK

```javascript Node.js theme={null}
# 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.

<Info>
  Until you add a payment method, sending is restricted to addresses belonging to verified [Users](https://dash.mailchannels.com/account/users)
  **on your account**. Add a user, click the link in the verification email, then use that address as the `to` email below.
</Info>

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

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](/email-api/webhooks) to learn how to get real-time notifications about email delivery,
  bounces, and complaints.
* Explore the [API reference](/email-api/api-reference-introduction) to see what else you can do with the API.