Tester les emails Django en local sur votre Mac

Interceptez les emails de votre app Django avec un serveur SMTP local sur Mac. Un bloc de paramètres, une commande de test, et chaque email s’affiche aussitôt.

Le backend console de Django affiche les emails dans votre terminal, ce qui suffit jusqu’au jour où vous devez voir la version HTML ou vérifier une pièce jointe. Avec Mailbox, Django envoie de vrais messages SMTP à un serveur sur votre Mac, et chaque email s’affiche avec son rendu complet — HTML, texte brut, en-têtes et pièces jointes. Rien n’est livré à de vrais destinataires.

1. Démarrez un serveur dans Mailbox

Ouvrez Mailbox. Au premier lancement, l’app crée un serveur sur le port 2525 — vérifiez qu’il est bien démarré. Si vous préférez ajouter un autre serveur, Mailbox lui attribue un port libre ; utilisez alors ce port dans les étapes suivantes.

2. Modifiez vos paramètres

Django 6.1 a remplacé les paramètres EMAIL_* par un paramètre unique, MAILERS, que les nouveaux projets définissent déjà avec le backend console. Modifiez ce bloc dans vos paramètres de développement :

MAILERS = {
    "default": {
        "BACKEND": "django.core.mail.backends.smtp.EmailBackend",
        "OPTIONS": {"host": "127.0.0.1", "port": 2525},
    },
}

Indiquez le port explicitement — sans TLS, Django utilise le port 25 par défaut. N’ajoutez pas de paramètres EMAIL_* à côté de MAILERS : Django refuse de démarrer si les deux sont définis.

Django 6.0 et versions antérieures

Les projets sans MAILERS utilisent les paramètres classiques (qui fonctionnent toujours sur 6.1, avec un avertissement de dépréciation) :

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "127.0.0.1"
EMAIL_PORT = 2525
EMAIL_USE_TLS = False
EMAIL_USE_SSL = False

Dans les deux cas, ne définissez ni nom d’utilisateur ni mot de passe : Mailbox ne prend pas en charge l’authentification SMTP, et Django échoue avec SMTPNotSupportedError s’il tente de s’authentifier.

3. Envoyez un email de test

Django fournit une commande d’administration prévue exactement pour ça :

python manage.py sendtestemail test@example.com

Ou depuis python manage.py shell :

from django.core.mail import send_mail

send_mail("Hello from Django", "It works!", None, ["test@example.com"])

Les deux apparaissent immédiatement dans Mailbox. Les emails de réinitialisation de mot de passe, les rapports d’erreur de mail_admins et vos propres EmailMultiAlternatives suivent le même chemin.

Exécuter Django dans Docker

Dans un conteneur, 127.0.0.1 désigne le conteneur. Utilisez plutôt l’adresse de votre Mac — "host": "host.docker.internal" dans MAILERS, ou :

EMAIL_HOST = "host.docker.internal"

Si le conteneur ne parvient toujours pas à se connecter, activez Autoriser l’accès réseau dans Mailbox (Réglages → Général) et redémarrez le serveur : il acceptera alors les connexions venant de l’extérieur de l’interface loopback.

Dépannage

  • ConnectionRefusedError — le serveur Mailbox n’est pas démarré, ou EMAIL_PORT ne correspond pas.
  • ImproperlyConfigured: Deprecated email settings are not allowed when MAILERS is defined — supprimez les paramètres EMAIL_* et configurez uniquement MAILERS.
  • Les emails s’affichent toujours dans le terminal — un autre module de paramètres utilise encore le backend console ; vérifiez vers quel module pointe DJANGO_SETTINGS_MODULE.
  • Les tâches Celery n’envoient rien — les emails envoyés depuis des tâches nécessitent un worker en cours d’exécution.

Que vérifier ensuite

Avec de vrais emails sous les yeux, lancez la vérification de compatibilité HTML pour repérer le CSS que des clients de messagerie comme Outlook n’afficheront pas, et utilisez l’aperçu mobile pour contrôler vos templates responsive. Si vous testez plusieurs projets, Mailbox Pro vous permet d’attribuer à chacun son propre serveur et son propre port, pour que leurs emails restent séparés.

Autres guides