Skip to main content

A simple email Component for APIStar

Project description


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


$ pip install apistar-mail


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': '',
    'MAIL_USERNAME': '',
    'MAIL_PASSWORD': 'dontcommitthistoversioncontrol',
    'MAIL_PORT': 587,
    'MAIL_USE_TLS': True,

def send_a_message(mail: Mail):
    msg = Message(subject='Hello',
                  body='Welcome to APIStar!',
    return Response('', 204)

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

components = [

app = App(

if __name__ == '__main__':
    app.serve('', 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',

Your message recipients can be set in bulk or individually:

msg.recipients = ['', '']

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

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', ''))

assert msg.sender == 'Me <>'

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


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


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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

apistar-mail-0.3.0.tar.gz (13.0 kB view hashes)

Uploaded source

Built Distribution

apistar_mail-0.3.0-py35-none-any.whl (8.8 kB view hashes)

Uploaded py35

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page