This module provides an interface for the smtprelay server that allows it to be used as a logger or just to send emails.
smtprelay is designed to act as a message queue for sending e-mails so that rate limiting and authentication
can be implemented in one place.
## Configuration
Configuration is done via [Zirconium](https://github.com/turnbullerin/zirconium), which allows for you to use your
configuration language of choice. The example configuration below is given in TOML. Note that you must install the toml
package for versions of Python where it is not built-in.
```toml
[smtp_relay]
end_point = "http://server:port/send" # Mandatory, put in the path to your smtprelay server here.
bearer_token = "blahblah" # Mandatory, put in your secret token here from the relay server.
default_send_group = "" # Optional, specify a send group to be applied to all messages unless one is specified in code.
default_send_from = "" # Optional, specify a sender e-mail here for all messages unless one is provided in code.
retry_file = "" # Optional, specify a path to a file that will be used to store messages when the relay server cannot be contacted.
show_errors = true # Change to false to hide the printed errors when connections to the relay server fail
request_timeout = 2.5 # Change the timeout for the requests module here (default is 2.5)
cap_on_retry = 50 # Change the maximum number of e-mails that will be send during a retry attempt.
```
## Automatic Retries
This package allows for e-mails to be saved to a file if the smtprelay server is not available. To use this option, you
must first set the retry_file to a file path in the configuration. You can then schedule the resend using either the
entry point or by calling the module in cron.d or Windows task manager:
```bash
# Make sure you're in the right venv and that you execute this from the proper
# working directory for where you've located the configuration files.
python -m smtprelayapi
# OR
smtprelayapi-resend
```
## Usage
In this example, we simply queue up a message to be sent. The `send_group` parameter is a simple text string
that is recorded on the server side so that the origin of messages can be tracked.
```python
from autoinject import injector
from smtprelayapi import RelayClient
@injector.inject
def send_an_email(rc: RelayClient = None):
rc.send_email(
subject="Extended Warranty",
plain_message="We've been trying to reach you about your car's extended warranty.",
html_message="<p>We've been trying to reach you about your car's <strong>extended warranty</strong>.</p>",
from_email="scammer@example.com",
to_emails="adam.undergrove@example.com",
bcc_emails="head.scammer@example.com",
send_group="warranty-scams"
)
```
An implementation of `logging.Handler` is also provided for simplicity to integrate with the `logging` module.
```python
from smtprelayapi import RelayHandler
import logging
handler = RelayHandler(
subject="Application Log: myapplication: %{levelname}!",
format_subject=True,
toaddrs="admin@example.com",
ccaddrs="manager@example.com",
send_group="myapplication-errors",
level=logging.WARNING
)
logging.getLogger().addHandler(handler)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/dfo-meds/smtp-relay-client",
"name": "smtprelayapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Erin Turnbull",
"author_email": "erin.a.turnbull@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/22/e1/b8ed953e7d6712acbe5e10026992c9928374b1287449595ee81e6ad8d095/smtprelayapi-1.0.0.tar.gz",
"platform": null,
"description": "This module provides an interface for the smtprelay server that allows it to be used as a logger or just to send emails.\r\n\r\nsmtprelay is designed to act as a message queue for sending e-mails so that rate limiting and authentication\r\ncan be implemented in one place.\r\n\r\n## Configuration\r\n\r\nConfiguration is done via [Zirconium](https://github.com/turnbullerin/zirconium), which allows for you to use your\r\nconfiguration language of choice. The example configuration below is given in TOML. Note that you must install the toml\r\npackage for versions of Python where it is not built-in.\r\n\r\n```toml\r\n[smtp_relay]\r\nend_point = \"http://server:port/send\" # Mandatory, put in the path to your smtprelay server here.\r\nbearer_token = \"blahblah\" # Mandatory, put in your secret token here from the relay server.\r\ndefault_send_group = \"\" # Optional, specify a send group to be applied to all messages unless one is specified in code.\r\ndefault_send_from = \"\" # Optional, specify a sender e-mail here for all messages unless one is provided in code.\r\nretry_file = \"\" # Optional, specify a path to a file that will be used to store messages when the relay server cannot be contacted.\r\nshow_errors = true # Change to false to hide the printed errors when connections to the relay server fail\r\nrequest_timeout = 2.5 # Change the timeout for the requests module here (default is 2.5)\r\ncap_on_retry = 50 # Change the maximum number of e-mails that will be send during a retry attempt.\r\n```\r\n\r\n## Automatic Retries\r\n\r\nThis package allows for e-mails to be saved to a file if the smtprelay server is not available. To use this option, you\r\nmust first set the retry_file to a file path in the configuration. You can then schedule the resend using either the\r\nentry point or by calling the module in cron.d or Windows task manager:\r\n\r\n```bash \r\n # Make sure you're in the right venv and that you execute this from the proper\r\n # working directory for where you've located the configuration files.\r\n \r\n python -m smtprelayapi\r\n # OR\r\n smtprelayapi-resend\r\n\r\n```\r\n\r\n## Usage\r\n\r\nIn this example, we simply queue up a message to be sent. The `send_group` parameter is a simple text string\r\nthat is recorded on the server side so that the origin of messages can be tracked.\r\n\r\n```python \r\n from autoinject import injector\r\n from smtprelayapi import RelayClient\r\n \r\n @injector.inject\r\n def send_an_email(rc: RelayClient = None):\r\n rc.send_email(\r\n subject=\"Extended Warranty\",\r\n plain_message=\"We've been trying to reach you about your car's extended warranty.\",\r\n html_message=\"<p>We've been trying to reach you about your car's <strong>extended warranty</strong>.</p>\",\r\n from_email=\"scammer@example.com\",\r\n to_emails=\"adam.undergrove@example.com\",\r\n bcc_emails=\"head.scammer@example.com\",\r\n send_group=\"warranty-scams\"\r\n )\r\n```\r\n\r\nAn implementation of `logging.Handler` is also provided for simplicity to integrate with the `logging` module.\r\n\r\n```python\r\n\r\n from smtprelayapi import RelayHandler\r\n import logging\r\n \r\n handler = RelayHandler(\r\n subject=\"Application Log: myapplication: %{levelname}!\",\r\n format_subject=True,\r\n toaddrs=\"admin@example.com\",\r\n ccaddrs=\"manager@example.com\",\r\n send_group=\"myapplication-errors\",\r\n level=logging.WARNING\r\n )\r\n logging.getLogger().addHandler(handler) \r\n\r\n```\r\n",
"bugtrack_url": null,
"license": "",
"summary": "API for connecting to the smtprelay server.",
"version": "1.0.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dbf9dfaa3b602d3199a669bdd7cab2c4ecb0ca311a5af6d6c0e3d46590f01bfc",
"md5": "c3ae8c2f93058534a956298273a7e480",
"sha256": "0b8c942c67f769a028e61ea9f45f44f5860d0471aeafe43888f32dfa41287caf"
},
"downloads": -1,
"filename": "smtprelayapi-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3ae8c2f93058534a956298273a7e480",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7959,
"upload_time": "2023-01-23T19:39:27",
"upload_time_iso_8601": "2023-01-23T19:39:27.530068Z",
"url": "https://files.pythonhosted.org/packages/db/f9/dfaa3b602d3199a669bdd7cab2c4ecb0ca311a5af6d6c0e3d46590f01bfc/smtprelayapi-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "22e1b8ed953e7d6712acbe5e10026992c9928374b1287449595ee81e6ad8d095",
"md5": "b88e2b944175e1a6f7716ffc40da0bf0",
"sha256": "3de5136f567e591c4ea925037b5691734aca90655ad757465c7d77d63c2c7afa"
},
"downloads": -1,
"filename": "smtprelayapi-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b88e2b944175e1a6f7716ffc40da0bf0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8127,
"upload_time": "2023-01-23T19:39:28",
"upload_time_iso_8601": "2023-01-23T19:39:28.840623Z",
"url": "https://files.pythonhosted.org/packages/22/e1/b8ed953e7d6712acbe5e10026992c9928374b1287449595ee81e6ad8d095/smtprelayapi-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-23 19:39:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "dfo-meds",
"github_project": "smtp-relay-client",
"lcname": "smtprelayapi"
}
JSON
