Flask-Sendmail Documentation Release 0.1 Anthony Ford February 14, 2014
Contents 1 Installing Flask-Sendmail 3 2 Configuring Flask-Sendmail 5 3 Sending messages 7 4 Bulk emails 9 5 Attachments 11 6 Unit tests and suppressing emails 13 7 Header injection 15 8 API 17 Python Module Index 19 i
ii
Flask-Sendmail Documentation, Release 0.1 Emailing users is essential in most web applications. For most cases, you can easily use SMTP, and in those cases, Flask-Mail is perfect. In other cases, you can only use your system s sendmail client. The Flask-Sendmail extension provides a simple interface to your system s sendmail client from within your Flask application and gives you ability to send messages from your views and scripts. Source code and issue tracking are at GitHub. Contents 1
Flask-Sendmail Documentation, Release 0.1 2 Contents
CHAPTER 1 Installing Flask-Sendmail Install with pip and easy_install: pip install Flask-Sendmail or download the latest version from version control: git clone https://github.com/ajford/flask-sendmail.git cd flask-sendmail 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). 3
Flask-Sendmail Documentation, Release 0.1 4 Chapter 1. Installing Flask-Sendmail
CHAPTER 2 Configuring Flask-Sendmail Flask-Sendmail is configured through the standard Flask config API. These are the available options (each is explained later in the documentation): MAIL_MAILER : default /usr/sbin/sendmail MAIL_MAILER_FLAGS : default -t MAIL_DEBUG : default app.debug DEFAULT_MAIL_SENDER : default None DEFAULT_MAX_EMAILS : default None MAIL_FAIL_SILENTLY : default True MAIL_SUPPRESS_SEND : default False In addition the standard Flask TESTING configuration option is used by Flask-Sendmail in unit tests (see below). Emails are managed through a Mail instance: from flask import Flask from flask.ext.sendmail import Mail app = Flask( name ) mail = Mail(app) 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) 5
Flask-Sendmail Documentation, Release 0.1 6 Chapter 2. Configuring Flask-Sendmail
CHAPTER 3 Sending messages To send a message first create a Message instance: from flask.ext.sendmail 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 DEFAULT_MAIL_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) If the setting MAIL_FAIL_SILENTLY is True, and the connection fails (for example, the mail server cannot be found at that hostname) then no error will be raised, although of course no emails will be sent either. 7
Flask-Sendmail Documentation, Release 0.1 8 Chapter 3. Sending messages
CHAPTER 4 Bulk emails While Flask-Mail supports bulk emailing, Flask-Sendmail does not yet support it. If anyone has any suggestions on achieving bulk email support, please pull a request on Github. Flask-Sendmail does take the max_email argument in an effort to mantain drop-in compatibility 9
Flask-Sendmail Documentation, Release 0.1 10 Chapter 4. Bulk emails
CHAPTER 5 Attachments Attachments are planned for a future release. 11
Flask-Sendmail Documentation, Release 0.1 12 Chapter 5. Attachments
CHAPTER 6 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. 13
Flask-Sendmail Documentation, Release 0.1 14 Chapter 6. Unit tests and suppressing emails
CHAPTER 7 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. 15
Flask-Sendmail Documentation, Release 0.1 16 Chapter 7. Header injection
CHAPTER 8 API class flask_sendmail.mail(app=none) connect(max_emails=none) Opens a connection to the system s sendmail client. send(message) Sends message through system s sendmail client. Parameters message Mail Message instance send_message(*args, **kwargs) Shortcut for send(msg). Takes same arguments as Message constructor. class flask_sendmail.connection(mail, max_emails=none) Handles connection to host. send_message(*args, **kwargs) Shortcut for send(msg). Takes same arguments as Message constructor. class flask_sendmail.message(subject, recipients=none, body=none, html=none, sender=none, cc=none, bcc=none, attachments=none, reply_to=none, charset=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 DEFAULT_MAIL_SENDER by default cc CC list bcc BCC list attachments list of Attachment instances reply_to reply-to address charset used to set MIMEText _charset 17
Flask-Sendmail Documentation, Release 0.1 add_recipient(recipient) Adds another recipient to the message. Parameters recipient email address. 18 Chapter 8. API
Python Module Index f flask-mail, 3 flask_sendmail, 17 19