ZetCode

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.

config/settings.py
...
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.

config/urls.py
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.

config/views.py
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.

config/templates/home.html
<!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.

config/settings.py
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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Django tutorials.