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.

Filename, size & hash SHA256 hash help File type Python version Upload date
apistar_mail-0.3.0-py35-none-any.whl (8.8 kB) Copy SHA256 hash SHA256 Wheel py35
apistar-mail-0.3.0.tar.gz (13.0 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page