{"id":4541,"library":"flask-mail","title":"Flask-Mail","description":"Flask-Mail is an extension for Flask that simplifies sending emails from your application. It provides a straightforward interface for integrating SMTP capabilities. Currently at version 0.10.0, the project is actively maintained as part of the Pallets Community Ecosystem, the open-source organization behind Flask.","status":"active","version":"0.10.0","language":"python","source_language":"en","source_url":"https://github.com/pallets-eco/flask-mail/","tags":["flask","email","mail","smtp"],"install":[{"cmd":"pip install Flask-Mail","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core web framework integration.","package":"Flask","optional":false}],"imports":[{"symbol":"Mail","correct":"from flask_mail import Mail"},{"symbol":"Message","correct":"from flask_mail import Message"}],"quickstart":{"code":"import os\nfrom flask import Flask\nfrom flask_mail import Mail, Message\n\napp = Flask(__name__)\n\n# Configure Flask-Mail using environment variables for sensitive data\napp.config['MAIL_SERVER'] = os.environ.get('MAIL_SERVER', 'smtp.example.com')\napp.config['MAIL_PORT'] = int(os.environ.get('MAIL_PORT', 587))\napp.config['MAIL_USE_TLS'] = os.environ.get('MAIL_USE_TLS', 'True').lower() == 'true'\napp.config['MAIL_USE_SSL'] = os.environ.get('MAIL_USE_SSL', 'False').lower() == 'true'\napp.config['MAIL_USERNAME'] = os.environ.get('MAIL_USERNAME', '')\napp.config['MAIL_PASSWORD'] = os.environ.get('MAIL_PASSWORD', '')\napp.config['MAIL_DEFAULT_SENDER'] = os.environ.get('MAIL_DEFAULT_SENDER', 'noreply@example.com')\n\nmail = Mail(app)\n\n@app.route('/send-test-email')\ndef send_email():\n    if not app.config['MAIL_USERNAME'] or not app.config['MAIL_PASSWORD']:\n        return \"Email credentials not set in environment variables. Cannot send.\", 500\n\n    msg = Message(\n        subject='Hello from Flask-Mail!',\n        recipients=['recipient@example.com'], # Replace with a real recipient email\n        body='This is a test email sent from your Flask application.'\n    )\n    try:\n        mail.send(msg)\n        return 'Email sent successfully!'\n    except Exception as e:\n        return f'Failed to send email: {e}', 500\n\nif __name__ == '__main__':\n    # Example usage with environment variables (set these before running):\n    # export MAIL_SERVER='smtp.gmail.com'\n    # export MAIL_PORT=587\n    # export MAIL_USE_TLS=True\n    # export MAIL_USE_SSL=False\n    # export MAIL_USERNAME='your_gmail@gmail.com'\n    # export MAIL_PASSWORD='your_app_password'\n    # export MAIL_DEFAULT_SENDER='your_gmail@gmail.com'\n    app.run(debug=True)","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python interpreter to 3.8 or newer.","message":"Version 0.10.0 dropped support for Python versions older than 3.8. Ensure your environment meets this minimum requirement.","severity":"breaking","affected_versions":"0.10.0+"},{"fix":"Use `importlib.metadata.version(\"flask-mail\")` instead to retrieve the package version.","message":"The `__version__` attribute is deprecated in 0.10.0 and will be removed. Direct access will fail.","severity":"breaking","affected_versions":"0.10.0+"},{"fix":"Update `msg.attach` calls to pass headers as a dictionary.","message":"The `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.","severity":"breaking","affected_versions":"0.10.0+"},{"fix":"Set 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.","message":"You cannot enable both `MAIL_USE_TLS` and `MAIL_USE_SSL` simultaneously. Enabling both will lead to connection errors or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update configuration variable names to use the `MAIL_` prefix (e.g., `MAIL_DEFAULT_SENDER`).","message":"Older 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.","severity":"gotcha","affected_versions":"< 0.8.0 to 0.8.0+"},{"fix":"Generate an App Password in your Google Account security settings and use that for `MAIL_PASSWORD`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions (specific to Gmail/SMTP setup)"},{"fix":"Update signal handlers connected to `email_dispatched` to expect `(app, message)` signature.","message":"The `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.","severity":"breaking","affected_versions":"0.10.0+"}],"env_vars":null,"search_vec":"'0.10.0':31 'activ':35 'applic':18 'behind':49 'capabl':27 'communiti':42 'current':28 'ecosystem':43 'email':15,52 'extens':9 'flask':2,5,11,50,51 'flask-mail':1,4 'integr':25 'interfac':23 'mail':3,6,53 'maintain':36 'open':46 'open-sourc':45 'organ':48 'pallet':41 'part':38 'project':33 'provid':20 'send':14 'simplifi':13 'smtp':26,54 'sourc':47 'straightforward':22 'version':30","created_at":"2026-04-12T13:57:03.656779+00:00","updated_at":"2026-04-17T14:29:46.045787+00:00","problems":[{"fix":"Install Flask-Mail using pip: `pip install Flask-Mail`.","cause":"The Flask-Mail package is not installed in the Python environment.","error":"ImportError: No module named 'flask_mail'"},{"fix":"Refactor the application to avoid circular imports by restructuring modules or using relative imports.","cause":"Circular import due to improper module structure or import statements.","error":"ImportError: cannot import name 'mail' from 'app'"},{"fix":"Ensure all necessary mail configurations are set in the Flask app, including MAIL_SERVER, MAIL_PORT, MAIL_USERNAME, and MAIL_PASSWORD.","cause":"Missing or incorrect SMTP server configuration in Flask app settings.","error":"SMTPServerDisconnected: Please configure the MAIL_SERVER setting."},{"fix":"Verify the SMTP server address, port, and ensure that the server allows connections from your application.","cause":"The SMTP server is refusing the connection, possibly due to incorrect server settings or network issues.","error":"error: [Errno 10061] No connection could be made because the target machine actively refused it"},{"fix":"Ensure the Flask-Mail package is installed using pip: `pip install Flask-Mail`.","cause":"This error occurs when the 'flask-mail' package is not installed in the Python environment, or the Python interpreter cannot find it.","error":"ModuleNotFoundError: No module named 'flask_mail'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.10.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/pallets-eco/flask-mail","docs":"https://flask-mail.readthedocs.io","changelog":"https://flask-mail.readthedocs.io/en/latest/changes/","pypi":"https://pypi.org/project/flask-mail/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}