Flask-Sendmail Documentation

Transcription

1 Flask-Sendmail Documentation Release 0.1 Anthony Ford February 14, 2014

2

3 Contents 1 Installing Flask-Sendmail 3 2 Configuring Flask-Sendmail 5 3 Sending messages 7 4 Bulk s 9 5 Attachments 11 6 Unit tests and suppressing s 13 7 Header injection 15 8 API 17 Python Module Index 19 i

4 ii

5 Flask-Sendmail Documentation, Release 0.1 ing 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

6 Flask-Sendmail Documentation, Release Contents

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

8 Flask-Sendmail Documentation, Release Chapter 1. Installing Flask-Sendmail

9 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_ S : 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). s 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

10 Flask-Sendmail Documentation, Release Chapter 2. Configuring Flask-Sendmail

11 CHAPTER 3 Sending messages To send a message first create a Message instance: from flask.ext.sendmail import def index(): msg = Message("Hello", sender="from@example.com", recipients=["to@example.com"]) You can set the recipient s 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 s will be sent either. 7

12 Flask-Sendmail Documentation, Release Chapter 3. Sending messages

13 CHAPTER 4 Bulk s While Flask-Mail supports bulk ing, Flask-Sendmail does not yet support it. If anyone has any suggestions on achieving bulk support, please pull a request on Github. Flask-Sendmail does take the max_ argument in an effort to mantain drop-in compatibility 9

14 Flask-Sendmail Documentation, Release Chapter 4. Bulk s

15 CHAPTER 5 Attachments Attachments are planned for a future release. 11

16 Flask-Sendmail Documentation, Release Chapter 5. Attachments

17 CHAPTER 6 Unit tests and suppressing s When you are sending messages inside of unit tests, or in a development environment, it s useful to be able to suppress sending. If the setting TESTING is set to True, s 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

18 Flask-Sendmail Documentation, Release Chapter 6. Unit tests and suppressing s

19 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

20 Flask-Sendmail Documentation, Release Chapter 7. Header injection

21 CHAPTER 8 API class flask_sendmail.mail(app=none) connect(max_ s=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_ s=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 message. Parameters subject subject header recipients list of addresses body plain text message html HTML message sender 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

22 Flask-Sendmail Documentation, Release 0.1 add_recipient(recipient) Adds another recipient to the message. Parameters recipient address. 18 Chapter 8. API

23 Python Module Index f flask-mail, 3 flask_sendmail, 17 19