# apistar-mail
---
`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 ](https://github.com/mattupstate/flask-mail ) extension by 'Dan Jacob' but has been modified extensively to remove Python 2 support and be used as an APIStar component.
## Installation
`$ pip install apistar-mail`
## Usage
### Setup
To send mail messages from your view functions you must include the `MAIL` dictionary in your settings and the mail_component in your component list.
```
from apistar import WSGIApp as App
from apistar_mail import mail_component
settings = {
'MAIL': {
'MAIL_SERVER': 'smtp.example.com',
'MAIL_USERNAME': 'drew@example.com',
'MAIL_PASSWORD': 'dontcommitthistoversioncontrol',
'MAIL_PORT': 587,
'MAIL_USE_TLS': True,
'MAIL_DEFAULT_SENDER': 'drew@example.com'
}
}
components = [
mail_component
]
app = App(
settings=settings,
routes=routes,
components=components
)
```
### 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 don’
```
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 > '
```
### 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`
