Skip to main content
mailkube-django ships a Django email backend, so everything that already sends mail in your project, from send_mail to a password reset, goes out through mailkube once one setting changes. It is a thin adapter over the Python SDK, which owns the API surface, the errors and the signature verification. Requires Python 3.12+ and Django 5.2+.

Install

Configure

The whole integration is the backend setting plus the key:
settings.py
MAILKUBE_TIMEOUT is the one other setting. Anything left unset falls through to the SDK, which reads MAILKUBE_API_KEY from the environment. The key can stay out of Django settings entirely. Adding "mailkube_django" to INSTALLED_APPS is optional. It registers two manage.py check warnings, one for a missing API key and one for selecting the Anymail backend without the extra installed, and nothing else. There are no models and no migrations.

Send

Django loads the backend from its dotted path, so every send_mail and every EmailMessage.send() in the project keeps its existing code and now goes through mailkube:
send() returns a count of accepted messages, the way every Django backend does, so this path reports no message id back. When you need the id, send through the SDK client below.

What the backend cannot carry

EmailMessage models an RFC 5322 message. Tags, topics, templates, scheduling and idempotency keys are not parts of one, and the backend has no slot for them. Reach them with the Python SDK directly; it reads the same MAILKUBE_API_KEY:

The Anymail backend

The distribution ships a second backend for django-anymail users:
settings.py
It carries what Anymail’s message extensions can express: tags, send_at, template_id, merge_global_data (the API’s variables), esp_extra, the pre_send/post_send signals, and per-recipient anymail_status:
Anymail tags are flat strings, so the backend maps each one to a name-only mailkube tag. A feature the API has no equivalent for, such as metadata, raises Anymail’s usual unsupported-feature error rather than being silently dropped. Both backends send through the same SDK and the wire behavior is identical. Pick Anymail when you already use it or want to keep providers swappable.

Receiving webhooks

WebhookView verifies each delivery over the raw request body, then dispatches the webhook_received signal carrying the SDK’s typed event:
settings.py
An event type your installed SDK version does not know arrives as UnknownEvent with its raw data intact. A new platform event never breaks a receiver. A delivery whose signature does not check out gets a 400 and no signal. Receivers run inside the request and a delivery has ten seconds, so enqueue slow work and return. The view answers POST only, and mailkube activates an endpoint only after probing it with GET <url>?hub.mode=subscribe&hub.challenge=<token> and reading the token back. Django’s View dispatches by method, so subclass the package view and add the probe handler:
urls.py
The package view is already CSRF-exempt: the signature is what authenticates a delivery, and it covers the exact bytes received, so keep any middleware that re-encodes request bodies away from this path.

Next steps

Python SDK

The client the backend rides on: scheduled sends, idempotency, async, and the full error hierarchy.

Webhooks

Every event the webhook_received signal can carry, with payloads and retry behavior.