Why?

Some projects may want to sent emails over multiple SMTP relays or smarthosts. Examples are sites running on multiple domains, e.g. info@example.com and info@example.org. It may be possible to use the same SMTP credentials for each sender address but if that isn’t possible django-email-hosts may be a good solution for the problem.

Usage

• Install: pip install django-email-hosts

• Configure: Add the EMAIL_HOSTS setting

• Use: Always explicitly use the SMTP connection returned by email_hosts.backends.get_connection

EMAIL_HOSTS

The keys of the EMAIL_HOSTS dictionary are defined by you and there’s no deeper meaning to them. The values are DSNs inspired by dj-email-url DSNs.

An example configuration (which is possibly nonsensical) looks like this:

EMAIL_HOSTS = {
    "sendgrid": "submission://USER:PASSWORD@smtp.sendgrid.com?_default_from_email=info@example.com",
    "mailgun": "submission://USER:PASSWORD@smtp.mailgun.com?_default_from_email=info@example.org",
}

This configuration creates two SMTP backends, one using sendgrid and one using mailgun. The _default_from_email is completely optional. If the email message’s from_email isn’t set (resp. is equal to the DEFAULT_FROM_EMAIL setting) it automatically defaults to the per-backend value.

Django 6.1 and MAILERS

Django 6.1 introduced the MAILERS setting for configuring several email backends. email_hosts.mailers converts the EMAIL_HOSTS dictionary into MAILERS entries which support the per-backend _default_from_email:

from email_hosts import mailers

MAILERS = {
    "default": {"BACKEND": "django.core.mail.backends.smtp.EmailBackend", ...},
    **mailers(EMAIL_HOSTS),
}

Then, send emails using Django’s own API, e.g. EmailMessage(...).send(using="sendgrid"). get_connection below and the sendtestemailhosts management command use MAILERS automatically when the setting is defined.

email_hosts.backends.get_connection

The get_connection function expects a single key for the EMAIL_HOSTS setting above. Sending a single email using an explicit connection may look as follows, using the settings from above:

from django.core.mail import EmailMessage
from email_hosts.backends import get_connection

EmailMessage(
    "Hello",
    "World",
    to=["recipient@example.com"],
    connection=get_connection("sendgrid"),
).send()

get_connection currently silently returns the default email backend if the key doesn’t exist in the EMAIL_HOSTS dictionary.

sendtestemailhosts management command

The sendtestemailhosts management command allows you to test your email configurations by sending test emails through a specific backend.

Usage:

python manage.py sendtestemailhosts <backend> <email> [<email> ...]

The command takes a backend key from your EMAIL_HOSTS configuration as the first argument, followed by one or more recipient email addresses.

Example using the configuration above:

python manage.py sendtestemailhosts sendgrid test@example.com
python manage.py sendtestemailhosts mailgun admin@example.org recipient@example.com

The test email will include the hostname and timestamp in the subject line, and a simple confirmation message in the body.