apistar-mail 0.3.0

A simple email Component for APIStar

apistar-mail

Provides a simple interface to set up SMTP with your APIStar application and send messages from your view functions. Please note this work derives largely from the Flask-Mail extension by 'Dan Jacob' and contributors, but has been modified extensively to remove Python 2 support and be used as an APIStar component.

Installation

$ pip install apistar-mail

Usage

Example Setup

To send mail messages from your view functions you must include a dictionary of mail options to the MailComponent. Here we have a minimally viable app capable of sending an email message and returning a 204 response code:

from apistar import App, Route
from apistar.http import Response
from apistar_mail import MailComponent, Mail, Message

mail_options = {
    'MAIL_SERVER': 'smtp.example.com',
    'MAIL_USERNAME': '[e-mail]',
    'MAIL_PASSWORD': 'dontcommitthistoversioncontrol',
    'MAIL_PORT': 587,
    'MAIL_USE_TLS': True,
    'MAIL_DEFAULT_SENDER': '[e-mail]'
}


def send_a_message(mail: Mail):
    msg = Message(subject='Hello',
                  body='Welcome to APIStar!',
                  recipients=['[e-mail]'])
    mail.send(msg)
    return Response('', 204)


routes = [
    Route('/', 'POST', send_a_message)
]

components = [
    MailComponent(**mail_options)
]

app = App(
    routes=routes,
    components=components
)

if __name__ == '__main__':
    app.serve('127.0.0.1', 5000, debug=True)

Sending Messages

To send a message ,first include the Mail component for injection into your view. Then create an instance of Message, and pass it to your Mail component using mail.send(msg)

from apistar_mail import Mail, Message

def send_a_message(mail:Mail):
    msg = Message('Hello',
                  sender='[e-mail]',
                  recipients=['[e-mail]'])
    mail.send(msg)
    return

Your message recipients can be set in bulk or individually:

msg.recipients = ['[e-mail]', '[e-mail]']
msg.add_recipient('[e-mail]')

If you have set MAIL_DEFAULT_SENDER you don’t need to set the message sender explicitly, as it will use this configuration value by default:

msg = Message('Hello',
              recipients=['[e-mail]'])

The sender can also be passed as a two element tuple containing a name and email address which will be split like so:

msg = Message('Hello',
              sender=('Me', '[e-mail]'))

assert msg.sender == 'Me <[e-mail]>'

A Message can contain a body and/or HTML:

msg.body = 'message body'
msg.html = '<b>Hello apistar_mail!</b>'

Configuration Options

apistar-mail is configured through the inclusion of the MAIL dictionary in your apistar settings. These are the available options:

• 'MAIL_SERVER': default 'localhost'
• 'MAIL_USERNAME': default None
• 'MAIL_PASSWORD': default None
• 'MAIL_PORT': default 25
• 'MAIL_USE_TLS': default False
• 'MAIL_USE_SSL': default False
• 'MAIL_DEFAULT_SENDER': default None
• 'MAIL_DEBUG': default False
• 'MAIL_MAX_EMAILS': default None
• 'MAIL_SUPPRESS_SEND': default False
• 'MAIL_ASCII_ATTACHMENTS': False

Testing

To run the test suite with coverage first install the package in editable mode with it's testing requirements:

$ pip install -e ".[testing]"

To run the project's tests

$ pytest --cov

To run tests against multiple python interpreters use:

$ tox

HISTORY

0.3.0 Added support for APIStar version >= 0.4.0

0.2.1 Pinned APIStar requirement to 0.3.9

APIStar 0.4.0 introduced breaking changes to the framework. Since Components have completely changed we are pinning the requirement for this release.