flask-mail¶
One of the most basic functions in a web application is the ability to send emails to your users.
The Flask-Mail extension provides a simple interface to set up SMTP with your Flask application and to send messages from your views and scripts.
Links¶
Installing Flask-Mail¶
Install with pip and easy_install:
pip install Flask-Mail
or download the latest version from version control:
git clone https://github.com/mattupstate/flask-mail.git
cd flask-mail
python setup.py install
If you are using virtualenv, it is assumed that you are installing flask-mail in the same virtualenv as your Flask application(s).
Configuring Flask-Mail¶
Flask-Mail is configured through the standard Flask config API. These are the available options (each is explained later in the documentation):
MAIL_SERVER : default ‘localhost’
MAIL_PORT : default 25
MAIL_USE_TLS : default False
MAIL_USE_SSL : default False
MAIL_DEBUG : default app.debug
MAIL_USERNAME : default None
MAIL_PASSWORD : default None
MAIL_DEFAULT_SENDER : default None
MAIL_MAX_EMAILS : default None
MAIL_SUPPRESS_SEND : default app.testing
MAIL_ASCII_ATTACHMENTS : default False
In addition the standard Flask TESTING
configuration option is used by Flask-Mail
in unit tests (see below).
Emails are managed through a Mail
instance:
from flask import Flask
from flask_mail import Mail
app = Flask(__name__)
mail = Mail(app)
In this case all emails are sent using the configuration values of the application that
was passed to the Mail
class constructor.
Alternatively you can set up your Mail
instance later at configuration time, using the
init_app method:
mail = Mail()
app = Flask(__name__)
mail.init_app(app)
In this case emails will be sent using the configuration values from Flask’s current_app
context global. This is useful if you have multiple applications running in the same
process but with different configuration options.
Sending messages¶
To send a message first create a Message
instance:
from flask_mail import Message
@app.route("/")
def index():
msg = Message("Hello",
sender="from@example.com",
recipients=["to@example.com"])
You can set the recipient emails immediately, or individually:
msg.recipients = ["you@example.com"]
msg.add_recipient("somebodyelse@example.com")
If you have set MAIL_DEFAULT_SENDER
you don’t need to set the message
sender explicity, as it will use this configuration value by default:
msg = Message("Hello",
recipients=["to@example.com"])
If the sender
is a two-element tuple, this will be split into name
and address:
msg = Message("Hello",
sender=("Me", "me@example.com"))
assert msg.sender == "Me <me@example.com>"
The message can contain a body and/or HTML:
msg.body = "testing"
msg.html = "<b>testing</b>"
Finally, to send the message, you use the Mail
instance configured with your Flask application:
mail.send(msg)
Bulk emails¶
Usually in a web application you will be sending one or two emails per request. In certain situations you might want to be able to send perhaps dozens or hundreds of emails in a single batch - probably in an external process such as a command-line script or cronjob.
In that case you do things slightly differently:
with mail.connect() as conn:
for user in users:
message = '...'
subject = "hello, %s" % user.name
msg = Message(recipients=[user.email],
body=message,
subject=subject)
conn.send(msg)
The connection to your email host is kept alive and closed automatically once all the messages have been sent.
Some mail servers set a limit on the number of emails sent in a single connection. You can set the max amount of emails to send before reconnecting by specifying the MAIL_MAX_EMAILS setting.
Attachments¶
Adding attachments is straightforward:
with app.open_resource("image.png") as fp:
msg.attach("image.png", "image/png", fp.read())
See the API for details.
If MAIL_ASCII_ATTACHMENTS
is set to True, filenames will be converted to
an ASCII equivalent. This can be useful when using a mail relay that modify mail
content and mess up Content-Disposition specification when filenames are UTF-8
encoded. The conversion to ASCII is a basic removal of non-ASCII characters. It
should be fine for any unicode character that can be decomposed by NFKD into one
or more ASCII characters. If you need romanization/transliteration (i.e ß →
ss) then your application should do it and pass a proper ASCII string.
Unit tests and suppressing emails¶
When you are sending messages inside of unit tests, or in a development environment, it’s useful to be able to suppress email sending.
If the setting TESTING
is set to True
, emails will be
suppressed. Calling send()
on your messages will not result in
any messages being actually sent.
Alternatively outside a testing environment you can set MAIL_SUPPRESS_SEND
to False. This
will have the same effect.
However, it’s still useful to keep track of emails that would have been sent when you are writing unit tests.
In order to keep track of dispatched emails, use the record_messages
method:
with mail.record_messages() as outbox:
mail.send_message(subject='testing',
body='test',
recipients=emails)
assert len(outbox) == 1
assert outbox[0].subject == "testing"
The outbox is a list of Message
instances sent.
The blinker package must be installed for this method to work.
Note that the older way of doing things, appending the outbox to
the g
object, is now deprecated.
Header injection¶
To prevent header injection attempts to send
a message with newlines in the subject, sender or recipient addresses will result in a BadHeaderError
.
Signalling support¶
New in version 0.4.
Flask-Mail now provides signalling support through a email_dispatched
signal. This is sent whenever an email is
dispatched (even if the email is not actually sent, i.e. in a testing environment).
A function connecting to the email_dispatched
signal takes a Message
instance as a first argument, and the Flask
app instance as an optional argument:
def log_message(message, app):
app.logger.debug(message.subject)
email_dispatched.connect(log_message)
API¶
- class flask_mail.Mail(app=None)¶
Manages email messaging
- Parameters
app – Flask instance
- connect()¶
Opens a connection to the mail host.
- send(message)¶
Sends a single message instance. If TESTING is True the message will not actually be sent.
- Parameters
message – a Message instance.
- send_message(*args, **kwargs)¶
Shortcut for send(msg).
Takes same arguments as Message constructor.
- Versionadded
0.3.5
- class flask_mail.Attachment(filename=None, content_type=None, data=None, disposition=None, headers=None)¶
Encapsulates file attachment information.
- Versionadded
0.3.5
- Parameters
filename – filename of attachment
content_type – file mimetype
data – the raw file data
disposition – content-disposition (if any)
- class flask_mail.Connection(mail)¶
Handles connection to host.
- send(message, envelope_from=None)¶
Verifies and sends message.
- Parameters
message – Message instance.
envelope_from – Email address to be used in MAIL FROM command.
- send_message(*args, **kwargs)¶
Shortcut for send(msg).
Takes same arguments as Message constructor.
- Versionadded
0.3.5
- class flask_mail.Message(subject='', recipients=None, body=None, html=None, sender=None, cc=None, bcc=None, attachments=None, reply_to=None, date=None, charset=None, extra_headers=None, mail_options=None, rcpt_options=None)¶
Encapsulates an email message.
- Parameters
subject – email subject header
recipients – list of email addresses
body – plain text message
html – HTML message
sender – email sender address, or MAIL_DEFAULT_SENDER by default
cc – CC list
bcc – BCC list
attachments – list of Attachment instances
reply_to – reply-to address
date – send date
charset – message character set
extra_headers – A dictionary of additional headers for the message
mail_options – A list of ESMTP options to be used in MAIL FROM command
rcpt_options – A list of ESMTP options to be used in RCPT commands
- add_recipient(recipient)¶
Adds another recipient to the message.
- Parameters
recipient – email address of recipient.
- attach(filename=None, content_type=None, data=None, disposition=None, headers=None)¶
Adds an attachment to the message.
- Parameters
filename – filename of attachment
content_type – file mimetype
data – the raw file data
disposition – content-disposition (if any)