A simple email Component for APIStar
Project description
# apistar-mail
[![PyPI](https://img.shields.io/pypi/v/apistar-mail.svg)](https://pypi.org/project/apistar-mail/)
[![PyPI](https://img.shields.io/pypi/pyversions/apistar-mail.svg)](https://pypi.org/project/apistar-mail/)
[![Build Status](https://travis-ci.org/androiddrew/apistar-mail.svg?branch=master)](https://travis-ci.org/androiddrew/apistar-mail)
[![codecov](https://codecov.io/gh/androiddrew/apistar-mail/branch/master/graph/badge.svg)](https://codecov.io/gh/androiddrew/apistar-mail)
Provides a simple interface to set up SMTP with your [APIStar](https://github.com/encode/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' 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:
```python
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)`
```python
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:
```python
msg.recipients = ['you@example.com', 'me@example.com']
msg.add_recipient('otherperson@example.com')
```
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:
```python
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:
```python
msg = Message('Hello',
sender=('Me', 'me@example.com'))
assert msg.sender == 'Me <me@example.com>'
```
A Message can contain a body and/or HTML:
```python
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
[![PyPI](https://img.shields.io/pypi/v/apistar-mail.svg)](https://pypi.org/project/apistar-mail/)
[![PyPI](https://img.shields.io/pypi/pyversions/apistar-mail.svg)](https://pypi.org/project/apistar-mail/)
[![Build Status](https://travis-ci.org/androiddrew/apistar-mail.svg?branch=master)](https://travis-ci.org/androiddrew/apistar-mail)
[![codecov](https://codecov.io/gh/androiddrew/apistar-mail/branch/master/graph/badge.svg)](https://codecov.io/gh/androiddrew/apistar-mail)
Provides a simple interface to set up SMTP with your [APIStar](https://github.com/encode/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' 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:
```python
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)`
```python
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:
```python
msg.recipients = ['you@example.com', 'me@example.com']
msg.add_recipient('otherperson@example.com')
```
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:
```python
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:
```python
msg = Message('Hello',
sender=('Me', 'me@example.com'))
assert msg.sender == 'Me <me@example.com>'
```
A Message can contain a body and/or HTML:
```python
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
Project details
Release history Release notifications | RSS feed
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.2.1.tar.gz
(12.8 kB
view hashes)
Built Distribution
Close
Hashes for apistar_mail-0.2.1-py35-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3ce3a91c9c5f41547a5565c3c903d1ef19a8c9fc2c57080a8447834d9e2bb5ae |
|
MD5 | 1fcfb46a4ccafb177cbb273d7a210e45 |
|
BLAKE2b-256 | 1adbeb4dca1d038f2079cce7aa35e454e77def15d36dfc41bcdc38fdf6dc58c8 |