Python quickstart

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.

Create a MailChannels account

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.

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.

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.

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. See Troubleshooting for details.

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.

Get Started

API Reference

Authentication & Account Setup

Sending Email

Email Authentication

Webhooks & Delivery Events

Platform & Multi-tenant

Reputation and Abuse Control

Metrics & Monitoring

Operate in production

Migration guides

Integrations

For AI Agents

Prerequisites

Install the Python SDK

Send your first email

Next steps

​Prerequisites

​Install the Python SDK

​Send your first email

​Next steps

Prerequisites

Install the Python SDK

Send your first email

Next steps