Flask-Mail (Sending Emails)

Many apps need email:

• password reset
• email verification
• notifications

Flask-Mail is a popular extension.

Install

bash

pip install Flask-Mail

Basic configuration

python

app.config.update(
    MAIL_SERVER="smtp.gmail.com",
    MAIL_PORT=587,
    MAIL_USE_TLS=True,
    MAIL_USERNAME=os.environ.get("MAIL_USERNAME"),
    MAIL_PASSWORD=os.environ.get("MAIL_PASSWORD"),
)

Then:

python

from flask_mail import Mail
 
mail = Mail(app)

Sending an email

python

from flask_mail import Message
 
msg = Message(
    subject="Welcome",
    sender="noreply@example.com",
    recipients=["user@example.com"],
    body="Hello from Flask!",
)
mail.send(msg)

Production tips

• Don’t send emails synchronously inside web requests (slow)
• Use background jobs (Celery/RQ) for sending
• Use environment variables for credentials
• Prefer transactional email providers (SendGrid/Mailgun)

Configuration is the whole setup

config.py

app.config.update(
    MAIL_SERVER="smtp.example.com",
    MAIL_PORT=587,
    MAIL_USE_TLS=True,
    MAIL_USERNAME=os.environ["MAIL_USERNAME"],
    MAIL_PASSWORD=os.environ["MAIL_PASSWORD"],   # never in the source
    MAIL_DEFAULT_SENDER="bot@example.com",
)
mail = Mail(app)

send.py

msg = Message("Welcome", recipients=["ada@example.com"])
msg.body = "Plain text body"
msg.html = "<p>HTML body</p>"
mail.send(msg)

MAIL_DEFAULT_SENDER fills in From when a message does not set one — measured, the captured message came back with sender='bot@example.com' without it being passed.

Test without sending anything

record.py

app.config["MAIL_SUPPRESS_SEND"] = True
 
with mail.record_messages() as outbox:
    send_welcome_email(user)
    assert len(outbox) == 1
    assert outbox[0].subject == "Welcome"
    assert outbox[0].recipients == ["ada@example.com"]

Measured: one message captured, with subject, sender, recipients and both bodies intact — and no SMTP connection opened. This is how the rest of this page was verified, and it is how email should be tested. A suite that really sends mail is slow, flaky, and eventually mails a real person.

diagram Diagram mermaid

  flowchart TD
  S["mail.send(msg)"] --> Q{"MAIL_SUPPRESS_SEND?"}
  Q -->|"True"| R["recorded in the outbox
nothing leaves the machine"]
  Q -->|"False"| C["open an SMTP connection"]
  C --> W["wait for the server"]
  W --> D["delivered, or an exception"]

What is actually transmitted

measured, msg.as_string()

Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: Subject line
From: bot@example.com
To: a@b.co
Date: Sun, 09 Aug 2026 19:14:47 +0530
Message-ID: <178628308768.15712...@host>

A message carrying both body and html becomes multipart/mixed with a generated boundary — measured. Clients that cannot render HTML fall back to the plain part, which is why setting both is worth the extra line.

Sending is blocking, and it happens inside the request

mail.send() opens a TCP connection and waits for the SMTP server. If that server is slow, your user watches a spinner; if it is down, their signup fails for a reason that has nothing to do with signing up. Move it off the request:

background.py

from threading import Thread
 
def send_async(app, msg):
    with app.app_context():        # a new thread has no context of its own
        mail.send(msg)
 
Thread(target=send_async, args=(app, msg)).start()

A thread is the minimum. A real queue — Celery, RQ, or your platform’s — gives you retries and visibility, which matter once mail is part of a business process.

Never put credentials in the code

MAIL_PASSWORD in a committed config is a working credential for anyone with repository access, including after you delete the line. Read it from the environment. Most providers also require an app-specific password rather than the account password.

See it move

sketch Sending inside the request, or off it p5.js Pause Restart

mail.send blocks until the SMTP server replies. Moving it to a background thread returns the response immediately.

Check yourself

pch.quizTag pch.quizDefaultTitle

1. How should email be covered in an automated test suite?

   A send to a real inbox and check it manually B set MAIL_SUPPRESS_SEND and use mail.record_messages() to capture messages in memory C mock the socket layer by hand D skip testing email entirely
   pch.quizShowAnswer

   B — set MAIL_SUPPRESS_SEND and use mail.record_messages() to capture messages in memory — Measured one message captured with subject, sender, recipients and both bodies intact, and no SMTP connection opened. A suite that really sends mail is slow, flaky, and eventually mails a real person.

2. Why move mail.send() out of the request that triggered it?

   A Flask forbids network calls inside a view B it opens an SMTP connection and blocks until the server replies, so a slow or dead mail server becomes a slow or failed user action C sending requires an application context that views lack D it would otherwise send the message twice
   pch.quizShowAnswer

   B — it opens an SMTP connection and blocks until the server replies, so a slow or dead mail server becomes a slow or failed user action — A background thread is the minimum, and it needs its own app context. A real queue adds retries and visibility once mail is part of a business process.

3. A Message sets both body and html. What Content-Type does the transmitted message use?

   A text/plain, the html is discarded B text/html, the plain body is discarded C multipart/mixed with a generated boundary, so clients can choose D it raises, since only one body may be set
   pch.quizShowAnswer

   C — multipart/mixed with a generated boundary, so clients can choose — Measured multipart with a boundary. Clients that cannot render HTML fall back to the plain part, which is why setting both is worth the extra line.