Metadata-Version: 2.5
Name: django-email-hosts
Version: 0.3.0
Summary: Support for several SMTP configurations in a single site
Project-URL: Homepage, https://github.com/feinheit/django-email-hosts/
Author-email: Feinheit AG <dev@feinheit.ch>
License: BSD-3-Clause
License-File: LICENSE
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.9
Requires-Dist: django>=3.2
Requires-Dist: speckenv>=6.3
Provides-Extra: tests
Requires-Dist: coverage; extra == 'tests'
Description-Content-Type: text/x-rst

==============================================================================
django-email-hosts -- Support for several SMTP configurations in a single site
==============================================================================

.. image:: https://github.com/feinheit/django-email-hosts/actions/workflows/tests.yml/badge.svg
    :target: https://github.com/feinheit/django-email-hosts/
    :alt: CI Status


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
<https://github.com/migonzalvar/dj-email-url>`__ DSNs.

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


.. code-block:: python

    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``:

.. code-block:: python

    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:

.. code-block:: python

    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:

.. code-block:: bash

    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:

.. code-block:: bash

    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.
