Django 6.1 introduces the MAILERS setting, replacing
EMAIL_BACKEND and several other EMAIL_* settings. It also
introduces mail.mailers for obtaining configured email backend
instances, replacing mail.get_connection(). A new using argument
replaces the earlier connection in Django functions that send email.
The older functionality and settings are still available, but are deprecated and will be removed in Django 7.0. 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, verify their
compatibility with MAILERS
before making other changes.
Run with deprecation warnings enabled (see Resolving deprecation warnings) to identify other code needing updates.
Note
Test suites often use a non-functional email backend, such as the memory backend that Django automatically substitutes during tests. As a result, running tests won’t uncover deprecations that only appear when sending email in production.
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 that will change in Django 7.0.
Other updates are needed only for projects or reusable Django libraries that use these specific features:
Often, the only change needed to migrate to mailers is updating email-related
settings. In your project’s settings, define a 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",
},
},
}
The complete list of deprecated EMAIL_* settings and where they should be
moved in a MAILERS configuration is:
EMAIL_BACKEND becomes "BACKEND". If your settings didn’t
define EMAIL_BACKEND, the default value was
"django.core.mail.backends.smtp.EmailBackend" (which is also the default
if a MAILERS configuration doesn’t specify the "BACKEND").
EMAIL_FILE_PATH becomes "file_path" in "OPTIONS" (with
"BACKEND" set to "django.core.mail.backends.filebased.EmailBackend").
EMAIL_HOST becomes "host" in "OPTIONS". If your settings
didn’t define EMAIL_HOST, the default value was "localhost"
and you must add "host": "localhost" to the "OPTIONS" for an SMTP
mailer configuration.
EMAIL_HOST_PASSWORD becomes "password" in "OPTIONS".
EMAIL_HOST_USER becomes "username" in "OPTIONS".
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).
EMAIL_SSL_CERTFILE becomes "ssl_certfile" in "OPTIONS".
EMAIL_SSL_KEYFILE becomes "ssl_keyfile" in "OPTIONS".
EMAIL_TIMEOUT becomes "timeout" in "OPTIONS".
EMAIL_USE_SSL becomes "use_ssl" in "OPTIONS".
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
Migrating custom email backends below.
The Configuring email topic has more information on the
MAILERS setting and additional configuration examples.
In most cases, third-party packages that send email through Django will
continue working with projects whose settings have been upgraded to use
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
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 mail.get_connection("path.to.EmailBackend") with a specific backend path. (Other uses of
get_connection() are still allowed, and will issue deprecation warnings.)
If a third-party package does either of those, projects that use it cannot
upgrade to the MAILERS setting until the package has been updated.
If either of these errors are raised within a third-party package, that
indicates it is not compatible with the MAILERS setting:
AttributeError: "The name setting is not available when MAILERS is
defined" where name is EMAIL_BACKEND, 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 MAILERS from your settings and replace it with the
equivalent deprecated email settings until
the package has been updated.
get_connection() and connection arguments¶mail.get_connection() is deprecated in Django 6.1, as is the
connection argument for passing backend instances directly to mail
functions.
The replacement for get_connection() depends on how it is being called:
get_connection() called with no arguments
Replace with 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)
get_connection(...) called with any other arguments
Define a custom 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 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 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])
fail_silently¶The fail_silently arguments to send_mail(), send_mass_mail(),
mail_admins(), mail_managers(), and EmailMessage.send()
are deprecated.
Handling of fail_silently varies depending on the email backend. A survey
of its use suggested that callers have several different expectations for its
behavior, many of which don’t match the actual backend implementations.
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), 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
backend fail_silently handling).
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 certain local delivery configurations, SMTP servers may report some
recipient errors at send time. Intercept
SMTPRecipientsRefused and/or
SMTPResponseExceptions with particular smtp_code
values to detect those cases.)
To create an email configuration that ignores certain backend-dependent
errors and reuse it for multiple sending operations, create a custom
MAILERS configuration with "fail_silently": True in the
"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.
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 "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 defines a self.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 (similar to Django’s built-in email backends):
A backend can detect it is being initialized without 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 EMAIL_HOST
must not try to access them when 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).
auth_user and auth_password¶The auth_user and auth_password arguments to mail.send_mail()
and mail.send_mass_mail() are deprecated. To replace them, define a
custom MAILERS configuration with "username" and "password"
"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 MAILERS configuration in your settings:
MAILERS = {
"default": {
"OPTIONS": {
"host": "smtp.example.com",
"username": "default-user",
"password": "default-password",
},
},
"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")
email_backend¶The email_backend argument to the logging AdminEmailHandler is
deprecated. Replace it with a custom MAILERS configuration and refer
to that configuration 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",
},
}
May 13, 2026