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

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