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

# Python quickstart

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

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

The Python SDK is open source. Browse the [source code](https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-py/).

## 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 Python SDK

```python Python theme={null}
# pip
pip install mailchannels

# uv
uv add mailchannels
```

## 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>
  ```python Python theme={null}
  import os
  import sys

  import mailchannels

  # The SDK reads MAILCHANNELS_API_KEY from the environment automatically.
  if not os.environ.get("MAILCHANNELS_API_KEY"):
      sys.exit("Set MAILCHANNELS_API_KEY before running")

  from_email = os.environ.get("FROM_EMAIL")
  to_email = os.environ.get("TO_EMAIL")
  if not from_email:
      sys.exit("Set FROM_EMAIL (must be on a Domain-Lockdown-authorized domain)")
  if not to_email:
      sys.exit("Set TO_EMAIL")

  response = 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>'
          ),
      }
  )

  print(response)
  ```
</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.