Skip to content

Latest commit

 

History

History
162 lines (102 loc) · 5.86 KB

README.md

File metadata and controls

162 lines (102 loc) · 5.86 KB
Raw

What is Clojurewerkz Mailer

Mailer is an ActionMailer-inspired mailer library for Clojure. It combines Postal, Clostache and a number of its own features and conventions to make delivering complex template-based emails as painless as possible.

Project Goals

  • Do not reinvent the wheel
  • Email delivery should be testable
  • Steal good parts from ActionMailer

Project Maturity

Mailer is a moderately mature project, the API hasn't changed in several years.

Maven Artifacts

Mailer artifacts are released to Clojars. If you are using Maven, add the following repository definition to your

pom.xml:

<repository>
  <id>clojars.org</id>
  <url>http://clojars.org/repo</url>
</repository>

The Most Recent Release

With Leiningen:

[clojurewerkz/mailer "1.3.0"]

With Maven:

<dependency>
  <groupId>clojurewerkz</groupId>
  <artifactId>mailer</artifactId>
  <version>1.3.0</version>
</dependency>

Documentation

Mailer uses Mustache templates on the classpath and Postal mail message attribute maps. Key functions are:

  • clojurewerkz.mailer.core/build-email
  • clojurewerkz.mailer.core/deliver-email
  • clojurewerkz.mailer.core/render
  • clojurewerkz.mailer.core/delivery-mode!
  • clojurewerkz.mailer.core/with-delivery-mode
  • clojurewerkz.mailer.core/with-settings
(ns my-app
  (:require [clojurewerkz.mailer.core :refer [delivery-mode! with-settings with-defaults with-settings build-email deliver-email]]))

;; set default delivery mode (:smtp, :sendmail or :test)
(delivery-mode! :test)

;; build a message (can be used in unit tests or for various forms of delayed delivery)
;;
;; Pleasen note that email/templates/warning.mustache should be on your classpath. For example, with Leiningen 2,
;; you would use :resource-paths for this, like so: :resource-paths ["src/resources"]
(build-email {:from "Joe The Robot", :to ["[email protected]" "[email protected]"] :subject "OMG everything is down!"}
  "email/templates/warning.mustache" {:name "Joe" :host "host3.megacorp.internal"})

;;build a message using an HTML template, specify parameter mime type :text/html
(build-email {:from "Joe The Robot", :to ["[email protected]" "[email protected]"] :subject "OMG everything is down!"}
  "email/templates/warning.html.mustache" {:name "Joe" :host "host3.megacorp.internal"} :text/html)

;; build a message using alternative message body, specify alternative plain-text body in addition to main HTML body of the message
(build-email {:from "Joe The Robot", :to ["[email protected]" "[email protected]"] :subject "Hello!"}
             "templates/html_hello.mustache" {:name "Joe"} :text/html
             "templates/hello.mustache" {:name "Joe"} :text/plain)

;; deliver mail, uses *delivery-mode* value to determine how exactly perform the delivery, defaults to :text/plain
(deliver-email {:from "Joe The Robot", :to ["[email protected]" "[email protected]"] :subject "OMG everything is down!"}
  "email/templates/warning.mustache" {:name "Joe" :host "host3.megacorp.internal"})

;; deliver mail, specify html content type
(deliver-email {:from "Joe The Robot", :to ["[email protected]" "[email protected]"] :subject "OMG everything is down!"}
  "email/templates/warning.html.mustache" {:name "Joe" :host "host3.megacorp.internal"} :text/html)

;; deliver mail using alternative message body, specify alternative plain-text body in addition to main HTML body of the message
(deliver-email {:from "Joe The Robot", :to ["[email protected]" "[email protected]"] :subject "Hello!"}
               "templates/html_hello.mustache" {:name "Joe"} :text/html
               "templates/hello.mustache" {:name "Joe"} :text/plain)

;; alter message defaults, for example, From header
(with-defaults { :from "Joe The Robot <[email protected]>" :subject "[Do Not Reply] Warning! Achtung! Внимание!" }
  (send-warnings))

;; alter delivery mode (effective for current thread only):
(with-delivery-mode :smtp
  (do-something))

;; alter SMTP settings (effective for current thread only, only makes sense for :smtp delivery mode):
(with-settings { :host "smtp.megacorp.internal" }
  (with-delivery-mode :smtp
    (do-something-that-delivers-email-over-smtp)))

;; render a template
(render "templates/hello.mustache" {:name "Joe"}) ;; => "Hello, Joe"

Community

Mailer has a mailing list. Feel free to join it and ask any questions you may have.

To subscribe for announcements of releases, important changes and so on, please follow @ClojureWerkz on Twitter.

Supported Clojure versions

Mailer requires Clojure 1.6+.

Mailer Is a ClojureWerkz Project

Mailer is part of the group of libraries known as ClojureWerkz, together with Neocons, Monger, Langohr, Elastisch, Quartzite and several others.

Continuous Integration

Continuous Integration status

CI is hosted by travis-ci.org

Development

Mailer uses Leiningen 2. Make sure you have it installed and then run tests against all supported Clojure versions using

lein all test

Then create a branch and make your changes on it. Once you are done with your changes and all tests pass, submit a pull request on Github.

License

Copyright © 2012-2017 Michael S. Klishin, Alex Petrov, and the ClojureWerkz team.

Distributed under the Eclipse Public License, the same as Clojure.