Skip to main content

SQLAlchemy based e-mail sending extension for Flask

Project description


SQLAlchemy based e-mail sending extension for Flask.


The provided MailAlchemy extension object registers a Flask-Mail instance and an Email model class through Flask-SQLAlchemy.

Flask-MailAlchemy can be configured with the same parameters as Flask-Mail Additional parameters include MAIL_PER_MINUTE, MAIL_PER_HOUR and MAIL_PER_DAY.


The MailAlchemy extension can be initialized like any other Flask extension. Flask-SQLAlchemy instance is needed. Custom Email model can be provided for extending the model with extra functionality (e.g.: Adding foreign key to user table). If email_class is None, a simple Email model is used. You can also provide the Flask app after initialization with mail.init_app(app).

from flask import Flask
from flask_mailalchemy import MailAlchemy, Message, EmailMixin
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
db = SQLAlchemy(app)

class Email(db.Model, EmailMixin):
    recipient_id = db.Column(db.Integer, db.ForeignKey(''))

mail = MailAlchemy(app, db, Email)

if __name__ == '__main__':

Sending mails

To send email instantly, use the send() or send_message() methods just like in Flask-Mail. Additionally, message content can be rendered from templates with the render_template() method. Templates should be saved in the templates/mail/ directory. The method expects the template name without extension and uses .html and .txt files for message body.

msg = Message(
   subject="Test Mail",
   sender=("Sender Name", ""),
   recipients=("", "")
mail.render_template(msg, "hello_world", name="John")


Using worker

It might be a good idea to handle the sending of e-mails in the background in a separate thread. This way we can schedule e-mails to be sent at a specific time in the future and handle mail server limitations. These limitations can be set in the Flask config with the values MAIL_PER_MINUTE, MAIL_PER_HOUR and MAIL_PER_DAY. To schedule an e-mail to send, use the schedule() or schedule_mesage() methods.

def mail_test():
    msg = Message(
        subject="Test Mail",
        sender=("Sender Name", ""),
        recipients=("", "")
    mail.render_template(msg, "hello_world", name="John")
    mail.schedule(msg, datetime.datetime(2020, 1, 1, 8, 0, 0))

if __name__ == '__main__':


There is a base template available in the templates/mail/ directory, which is consists of 4 regular blocks and one content block.

{% block header %}{% include "mail/blocks/header.html" %}{% endblock %}

{% block greetings %}{% include "mail/blocks/greetings.html" %}{% endblock %}

{% block content%}{% endblock %}

{% block sign_off %}{% include "mail/blocks/sign_off.html" %}{% endblock %}

{% block footer %}{% include "mail/blocks/footer.html" %}{% endblock %}

The regular blocks are found in templates/mail/blocks. The base and block templates have both an HTML and a plaintext version. For your e-mail templates simply extend the base template and override the content block.

{% extends 'mail/base.html' %}

{% block content %}
<p>Hello {{name}}!</p>
{% endblock %}

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for Flask-MailAlchemy, version 0.4
Filename, size File type Python version Upload date Hashes
Filename, size Flask-MailAlchemy-0.4.tar.gz (6.5 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page