# Send emails with Python

> Call the MailBlastr REST API from Python with the requests library.

MailBlastr does not yet publish a Python package. Because MailBlastr is a JSON REST API, the popular [`requests`](https://requests.readthedocs.io) library (or any HTTP client like `httpx`) is all it takes to send mail from Python.

This guide sends a single email with `POST /emails`. Node.js / TypeScript projects can use `npm install mailblastr` instead — see [Send emails with Node.js](https://www.mailblastr.com/docs/integrations/nodejs).

## Prerequisites

1. A **verified domain** for your `from` address. ([guide](https://www.mailblastr.com/docs/domains/managing))
2. An **API key** (`mb_...`), created under API Keys and shown once. ([Authentication](https://www.mailblastr.com/docs/authentication))
3. `requests` installed: `pip install requests`.

## Send an email

Read the key from the environment so it never lives in source control.

**send.py**

```python
import os
import requests

api_key = os.environ["MAILBLASTR_API_KEY"]

res = requests.post(
    "https://www.mailblastr.com/api/emails",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "from": "Acme <hello@yourdomain.com>",
        "to": ["delivered@example.com"],
        "subject": "Hello from Python",
        "html": "<p>Sent with requests 🐍</p>",
    },
    timeout=10,
)

# Raise for any 4xx/5xx; MailBlastr returns { statusCode, name, message }.
if not res.ok:
    err = res.json()
    raise RuntimeError(f"MailBlastr {err['name']}: {err['message']}")

email_id = res.json()["id"]
print("Sent email", email_id)
```

## Handling the response

A successful call returns HTTP `200` and a JSON body with the new email `id`. Errors come back with a non-2xx status and a `{ statusCode, name, message }` body — check `res.ok` (or call `res.raise_for_status()`) before reading the `id`. Keep the `id` to [retrieve the email](https://www.mailblastr.com/docs/api/emails-get) or match [webhook](https://www.mailblastr.com/docs/webhooks/overview) events later.

```json
{
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
}
```

> **Warning:** Keep the `mb_` API key server-side — load it from an environment variable or secrets manager, never commit it, and never send it from a browser or mobile client. Anyone holding the key can send email as you.

## Next steps

- See the full [Send Email API](https://www.mailblastr.com/docs/api/emails-send) reference for every body field.
- Using a web framework? See [Send emails with Django](https://www.mailblastr.com/docs/integrations/django).
- Start from the [Quickstart](https://www.mailblastr.com/docs/quickstart).