.. RemovedInDjango70Warning: Remove this file and references to it. .. _migrating-to-mailers: ========================== Migrating email to mailers ========================== Django 6.1 introduced the :setting:`MAILERS` setting, replacing :setting:`EMAIL_BACKEND` and several other ``EMAIL_*`` settings. It also introduced :data:`.mail.mailers` for obtaining configured email backend instances, replacing :func:`.mail.get_connection`. A new ``using`` argument replaces the earlier ``connection`` in Django functions that send email. This guide provides details on migrating existing projects to the new mailers functionality. All Django projects that send email should: * If using any third-party packages that send email, :ref:`verify their compatibility ` with :setting:`MAILERS` before making other changes. * :ref:`Update email-related settings `. * Run with deprecation warnings enabled (see :ref:`howto/upgrade-version:Resolving deprecation warnings`) to identify other code needing updates. .. note:: Running tests may not identify all relevant deprecations. Test suites often use a non-functional email backend (such as the memory backend that Django :ref:`substitutes during tests `), so can miss deprecation warnings that are only issued from the production email configuration. Consider running with deprecation warnings enabled in production to catch those deprecations. Or carefully review your code (including third-party packages) for use of any deprecated email features. Other updates are needed only for projects or reusable Django libraries that use these specific features: * :ref:`migrating-to-mailers-get-connection` * :ref:`migrating-to-mailers-fail-silently` * :ref:`migrating-to-mailers-email-backends` * :ref:`migrating-to-mailers-auth` * :ref:`migrating-to-mailers-adminemailhandler` .. deprecated:: 6.1 The following settings and functions will be removed in Django 7.0: * :setting:`EMAIL_BACKEND`, :setting:`EMAIL_FILE_PATH`, :setting:`EMAIL_HOST`, :setting:`EMAIL_HOST_PASSWORD`, :setting:`EMAIL_HOST_USER`, :setting:`EMAIL_PORT`, :setting:`EMAIL_SSL_CERTFILE`, :setting:`EMAIL_SSL_KEYFILE`, :setting:`EMAIL_TIMEOUT`, :setting:`EMAIL_USE_SSL`, :setting:`EMAIL_USE_TLS` * :func:`.mail.get_connection` and the ``connection`` arguments to mail functions * The ``fail_silently`` argument to :func:`.send_mail`, :func:`.send_mass_mail`, :func:`.mail_admins`, :func:`.mail_managers`, and :meth:`.EmailMessage.send` * The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail` and :func:`.send_mass_mail` * The ``email_backend`` argument to :class:`.AdminEmailHandler` .. _migrating-to-mailers-settings: Migrating settings ------------------ Often, the only change needed to migrate to mailers is updating email-related settings. In your project's settings, define a :setting:`MAILERS` dict with a ``"default"`` entry matching the earlier ``EMAIL_*`` settings:: MAILERS = { "default": { "BACKEND": ..., # value of EMAIL_BACKEND setting "OPTIONS": { # values from other deprecated EMAIL_* settings ..., }, }, } For example, to update these settings:: EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend" EMAIL_HOST = "mail.example.net" EMAIL_USE_TLS = True EMAIL_PORT = 587 EMAIL_HOST_USER = "user@example.net" EMAIL_HOST_PASSWORD = "password" use:: MAILERS = { "default": { "BACKEND": "django.core.mail.backends.smtp.EmailBackend", "OPTIONS": { "host": "mail.example.net", "use_tls": True, # port is not needed: it defaults to 587 with use_tls True. "username": "user@example.net", "password": "password", }, }, } .. _deprecated-email-settings: The complete list of deprecated ``EMAIL_*`` settings and where they should be moved in a :setting:`MAILERS` configuration is: * :setting:`EMAIL_BACKEND` becomes ``"BACKEND"``. If your settings didn't define :setting:`!EMAIL_BACKEND`, the default value was ``"django.core.mail.backends.smtp.EmailBackend"`` (which is also the default if a :setting:`MAILERS` configuration doesn't specify the ``"BACKEND"``). * :setting:`EMAIL_FILE_PATH` becomes ``"file_path"`` in ``"OPTIONS"`` (with ``"BACKEND"`` set to ``"django.core.mail.backends.filebased.EmailBackend"``). * :setting:`EMAIL_HOST` becomes ``"host"`` in ``"OPTIONS"``. A ``"host"`` is required for the SMTP email backend. If your settings didn't define ``EMAIL_HOST``, set ``"host"`` to ``"localhost"`` (the default value for the deprecated setting). * :setting:`EMAIL_HOST_PASSWORD` becomes ``"password"`` in ``"OPTIONS"``. * :setting:`EMAIL_HOST_USER` becomes ``"username"`` in ``"OPTIONS"``. (Note ``"username"`` doesn't quite follow the naming pattern for the other deprecated settings.) * :setting:`EMAIL_PORT` becomes ``"port"`` in ``"OPTIONS"``. It can be omitted if the connection uses the default port for its security (465 for SSL, 587 for TLS, or 25 for an unsecured SMTP connection). * :setting:`EMAIL_SSL_CERTFILE` becomes ``"ssl_certfile"`` in ``"OPTIONS"``. * :setting:`EMAIL_SSL_KEYFILE` becomes ``"ssl_keyfile"`` in ``"OPTIONS"``. * :setting:`EMAIL_TIMEOUT` becomes ``"timeout"`` in ``"OPTIONS"``. * :setting:`EMAIL_USE_SSL` becomes ``"use_ssl"`` in ``"OPTIONS"``. * :setting:`EMAIL_USE_TLS` becomes ``"use_tls"`` in ``"OPTIONS"``. For third-party or custom email backends, the available ``"OPTIONS"`` depend on the backend. Refer to the third-party documentation, or for custom backends see :ref:`migrating-to-mailers-email-backends` below. The :ref:`topic-email-configuration` topic has more information on the ``MAILERS`` setting and additional configuration examples. .. _migrating-to-mailers-third-party: Reusable library readiness -------------------------- In most cases, third-party packages that send email through Django will continue working with projects whose settings have been upgraded to use :setting:`MAILERS`. (If they use any deprecated mail features, those will of course cause deprecation warnings.) There are two deprecated features that are *not* supported when :setting:`MAILERS` is defined in a project's settings: * Trying to access any of the deprecated ``EMAIL_*`` settings on ``django.conf.settings`` (e.g., checking ``settings.EMAIL_BACKEND`` or using ``settings.EMAIL_HOST_USER``). * Calling :func:`mail.get_connection("path.to.EmailBackend") <.mail.get_connection>` with a specific backend path. (Other arguments to ``get_connection()`` are still supported, and will simply issue deprecation warnings when :setting:`MAILERS` is defined.) If a third-party package does either of those, projects that use it will not be able to change to the :setting:`MAILERS` setting until the package has been updated. Solving "not available when MAILERS is defined" errors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If either of these errors are raised within a third-party package, that indicates it is not compatible with the :setting:`MAILERS` setting: * :samp:`AttributeError: "The {name} setting is not available when MAILERS is defined"` where *name* is :setting:`EMAIL_BACKEND`, :setting:`EMAIL_HOST`, or one of the other deprecated settings. * ``RuntimeError: get_connection(backend, ...) is not supported with MAILERS.`` If you see these errors, check if a newer version of that dependency is available. If not (and if there are no alternatives to that package), you will need to remove :setting:`MAILERS` from your settings and replace it with the equivalent :ref:`deprecated email settings ` until the package has been updated. If those errors are coming from your own code, see the other sections in this migration guide for recommended updates. .. _migrating-to-mailers-get-connection: Replacing ``get_connection()`` and ``connection`` arguments ----------------------------------------------------------- The replacements for the deprecated :func:`.mail.get_connection` function and ``connection`` arguments to other mail functions depend on how and why the connections are being created: * ``get_connection()`` called with no arguments Replace with :data:`.mailers.default`. For example, update this code:: connection = mail.get_connection() connection.send_messages([email1, email2]) To:: connection = mail.mailers.default connection.send_messages([email1, email2]) Note that ``mailers.default`` *is* the default for Django's mail-sending functions. Code like this:: mail.send_mail(..., connection=mail.get_connection()) can be updated to:: mail.send_mail(...) # No connection arg needed. * ``get_connection(fail_silently=True)`` See :ref:`migrating-to-mailers-fail-silently`. * ``get_connection(...)`` called with any other arguments Define a custom :setting:`MAILERS` configuration with the desired backend and options. Then refer to it in the ``using`` argument when sending mail, or obtain an email backend instance from :data:`.mail.mailers` with the configuration name. For example, to upgrade this code:: connection = mail.get_connection( "path.to.custom.EmailBackend", option1=True, option2="value" ) mail.send_mail(..., connection=connection) connection.send_messages([email1, email2]) Define a custom :setting:`MAILERS` configuration in your settings:: MAILERS = { "default": {...}, "custom": { "BACKEND": "path.to.custom.EmailBackend", "OPTIONS": { "option1": True, "option2": "value", }, }, } And then use it like this:: mail.send_mail(..., using="custom") mail.mailers["custom"].send_messages([email1, email2]) .. _migrating-to-mailers-fail-silently: Replacing ``fail_silently`` --------------------------- The deprecated ``fail_silently`` arguments to :func:`.send_mail`, :func:`.send_mass_mail`, :func:`.mail_admins`, :func:`.mail_managers`, and :meth:`.EmailMessage.send` can be replaced in several ways. Existing usage seems to have several different expectations for the behavior, many of which don't match the actual (and email backend-dependent) implementation. Consider removing ``fail_silently`` entirely if there is not a specific need for it. Calls with ``fail_silently=True`` should be updated with one of these options, depending on the caller's intent: * To send a message if email has been configured but avoid raising an error if it hasn't (e.g., in a reusable library), wrap the send call in ``try:`` / ``except mail.MailerDoesNotExist: pass``. * To ignore *all* exceptions (e.g., to avoid cascading failures in an error handler that sends mail), wrap the send call in ``try:`` / ``except Exception: pass``. * To ignore only SMTP-related errors, wrap the send call in ``try`` / ``except OSError: pass``. Note that this ignores both transient network glitches *and* SMTP configuration problems (just like the existing SMTP email backend ``fail_silently`` implementation). * To ignore end user typos in ``to`` addresses and other delivery problems, remove the ``fail_silently`` argument. Recipient errors are not generally detected at send time, so using ``fail_silently`` for this purpose doesn't accomplish anything and could mask other problems like configuration errors. (In *local delivery* configurations, SMTP servers may report some recipient errors at send time. If you are using ``fail_silently`` specifically to ignore those errors, consider instead intercepting :exc:`~.smtplib.SMTPRecipientsRefused` and/or :exc:`~.smtplib.SMTPResponseException`\ s with particular ``smtp_code`` values as a more precise filter.) * To create an email configuration that ignores certain backend-dependent errors and reuse it for multiple sending operations, create a custom :setting:`MAILERS` configuration with ``"fail_silently": True`` in the :setting:`"OPTIONS" `, then refer to that configuration with ``using`` in the send call. Calls with ``fail_silently=False`` should be updated to remove the ``fail_silently`` arg, as that is the default. .. _migrating-to-mailers-email-backends: Migrating custom email backends ------------------------------- Custom ``EmailBackend`` implementations may need to be updated for compatibility with mailers. * In the backend's ``__init__()`` method, accept explicit keyword arguments for all configuration options that can come from :setting:`"OPTIONS" `. Backends that use custom settings for configuration can continue to do so (or not, as they choose), but keyword arguments should take precedence over settings. * Accept variable ``**kwargs`` and pass them to superclass init. (This will include a new ``alias`` argument which must be passed to the superclass.) Ensure that any ``**kwargs`` used by the backend are *not* passed to superclass init, as that would generate an ``InvalidMailer`` error for unknown OPTIONS. * Backends must now handle ``fail_silently`` themselves, if they want to support it. There is no requirement to support ``fail_silently``, and backends that don't offer it should eliminate that keyword argument. (Do not pass an explicit ``fail_silently`` arg to superclass init.) * Do not accept variable positional ``*args`` or pass them to superclass init. The ``BaseEmailBackend`` superclass now initializes an ``alias`` attribute. This is useful for error messages (e.g., ``raise InvalidMailer(f"Bad host {host}", alias=self.alias)``), but should not be used for accessing ``settings.MAILERS`` directly. All OPTIONS for a mailer configuration are passed to backend init as keyword arguments. For reusable libraries that want to support compatibility with deprecated mail functions and settings, or that support older Django versions: * A backend can detect it is being initialized without :setting:`MAILERS` by checking if ``self.alias is None``. (Django's built-in backends check this to decide whether deprecated settings should be used.) Libraries supporting older Django versions will need to use ``getattr(self, "alias", None)``. * Backends that borrow Django's SMTP email settings like :setting:`EMAIL_HOST` must *not* try to access them when :setting:`MAILERS` is in use (``self.alias is not None``), as this will cause a "not available when MAILERS is defined" ``AttributeError``. * Libraries supporting multiple Django versions can identify support for mailers with either ``hasattr(django.core.mail, "mailers")`` or ``django.VERSION >= (6, 1)``. .. _migrating-to-mailers-auth: Replacing ``auth_user`` and ``auth_password`` --------------------------------------------- The deprecated ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail` and :func:`.send_mass_mail` can be replaced by defining a custom :setting:`MAILERS` configuration with ``"username"`` and ``"password"`` :setting:`"OPTIONS" `, and refer to that configuration with the ``using`` argument when sending mail. For example, to upgrade:: mail.send_mail(..., auth_user="admin", auth_password="admin-password") Add a custom :setting:`MAILERS` configuration in your settings:: MAILERS = { # Existing default configuration. "default": { "OPTIONS": { "host": "smtp.example.com", "username": "default-user", "password": "default-password", }, }, # Duplicate the default configuration, changing the auth. "admin-config": { "OPTIONS": { "host": "smtp.example.com", "username": "admin", "password": "admin-password", }, }, } And then refer to it when sending:: mail.send_mail(..., using="admin-config") .. _migrating-to-mailers-adminemailhandler: Updating AdminEmailHandler ``email_backend`` -------------------------------------------- The deprecated ``email_backend`` argument to the logging :class:`.AdminEmailHandler` can be replaced with a custom :setting:`MAILERS` configuration, referring to it with the ``using`` argument. For example, if your settings include:: LOGGING = { # ... "handlers": { "mail_admins": { "class": "django.utils.log.AdminEmailHandler", "email_backend": "third.party.EmailBackend", }, }, # ... } Replace that with:: LOGGING = { # ... "handlers": { "mail_admins": { "class": "django.utils.log.AdminEmailHandler", "using": "admin-logging", # defined in MAILERS }, }, # ... } MAILERS = { "default": {...}, "admin-logging": { "BACKEND": "third.party.EmailBackend", }, }