Install & Compatibility
Where this runs
tested against v0.10.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.586s · 22.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.526s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Mail
✓ from flask_mail import Mail
Message
✓ from flask_mail import Message
Initializes Flask-Mail with configuration from environment variables for security and flexibility, then defines a simple route to send a test email. Remember to set `MAIL_USERNAME`, `MAIL_PASSWORD`, and other `MAIL_` environment variables before running the application. For Gmail, use an App Password if 2FA is enabled.
import os
from flask import Flask
from flask_mail import Mail, Message
app = Flask(__name__)
# Configure Flask-Mail using environment variables for sensitive data
app.config['MAIL_SERVER'] = os.environ.get('MAIL_SERVER', 'smtp.example.com')
app.config['MAIL_PORT'] = int(os.environ.get('MAIL_PORT', 587))
app.config['MAIL_USE_TLS'] = os.environ.get('MAIL_USE_TLS', 'True').lower() == 'true'
app.config['MAIL_USE_SSL'] = os.environ.get('MAIL_USE_SSL', 'False').lower() == 'true'
app.config['MAIL_USERNAME'] = os.environ.get('MAIL_USERNAME', '')
app.config['MAIL_PASSWORD'] = os.environ.get('MAIL_PASSWORD', '')
app.config['MAIL_DEFAULT_SENDER'] = os.environ.get('MAIL_DEFAULT_SENDER', 'noreply@example.com')
mail = Mail(app)
@app.route('/send-test-email')
def send_email():
if not app.config['MAIL_USERNAME'] or not app.config['MAIL_PASSWORD']:
return "Email credentials not set in environment variables. Cannot send.", 500
msg = Message(
subject='Hello from Flask-Mail!',
recipients=['recipient@example.com'], # Replace with a real recipient email
body='This is a test email sent from your Flask application.'
)
try:
mail.send(msg)
return 'Email sent successfully!'
except Exception as e:
return f'Failed to send email: {e}', 500
if __name__ == '__main__':
# Example usage with environment variables (set these before running):
# export MAIL_SERVER='smtp.gmail.com'
# export MAIL_PORT=587
# export MAIL_USE_TLS=True
# export MAIL_USE_SSL=False
# export MAIL_USERNAME='your_gmail@gmail.com'
# export MAIL_PASSWORD='your_app_password'
# export MAIL_DEFAULT_SENDER='your_gmail@gmail.com'
app.run(debug=True)
Debug
Known issues
breakingVersion 0.10.0 dropped support for Python versions older than 3.8. Ensure your environment meets this minimum requirement.fixUpgrade your Python interpreter to 3.8 or newer.
affects: 0.10.0+
breakingThe `__version__` attribute is deprecated in 0.10.0 and will be removed. Direct access will fail.fixUse `importlib.metadata.version("flask-mail")` instead to retrieve the package version. affects: 0.10.0+
breakingThe `Message.attach` method's `headers` parameter now expects a dictionary (e.g., `{'Content-ID': '<image1>'}`) instead of a list of tuples (e.g., `[('Content-ID', '<image1>')]`). Using the old format will raise an AttributeError.fixUpdate `msg.attach` calls to pass headers as a dictionary.
affects: 0.10.0+
gotchaYou cannot enable both `MAIL_USE_TLS` and `MAIL_USE_SSL` simultaneously. Enabling both will lead to connection errors or unexpected behavior.fixSet either `MAIL_USE_TLS` or `MAIL_USE_SSL` to `True`, but not both, based on your SMTP server's requirements. For most modern servers, `MAIL_USE_TLS` with port 587 is common, while `MAIL_USE_SSL` typically uses port 465.
affects: All versions
gotchaOlder versions of Flask-Mail used configuration keys like `DEFAULT_MAIL_SENDER` and `DEFAULT_MAX_EMAILS`. These were changed to `MAIL_DEFAULT_SENDER` and `MAIL_MAX_EMAILS` in version 0.8.0.fixUpdate configuration variable names to use the `MAIL_` prefix (e.g., `MAIL_DEFAULT_SENDER`).
affects: < 0.8.0 to 0.8.0+
gotchaWhen using services like Gmail with 2-Factor Authentication (2FA) enabled, you typically need to generate an 'App Password' instead of using your regular account password to authenticate with SMTP. Regular passwords will fail.fixGenerate an App Password in your Google Account security settings and use that for `MAIL_PASSWORD`.
affects: All versions (specific to Gmail/SMTP setup)
breakingThe `email_dispatched` signal's arguments were reversed in 0.10.0. It now passes the Flask `app` instance as the sender and the `Message` instance as an argument, instead of the other way around.fixUpdate signal handlers connected to `email_dispatched` to expect `(app, message)` signature.
affects: 0.10.0+
Errors
Common errors & fixes
ImportError: No module named 'flask_mail'
The Flask-Mail package is not installed in the Python environment.
fixInstall Flask-Mail using pip: `pip install Flask-Mail`.
ImportError: cannot import name 'mail' from 'app'
Circular import due to improper module structure or import statements.
fixRefactor the application to avoid circular imports by restructuring modules or using relative imports.
SMTPServerDisconnected: Please configure the MAIL_SERVER setting.
Missing or incorrect SMTP server configuration in Flask app settings.
fixEnsure all necessary mail configurations are set in the Flask app, including MAIL_SERVER, MAIL_PORT, MAIL_USERNAME, and MAIL_PASSWORD.
error: [Errno 10061] No connection could be made because the target machine actively refused it
The SMTP server is refusing the connection, possibly due to incorrect server settings or network issues.
fixVerify the SMTP server address, port, and ensure that the server allows connections from your application.
ModuleNotFoundError: No module named 'flask_mail'
This error occurs when the 'flask-mail' package is not installed in the Python environment, or the Python interpreter cannot find it.
fixEnsure the Flask-Mail package is installed using pip: `pip install Flask-Mail`.
Upgrade
Version history
0.10.0latest on PyPI · released May 23, 2024
Audit
Dependencies
FlaskrequiredCore web framework integration.