Go to file
androiddrew edc67a062e correcting distribution name
apistar_mail Added addtional detail to README and correct dealt setting for MAIL_SERVER
tests Added support to flake8 to dev, applied style fixes
.coveragerc Continued testing for coverage. Minor bug fix for unicode in localpart of email address
.flake8 Added support to flake8 to dev, applied style fixes
.gitignore initial commit
.travis.yml Added flake8 CI testing and build status badge to README
HISTORY.md Added Travis support, corrected README, fix setup license
LICENSE Renamed Mailer to Mail. Added attribution back to the flask_mail extension. Refactored ascii_attachment check on message. Continued removal of support code for Python2
MANIFEST.in adding MANIFEST.in file
README.md Added coverage badge
requirements_dev.txt adding dev requirements
setup.cfg Bump version: 0.1.1 → 0.2.0
setup.py correcting distribution name
tox.ini Added flake8 CI testing and build status badge to README

README.md

apistar-mail

Build Status codecov

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 the 'MAIL' dictionary in your settings, the mail_component in your component list, and the Mail component as a dependency in your view. Here we have a minimally viable app capable of sending an email message and returning a 204 response code:

from apistar import Route
from apistar.frameworks.wsgi import WSGIApp as App
from apistar_mail import mail_component, Mail, Message

settings = {
    'MAIL': {
        'MAIL_SERVER': 'smtp.example.com',
        'MAIL_USERNAME': 'me@example.com',
        'MAIL_PASSWORD': 'dontcommitthistoversioncontrol',
        'MAIL_PORT': 587,
        'MAIL_USE_TLS': True,
        'MAIL_DEFAULT_SENDER': 'me@example.com'
    }
}


def send_a_message(mail: Mail):
    msg = Message('Hello',
                  sender='me@example.com',
                  recipients=['you@example.com'])
    mail.send(msg)
    return


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

components = [
    mail_component
]

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

if __name__ == '__main__':
    app.main()

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='drew@example.com',
                  recipients=['you@example.com'])
    mail.send(msg)
    return

Your message recipients can be set in bulk or individually:

msg.recipients = ['you@example.com', 'me@example.com']
msg.add_recipient('otherperson@example.com')

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

msg = Message('Hello',
              recipients=['you@example.com'])

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', 'me@example.com'))

assert msg.sender == 'Me <me@example.com>'

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