Package: mailclerk
Mailclerk PythonMailclerk helps anyone on your team design great emails, improve their performance, and free up developer time.Learn moreTable of ContentsRequirementsSetupAPI Key & URLUsageTestingVarying API KeysPackage TestsVersioningCode of ConductContributionsLicenseHistoryRequirementsPython 2.7+ or Python 3.4+SetupTo install, run:pip install mailclerkAPI Key & URLTo set the Mailclerk API Key (begins withmc_), 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 ishttps://api.mailclerk.app. To change this, you
can provide aMAILCLERK_API_URLENV variable or setmailclerk.mailclerk_url.UsageYou'll need an active account and at least one template (in the examplewelcome-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" })SeeMailclerk documentationfor more details.TestingYour Mailclerk environment has two API keys: a production key (beginning withmc_live)
and a test key (beginning withmc_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 likenaomifor previewing emails in development.To avoid cluttering up your Mailclerk test logs with sends triggered by your
automated test suite, callmailclerk.outbox.enable()in the file that
configures your tests. For example, in Django, add it to the test environment-specific
section of yoursettings.pyfile.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 methodmailclerk.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, thesetUp()method of a unittest case), you should clear the stored emails by callingmailclerk.outbox.reset().The emails have the following attributes:AttributeDescriptiontemplateSlug of the template sent (1st argument tomailclerk.deliver)recipientHash representing the send recipient (2nd argument tomailclerk.deliver)recipient_emailEmail of the send recipientrecipient_nameName of the send recipient (nil if not specified)dataDynamic data for the send (3rd argument tomailclerk.deliver)optionsOptions specified for the send (4th argument tomailclerk.deliver)fromFrom Mailclerk: Hash withnameandaddressof the sendersubjectFrom Mailclerk: Text of the send's subject linepreheaderFrom Mailclerk: Text of the send's preheaderhtmlFrom Mailclerk: Rendered body HTML for the sendtextFrom Mailclerk: Rendered plaintext version of the sendheadersFrom Mailclerk: Extra email headers (e.g.reply-to)See theMailclerk testing documentationfor more details.Varying API KeysIf you need to use multiple API keys, you can also initializemailclerk.MailclerkAPIClientinstances 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 TestsInstall test dependencies:pip install .[test]Run with:python -m unittest discoverVersioningReadSemantic Versioningfor 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 ConductPlease note that this project is released with aCODE OF CONDUCT. By
participating in this project you agree to abide by its terms.ContributionsReadCONTRIBUTINGfor details.LicenseCopyright 2021Mailclerk.
ReadLICENSEfor details.HistoryReadCHANGESfor details.
Built withGemsmith.