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 everysend_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
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:
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
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
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.