Send email from Django with an email API

To send email from Django you either use the mail framework the project already ships — send_mail, EmailMultiAlternatives and an EMAIL_BACKEND that speaks SMTP to a server you configure — or you make one HTTPS request to an email API from a view or a task. Both get a message to a mail server. The difference is everything around that handoff, and it is the difference this guide is about.

The mail framework is good at what it does. The locmem backend in particular is a pleasure to test against, and the console backend is the right development default. What it does not do is remember that an address bounced last week, refuse a send from a domain that fails authentication, or tell you the message was delivered. With a bare relay those are yours to build. The API versus SMTP comparison goes through the trade in full; the Django stack page is the short version. The rest of this page is the Django email API integration end to end: the key, the send, the task, the templates and the webhook.

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

Coming soon: the rasket package is not published yet. Until it is, two packages do the job: requests for the API calls, and svix for the webhook section later. Neither has a heavy dependency tree. Then put the key where Django puts configuration.

# settings.pyimport os
# os.environ[...] rather than .get(): a missing variable fails at# start-up, which is the moment you want to hear about it.RASKET_API_KEY = os.environ["RASKET_API_KEY"]RASKET_WEBHOOK_SECRET = os.environ["RASKET_WEBHOOK_SECRET"]

The subscript rather than .get is deliberate. A key that is missing should stop manage.py runserver with a KeyError, not send None as a bearer token from a worker at three in the morning. Locally the variable comes from your shell or a dotenv file; in production it comes from the host’s own environment. It is never a literal in settings.py, and it is never committed.

The send is one POST /emails, and a small helper keeps the key, the headers and the rate-limit answer in one place. Every later sample calls it.

# orders/rasket.pyimport requestsfrom django.conf import settings
URL = "https://api.rasket.com/emails"

class RateLimited(Exception):    def __init__(self, retry_after):        super().__init__(f"rate limited for {retry_after}s")        self.retry_after = retry_after

