> ## 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.

# cURL quickstart

> Send an email with the MailChannels Email API using cURL.

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.

<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 cURL SDK

```bash cURL theme={null}
# 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.

<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>
  ```bash cURL theme={null}
  #!/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
  ```
</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.