Django email
last modified November 13, 2026 Python 3.15
Django send email tutorial shows how to send emails in Django. We first use the console backend and then configure an SMTP server, the Mailtrap service. The examples use Django 6.1 and Python 3.15, and the environment is managed with uv.
Django
Django is a high-level Python web framework that encourages rapid development and clean, pragmatic design. It is maintained by the Django Software Foundation. If you are new to the framework, start with the Django introduction article.
Django email
Django ships with the django.core.mail module. The
send_mail() function sends a single message; the
EmailMessage and EmailMultiAlternatives classes cover
attachments and HTML bodies; send_mass_mail() sends several
messages over one connection.
Since Django 6.1, the way messages are delivered is configured with the
MAILERS setting: a dictionary of named mailers, each with a
BACKEND and its OPTIONS. The mailer named
default is used by send_mail(). The older
EMAIL_HOST, EMAIL_PORT, EMAIL_BACKEND
and related settings still work, but they are deprecated and cannot be combined
with MAILERS. The project template generated by
startproject already defines a default mailer that uses the
console backend, which prints messages to the terminal instead of sending them.
That is ideal for development.
Creating the project
In the following example, we create a Django application with a home page that contains a button. The button sends a POST request to a view, which sends a test email.
$ mkdir sendmail $ cd sendmail $ uv init --bare $ uv add django $ uv run django-admin startproject config .
We create a project directory, initialize it with uv, and install Django into a
project-local virtual environment. The last command creates the Django project
inside the current directory; the dot at the end prevents Django from
creating an extra config directory level. All commands are run
with uv run, so there is no need to activate the environment.
Note: The Django way is to put functionality into apps, which
are created with uv run python manage.py startapp. In this
tutorial, we do not use an app to keep the example simple. We focus on sending
an email.
We also create the templates directory where we place our template
files.
$ mkdir config/templates
We create the directory inside the config package.
Project structure
After we add the views.py module and the home.html
template, the project has the following structure; the hidden .venv
directory is not shown.
. ├── config │ ├── asgi.py │ ├── __init__.py │ ├── settings.py │ ├── templates │ │ └── home.html │ ├── urls.py │ ├── views.py │ └── wsgi.py ├── manage.py ├── pyproject.toml └── uv.lock
Settings
Two settings matter in this example: the template directories and the way Django delivers email.
...
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [BASE_DIR / 'config' / 'templates'],
...
]
...
MAILERS = {
'default': {
'BACKEND': 'django.core.mail.backends.console.EmailBackend',
},
}
Inside the settings.py file, we configure the templates directory;
BASE_DIR is a pathlib.Path object, so we can build the
path with the / operator. The MAILERS setting is
already generated by startproject and we leave it unchanged: the
messages are written to the console.
URL configuration
The URL configuration maps request paths to view functions. Django reads the urlpatterns list from top to bottom and calls the first view whose path matches.
from django.contrib import admin
from django.urls import path
from .views import home, send_test_mail
urlpatterns = [
path('admin/', admin.site.urls),
path('', home, name='home'),
path('send/', send_test_mail, name='send_test_mail'),
]
We define the routes. One route shows the home page and the other one calls our
custom send_test_mail view. The module docstring generated by
Django is omitted from the listing.
The views
The views are plain Python functions. Each receives the HttpRequest and returns a response.
from django.core.mail import send_mail
from django.http import HttpResponse
from django.shortcuts import render
from django.views.decorators.http import require_POST
def home(request):
return render(request, 'home.html')
@require_POST
def send_test_mail(request):
sent = send_mail(
'Subject',
'Email message',
'from@example.com',
['to@example.com'],
fail_silently=False,
)
return HttpResponse(f'{sent} message sent')
There are two view functions. The home function renders the home
page. The send_test_mail function calls Django's
send_mail(), which takes the subject, the message, the sender, and
a list of recipients. It returns the number of messages sent, which we put into
the response. The require_POST decorator rejects other HTTP methods
with the status code 405, because sending an email changes the state of the
world and should not be triggered by a simple link or a crawler.
The template
The home page is rendered from a template, which is an HTML file with Django template tags.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Home page</title>
</head>
<body>
<form method="post" action="{% url 'send_test_mail' %}">
{% csrf_token %}
<button type="submit">Send test mail</button>
</form>
</body>
</html>
The home page contains a form with a button that sends the POST request. The
{% csrf_token %} tag adds the hidden field with the CSRF token;
without it, Django rejects the POST request with the status code 403. The
{% url %} tag builds the form action from the route name.
Running the application
We start the development server.
$ uv run python manage.py runserver
We navigate to http://127.0.0.1:8000/ and click the button. The
browser shows the text 1 message sent, and the server terminal prints
the message that the console backend received. The Message-ID and
the date differ from run to run.
Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit MIME-Version: 1.0 Subject: Subject From: from@example.com To: to@example.com Date: Fri, 13 Nov 2026 17:55:06 +0000 Message-ID: <179459250679.195078.7098777926986756061@universum> Email message ------------------------------------------------------------------------------- [13/Nov/2026 17:55:06] "POST /send/ HTTP/1.1" 200 14
Sending with an SMTP server
To deliver the message through a real SMTP server, we change the default mailer to the SMTP backend. In this example, we use the Mailtrap service, which captures test emails in a sandbox inbox instead of delivering them. We need to register an account if we do not have one; there is a free tier. The SMTP credentials are shown in the integration settings of the Mailtrap inbox.
MAILERS = {
'default': {
'BACKEND': 'django.core.mail.backends.smtp.EmailBackend',
'OPTIONS': {
'host': os.environ.get('MAIL_HOST', 'sandbox.smtp.mailtrap.io'),
'port': int(os.environ.get('MAIL_PORT', '2525')),
'username': os.environ.get('MAIL_USER', ''),
'password': os.environ.get('MAIL_PASSWORD', ''),
'use_tls': os.environ.get('MAIL_TLS', '1') == '1',
},
},
}
The OPTIONS dictionary holds the arguments of the SMTP backend:
the host, port, credentials, and the use_tls flag, which enables
STARTTLS. We read them from environment variables so that the credentials do
not end up in the source code; the os module must be imported at the top of settings.py. The default host and port are the Mailtrap
sandbox values; check the exact values in your inbox settings, because the
service may change them. The same configuration works with any SMTP server; we
tested it against a local debugging SMTP server on port 1025 without TLS.
$ export MAIL_HOST=localhost MAIL_PORT=1025 MAIL_TLS=0
$ uv run python manage.py shell --no-imports -c "from django.core.mail import send_mail; print(send_mail('Subject', 'Email message', 'from@example.com', ['to@example.com']))"
1
Source
Django documentation: Sending email
In this article we have sent an email from a Django view with send_mail(), first with the console backend and then through an SMTP server configured with MAILERS. The first steps with the framework are covered in Django introduction.
Author
List all Django tutorials.