Send email from Python with an email API

To send email from Python you either speak SMTP yourself with smtplib from the standard library, or you make an HTTPS request to a Python email API client. Both put a message in front of a mail server. They differ in what happens around that.

There is nothing wrong with smtplib as an SMTP client. It is simply a client: it will not verify your domain, remember that an address bounced, or tell you what happened after the handoff. With a bare relay those are yours to build. The API versus SMTP comparison goes through the trade in full.

Coming soon: the rasket package is not published yet. Until it is, the send is an ordinary HTTPS request, and requests is all it takes; httpx works the same way if you need async.

pip install requests
# or, in a uv projectuv add requests

import os
import requests
response = requests.post(    "https://api.rasket.com/emails",    headers={        "authorization": f"Bearer {os.environ['RASKET_API_KEY']}",        "content-type": "application/json",        "user-agent": "acme-billing/1.0",        "idempotency-key": "receipt-1042",    },    json={        "from": "Acme <receipts@send.acme.example>",        "to": ["ronald.williams@example.com"],        "subject": "Your receipt",        "html": "<p>Thanks for your order.</p>",    },    timeout=10,)
response.raise_for_status()email_id = response.json()["id"]

Four details are load-bearing. The key is read from the environment with os.environ rather than os.environ.get, so a missing key raises at start-up instead of sending None as a bearer token at three in the morning. The user agent is required — a request without one is refused — and naming your application is what lets support tell your billing worker from your web process. The idempotency key is derived from the order rather than generated fresh. And the timeout: a request without one can hang indefinitely, and in a worker that means a task that never finishes rather than an error you can act on.

The framework matters less than the placement. A send is a network call to another service, and doing it inline inside a request handler makes your response time depend on theirs — and your request fail when theirs does.

• Django. Write the row that records the mail is owed inside the same transaction as whatever caused it, and send from a task afterwards. A task queue you already run is the right home; the row is what makes the send retryable.
• FastAPI. A background task is enough for low volume and honest about its limits: it runs in the same process, so a restart loses it. For anything you cannot afford to lose, the row plus a real queue is still the answer.

In both cases the send function should take an idempotency key as an argument rather than making one up, so that the caller — which knows what the work is — decides what counts as the same send. The stack pages have a worked example per framework.

Two kinds of failure, and the distinction between them is the whole retry policy. A response that is not 2xx means the API answered and said no. A connection error or a timeout means nothing answered, so you do not know whether the message was sent.

import requests
try:    response = requests.post(URL, headers=headers(key), json=message, timeout=10)except (requests.ConnectionError, requests.Timeout):    # No answer arrived. Retry with the SAME Idempotency-Key.    retry_later(key)else:    if not response.ok:        error = response.json()        if error["name"] == "validation_error":            reject(error["errors"])        elif response.status_code == 429:            later(int(response.headers["retry-after"]))        else:            # error["message"]; quote response.headers["x-request-id"] to support            response.raise_for_status()

Retry the second with the same key. A repeat of a keyed request inside the 24-hour window returns the original response and sends nothing, which is what makes retrying a timeout safe. Retrying the first is usually wrong: a validation error will fail identically forever, and only rate_limit_exceeded is worth waiting on.

The rate limit is ten requests a second per team, across every endpoint, and every response carries the limit, what is left and when the window resets. Pace a bulk job off the remaining count rather than off a sleep you tuned once on a quiet afternoon; the rate limits guide has the headers and the error shape.

Delivery events arrive as signed HTTPS requests. The signature scheme is the Standard Webhooks one, so the svix package verifies it directly and you do not have to implement the HMAC yourself.

# pip install svixfrom flask import Flask, requestfrom svix.webhooks import Webhook, WebhookVerificationError
app = Flask(__name__)

@app.post("/hooks/rasket")def rasket_webhook():    # get_data() is the raw body. Never get_json() first: it parses,    # and the signature is over what arrived.    raw_body = request.get_data()
    try:        event = Webhook(RASKET_WEBHOOK_SECRET).verify(raw_body, dict(request.headers))    except WebhookVerificationError:        return "invalid signature", 400
    handle(event)    return "", 200

The comment is the whole trap. Reading the parsed JSON first and re-serialising it produces a different string, and a different string has a different signature. Read the raw body, verify, then parse. The same rule applies in Django with request.body and in FastAPI with await request.body().

Answer quickly and do the work afterwards, deduplicating on the event id, because a handler that times out will be sent the same event again. The webhooks article covers retries, ordering and replay, and the emails API reference documents every field a send takes.