flask-mail Documentation

Release 0.9.1

Dan Jacob

Jun 20, 2017

 Contents

1 Links 3

2 Installing Flask-Mail 5

3 Configuring Flask-Mail 7

4 Sending messages 9

5 Bulk emails 11

6 Attachments 13

7 Unit tests and suppressing emails 15

8 Header injection 17

9 Signalling support 19

10 API 21

Python Module Index 25

i
ii
 flask-mail Documentation, Release 0.9.1

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 mes-
sages from your views and scripts.

Contents 1
flask-mail Documentation, Release 0.9.1

2 Contents
 CHAPTER 1

Links

• documentation
• source
• changelog

3
flask-mail Documentation, Release 0.9.1

4 Chapter 1. Links
 CHAPTER 2

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).

5
flask-mail Documentation, Release 0.9.1

6 Chapter 2. Installing Flask-Mail

 CHAPTER 3

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:

7
flask-mail Documentation, Release 0.9.1

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.

8 Chapter 3. Configuring Flask-Mail

 CHAPTER 4

Sending messages

To send a message first create a Message instance:

from flask_mail import Message

@app.route("/")
def index():

msg = Message("Hello",
sender="[email protected]",
recipients=["[email protected]"])

You can set the recipient emails immediately, or individually:

msg.recipients = ["[email protected]"]
msg.add_recipient("[email protected]")

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=["[email protected]"])

If the sender is a two-element tuple, this will be split into name and address:
msg = Message("Hello",
sender=("Me", "[email protected]"))

assert msg.sender == "Me <[email protected]>"

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:

9
flask-mail Documentation, Release 0.9.1

mail.send(msg)

10 Chapter 4. Sending messages

 CHAPTER 5

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.

11
flask-mail Documentation, Release 0.9.1

12 Chapter 5. Bulk emails

 CHAPTER 6

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.

13
flask-mail Documentation, Release 0.9.1

14 Chapter 6. Attachments
 CHAPTER 7

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 True. 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.

15
flask-mail Documentation, Release 0.9.1

16 Chapter 7. Unit tests and suppressing emails

 CHAPTER 8

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.

17
flask-mail Documentation, Release 0.9.1

18 Chapter 8. Header injection

 CHAPTER 9

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)

19
flask-mail Documentation, Release 0.9.1

20 Chapter 9. Signalling support

 CHAPTER 10

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.

21
flask-mail Documentation, Release 0.9.1

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, alts=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
• alts – A dict or an iterable to go through dict() that contains multipart alternatives
• 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

22 Chapter 10. API

 flask-mail Documentation, Release 0.9.1

• disposition – content-disposition (if any)

23
flask-mail Documentation, Release 0.9.1

24 Chapter 10. API

 Python Module Index

f
flask-mail, 3
flask_mail, 21

25
flask-mail Documentation, Release 0.9.1

26 Python Module Index

 Index

A
add_recipient() (flask_mail.Message method), 22
attach() (flask_mail.Message method), 22
Attachment (class in flask_mail), 21

C
connect() (flask_mail.Mail method), 21
Connection (class in flask_mail), 21

F
flask-mail (module), 1
flask_mail (module), 21

M
Mail (class in flask_mail), 21
Message (class in flask_mail), 22

S
send() (flask_mail.Connection method), 21
send() (flask_mail.Mail method), 21
send_message() (flask_mail.Connection method), 22
send_message() (flask_mail.Mail method), 21

27