def send_email(message, idempotency_key):    response = requests.post(        URL,        headers={            "authorization": f"Bearer {settings.RASKET_API_KEY}",            "content-type": "application/json",            # Required: a request without one is refused.            "user-agent": "acme-billing/1.0",            "idempotency-key": idempotency_key,        },        json=message,        timeout=10,    )    if response.status_code == 429:        raise RateLimited(int(response.headers["retry-after"]))    response.raise_for_status()    return response.json()["id"]

# orders/views.pyfrom django.http import JsonResponse
from .rasket import send_email

def send_shipping_email(request, order_id):    email_id = send_email(        {            "from": "Acme <orders@send.acme.example>",            "to": ["ronald.williams@example.com"],            "subject": "Your order has shipped",            "html": "<p>Order 1042 shipped today.</p>",        },        # Same key on every retry of this order.        idempotency_key=f"order-{order_id}",    )
    return JsonResponse({"id": email_id})

Three details carry the weight. The request names your application in its user-agent, because a request without one is refused, and a name of your own is what lets support tell your billing worker from your web process. The timeout turns a hung connection into an error you can act on. And the idempotency_key is derived from the order, which is the thing that caused the send, rather than generated fresh. A repeat of a keyed request inside 24 hours returns the original response and sends nothing; the idempotency guide has the exact rules.

A Celery task is the right home for a send in Django: it already has retries, backoff and a worker that is not your web process. The only thing to get right is which failures to retry, and with what key.

# orders/tasks.pyimport requestsfrom celery import shared_task
from .rasket import RateLimited, send_email

@shared_task(    bind=True,    autoretry_for=(requests.ConnectionError, requests.Timeout),    retry_backoff=True,    retry_backoff_max=600,    retry_jitter=True,    max_retries=5,)def send_shipping_email(self, order_id):    try:        return send_email(            {                "from": "Acme <orders@send.acme.example>",                "to": ["ronald.williams@example.com"],                "subject": "Your order has shipped",                "html": "<p>Order 1042 shipped today.</p>",            },            # The SAME key on every attempt. A retry after a timeout            # replays the first answer instead of sending twice.            idempotency_key=f"order-{order_id}",        )    except RateLimited as error:        raise self.retry(countdown=error.retry_after)    # Any other 4xx raises HTTPError: it will fail the same way next time.

The decorator does most of the work. autoretry_for names the one kind of failure that is safe to retry blindly: a ConnectionError or a Timeout means nothing answered, so you do not know whether the message went. retry_backoff spaces the attempts out, and retry_jitter stops a hundred tasks retrying in the same second. Celery’s task guide documents each option.

The comment inside the call is the reason the whole thing is safe. Because every attempt sends order-1042 as its key, an attempt that timed out after the API had in fact accepted the message gets the original response back rather than a second email. Without that, backoff is a machine for sending duplicates politely. A 4xx is the other case: the API answered and said no. A validation error will say no identically forever, so the task lets it fail; only a 429 is worth waiting on, and its retry-after header carries the number of seconds to wait. The limit is ten requests a second per team, shared by every key, and the rate limits guide has the headers and the error body.

# orders/views.pyfrom django.db import transaction
from .tasks import send_shipping_email

def ship(request, order_id):    order = mark_shipped(order_id)    # Enqueue after the commit, so a worker that starts at once    # finds the row it was told about.    transaction.on_commit(lambda: send_shipping_email.delay(order.id))    return JsonResponse({"status": "shipped"})

transaction.on_commit is the small thing that avoids a large confusion. Without it, a fast worker can pick the task up before the view’s transaction commits and find no order, or the old state of one.

You have two template engines to choose from, and they suit different situations. Django already knows how to turn a context into HTML, and an API call is happy to carry whatever it produces. Rasket also stores templates of its own, rendered on the API side from variables you pass.

from django.template.loader import render_to_string
# 1. Django renders the HTML, the API sends it.html = render_to_string("orders/shipped.html", {"order": order})
send_email(    {        "from": "Acme <orders@send.acme.example>",        "to": ["ronald.williams@example.com"],        "subject": f"Order {order.number} has shipped",        "html": html,    },    idempotency_key=f"order-{order.id}",)
# 2. A published Rasket template renders on the API side.#    No html or text in the request; from and subject can#    come from the template as well.send_email(    {        "to": ["ronald.williams@example.com"],        "template": {            "id": "order-shipped",            "variables": {"order_number": order.number, "carrier": order.carrier},        },    },    idempotency_key=f"order-{order.id}",)

• Render in Django when the markup depends on your models, your translations or logic a simple substitution cannot express. render_to_string gives you a string; the request carries it as html. Add a text part when you can.
• Send a Rasket template when someone other than a developer edits the copy, or when you want every send to record which version it used. The request sets template with an id or alias and a variables map, and leaves html and text out — the two cannot be combined. The template must be published, every declared variable is a string or a number, and a key you do not pass takes its fallback.

Either way the idempotency key is the same, because the send is the same send. What changes is where the body is rendered.

A send returns 200 when the message is accepted and recorded, not when it is delivered. Delivery, bounces, complaints and opens arrive later as signed HTTPS requests to a URL you register. In Django that URL is a view with three properties the framework will fight you on.

# hooks/views.py — pip install svixfrom django.conf import settingsfrom django.http import HttpResponse, HttpResponseBadRequestfrom django.views.decorators.csrf import csrf_exemptfrom django.views.decorators.http import require_POSTfrom svix.webhooks import Webhook, WebhookVerificationError
from .tasks import record_event

@csrf_exempt@require_POSTdef rasket_webhook(request):    # request.body is the raw bytes. Never json.loads() first:    # the signature is over what arrived, not what you re-serialise.    try:        event = Webhook(settings.RASKET_WEBHOOK_SECRET).verify(            request.body, dict(request.headers)        )    except WebhookVerificationError:        return HttpResponseBadRequest("invalid signature")
    # Answer first, work later. The task dedupes on svix-id, so a    # redelivery of the same event is a no-op.    record_event.delay(request.headers["svix-id"], event)    return HttpResponse(status=200)

• It is CSRF exempt. The CSRF middleware rejects any POST without a token it issued, and a webhook sender has none. @csrf_exempt turns the check off for this one view; the signature is the authentication instead.
• It reads request.body first. The signature is an HMAC over the raw bytes. Parsing the JSON and serialising it again produces a different string, and a different string has a different signature. Read the bytes, verify, then use the parsed event the verifier returns.
• It answers fast. A handler that does its work inline and times out will be sent the same event again. Hand the event to a task keyed on svix-id, answer 200, and let the task dedupe.

Wire it in urls.py with path("hooks/rasket", rasket_webhook) and register the same path in the dashboard. The verifier checks the timestamp as well as the digest, so a request replayed more than five minutes later is refused too. The webhooks article covers retries, ordering and replay, and the events reference lists every event a send can produce.