Send mail with mailclerk.app
Project description
Mailclerk Python
Mailclerk helps anyone on your team design great emails, improve their performance, and free up developer time. Learn more
Table of Contents
- Requirements
- Setup
- API Key & URL
- Usage
- Testing
- Varying API Keys
- Package Tests
- Versioning
- Code of Conduct
- Contributions
- License
- History
Requirements
- Python 2.7+ or Python 3.4+
Setup
To install, run:
pip install mailclerk
API Key & URL
To set the Mailclerk API Key (begins with mc_), you can provide it as an
environmental variable: MAILCLERK_API_KEY. Alternatively, you can
set it directly on the Mailclerk module:
import mailclerk
mailclerk.api_key = "mc_yourprivatekey"
If you are using version control like git, we strongly recommend storing your production API keys in environmental variables.
The default API endpoint is https://api.mailclerk.app. To change this, you
can provide a MAILCLERK_API_URL ENV variable or set mailclerk.mailclerk_url.
Usage
You'll need an active account and at least one template (in the example welcome-email).
To send an email to "alice@example.com":
mailclerk.deliver("welcome-email", "alice@example.com")
If the template has any dynamic data, you can include it in the third parameter as a hash:
mailclerk.deliver("welcome-email", "alice@example.com", { name: "Alice" })
See Mailclerk documentation for more details.
Testing
Your Mailclerk environment has two API keys: a production key (beginning with mc_live)
and a test key (beginning with mc_test). If you use the test key, emails will
not be delivered, but will show up in the logs on your Mailclerk account and can be
previewed there. This replaces tools like naomi for previewing emails in development.
To avoid cluttering up your Mailclerk test logs with sends triggered by your
automated test suite, call mailclerk.outbox.enable() in the file that
configures your tests. For example, in Django, add it to the test environment-specific
section of your settings.py file.
This will also enable utility methods which you can use to write tests that check emails are sent with the correct data:
# Number of emails "sent"
len(mailclerk.outbox)
# Returns all emails of matching a template or email recipient. See method
mailclerk.outbox.filter(template="welcome-email")
mailclerk.outbox.filter(recipient_email="gilles@example.com")
# Returns the most recent email:
email = mailclerk.outbox[-1]
email.template # "welcome-email"
email.recipient_email # "gilles@example.com"
email.subject # "Welcome to Acme, Gilles"
email.html # "<html><body>..."
In between test cases (for example, the setUp() method of a unittest case), you should clear the stored emails by calling mailclerk.outbox.reset().
The emails have the following attributes:
| Attribute | Description |
|---|---|
template |
Slug of the template sent (1st argument to mailclerk.deliver) |
recipient |
Hash representing the send recipient (2nd argument to mailclerk.deliver) |
recipient_email |
Email of the send recipient |
recipient_name |
Name of the send recipient (nil if not specified) |
data |
Dynamic data for the send (3rd argument to mailclerk.deliver) |
options |
Options specified for the send (4th argument to mailclerk.deliver) |
from |
From Mailclerk: Hash with name and address of the sender |
subject |
From Mailclerk: Text of the send's subject line |
preheader |
From Mailclerk: Text of the send's preheader |
html |
From Mailclerk: Rendered body HTML for the send |
text |
From Mailclerk: Rendered plaintext version of the send |
headers |
From Mailclerk: Extra email headers (e.g. reply-to) |
See the Mailclerk testing documentation for more details.
Varying API Keys
If you need to use multiple API keys, you can also initialize mailclerk.MailclerkAPIClient
instances with different keys. This:
mc_client = mailclerk.MailclerkAPIClient("mc_yourprivatekey")
mc_client.deliver("welcome-email", "bob@example.com")
Is equivalent to this:
mailclerk.api_key = "mc_yourprivatekey"
mailclerk.deliver("welcome-email", "bob@example.com")
Package Tests
Install test dependencies:
pip install .[test]
Run with:
python -m unittest discover
Versioning
Read Semantic Versioning for details. Briefly, it means:
- Major (X.y.z) - Incremented for any backwards incompatible public API changes.
- Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
- Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
Code of Conduct
Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.
Contributions
Read CONTRIBUTING for details.
License
Copyright 2021 Mailclerk. Read LICENSE for details.
History
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mailclerk-1.2.0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | dfaa79176db00cb3597a0b193761f31655ec4e0ce292b9188d0c045274d75ece |
|
| MD5 | b848803c57ff24165b8c608d8582d08c |
|
| BLAKE2b-256 | 19a1ebc6be04040ca7b9d3692acb6afe26c5cf3bef11fcb112fc0ea25c26b8d4 |
