A simple SMTP mailer.
This can be used to send one off emails such welcome emails after signing up to a service or password recovery emails.
Mailer is built upon gen_smtp and uses it to deliver emails.
A mass mailer, just don't do it.
Add the following to your applications dependency block in mix.exs.
{:mailer, github: "antp/mailer"}Then run mix deps.get.
Mailer uses gen_smtp to provide the mailing infrastructure.
First compose an email with:
email = Mailer.compose_email("[email protected]", "[email protected]", "Subject", "welcome_template", template_data)Then send the email with:
response = Mailer.send(email)The response can be checked for failed deliveries.
Successful deliveries will have OK in the response such as:
"2.0.0 Ok: queued as 955CBC01C2\r\n"
Failed deliveries will have a response similar to:
{:error, :retries_exceeded,
{:network_failure, "xxx.xxx.xxx.xxx", {:error, :ehostunreach}}}
In your applications config.exs file you need to add two sections.
Add a section to detail the location of the templates
config :mailer,
templates: "priv/templates"The mailer will look for all templates under this path. If you pass 'welcome' as the template name, mailer will look in priv/templates/welcome to locate the template file.
The path is relative to the directory that the application is run from. For a normal application setting priv/templates is correct. If you're application is part of an umbrella application then you will need to set it to the path within the apps directory such as:
config :mailer,
templates: "apps/site_mailer/priv/templates"if you run your application from the main umbrella directory.
As mailer uses gen_smtp it requires a server to relay mails through.
The smtp configuration is passed through to gen_smtp, so all options that gen_smtp supports are available.
| Option: | Values: |
|---|---|
| server | Address of the email server to relay through. |
| hostname | Hostname of your mail client |
| transport | :smtp -> deliver mail using smtp (default) :test -> deliver mail to a test server |
| username | username to use in authentication |
| password | password for the username |
| tls | :always -> always use TLS :never -> never use TLS :if_available -> use TLS if available (default) |
| ssl | :true -> use SSL :false -> do not use SSL (default) |
| auth | :if_available -> use authentication if available (default) |
| retries | Number of retries before a send failure is reported defaults to 1 |
Mailer will automatically send multipart emails if you have both a .txt and .html in the template directory. The .html template is optional.
Sending plain text only:
priv/templates/welcome/welcome.txtSending a multipart email:
priv/templates/welcome/welcome.txt
priv/templates/welcome/welcome.htmlWhen sending a mail it is possible to add a country code. When the mail is composed this will be added to the template path to further qualify the template lookup.
If for example to wanted to support both English and French the template directory structure would look like the following:
priv/templates/welcome/en/welcome.txt
priv/templates/welcome/en/welcome.html
priv/templates/welcome/fr/welcome.txt
priv/templates/welcome/fr/welcome.htmlBy including the country code in the compose call, Mailer will render the correct localised template.
Mailer.compose_email("[email protected]", "[email protected]", "Subject", "welcome", data, "en")if the template files are not found in the language directory Mailer will look for a default template to send in the parent directory.
priv/templates/welcome <- default location of templates
priv/templates/welcome/<country_code> <- internationalised templatesCopyright © 2014 Component X Software, Antony Pinchbeck
Released under Apache 2 License