Mailer

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.

What it is not

A mass mailer, just don't do it.

Dependencies

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.

Usage

First compose an email with:

  email = Mailer.compose_email("from@example.com", "to@example.com", "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}}}

Configuration

In your applications config.exs file you need to add two sections.

Template configuration

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.

SMTP client configuration

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

Plain text or Multipart email

Mailer will automatically send multipart emails if you have both a .txt and .html in the template directory. The .html template is optional.

To send a welcome email:

Sending plain text only:

priv/templates/welcome/welcome.txt

Sending a multipart email:

priv/templates/welcome/welcome.txt
priv/templates/welcome/welcome.html

Internationalisation

When 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.html

By including the country code in the compose call, Mailer will render the correct localised template.

Mailer.compose_email("from@example.com", "to@example.com", "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 templates

Author

Copyright © 2014 Component X Software, Antony Pinchbeck

Released under Apache 2 License