# Courier

Mail delivery for Elixir

[![Build Status](](

Courier is an OTP adapter-based mail delivery system for Elixir applications. It means serious business for sending emails.


It depends upon [`Mail`]( for composing the message.

First create your mailer:

defmodule MyApp.Mailer do
  use Courier, otp_app: :my_app

After this we need to add the Courier Supervisor to your tree. For
example, if you are using in a Phoenix app you can edit `lib/my_app.ex`

def start(_type, _args) do
  children = [
    supervisor(MyApp.Repo, []),
    supervisor(MyApp.Endpoint, []),

    # Mailer Supervisor
    supervisor(MyApp.Mailer, [])

Next set the default adapter in `config/config.exs` or `config/{environment}.exs`:

config :my_app, MyApp.Mailer,
  adapter: Courier.Adapters.SMTP,
  relay: "",
  hostname: "my-mail-server",
  port: 2525,
  username: System.get_env("COURIER_USERNAME"),
  password: System.get_env("COURIER_PASSWORD")

More configuration options for each adapter is in the [Adapters](#Adapters) section.

Then you can compose and deliver the message:

|> Mail.put_to("")
|> Mail.put_from("")
|> Mail.put_subject("How are things?")
|> Mail.put_text("Let's meet for drinks!")
|> Mail.put_html("<p>Let's meet for drinks!</p>")
|> MyApp.Mailer.deliver()

Courier will deliver the message through the adapter that is configured.

## Deliveries

All deliveries are pushed into a shceduler and sent out asynchronously.
Let's learn how to customize this scheduler

### Scheduling deliveries

By default if you do not specify a datetime to delivery `at` Courier
will mark the message for immediate delivery. But let's say we want to
schedule a specific datetime to send a message. You can do that with:

MyApp.Mailer.deliver(message, at: datetime)

The `datetime` variable should conform to either an Erlang calendar
tuple `{{year, month, day}, {hour, minute, second}}`

### Pooling

Courier will use a pool to rate limit the number of concurrent messages
being sent. This is necessary if you are sending to services that hate
their own rate limits. The default pool size is `10`. If you'd like to
change this default you can simply modify when configuring your mailer:

config :my_app, MyApp.Mailer,
  pool_size: 15

[Read more about the Scheduler, configuring it, and using

## Rendering with Phoenix Views

If you'd like to render the `text` or `html` parts with a Phoenix view
you should use `Courier.render/4`

|> Mail.put_to("")
|> Mail.put_from("")
|> Mail.put_subject("How are things?")
|> Courier.render(MyApp.MailerView, "check_in.txt", user: user)
|> Courier.render(MyApp.MailerView, "check_in.html", user: user)
|> MyApp.Mailer.deliver()

`Courier.render/4` will parse the template path to determine the
expected `content-type`. For example, if your template is `foobar.html`
the assumed `content-type` is `text/html` and Courier will render the
template to a string and use `Mail.put_html(message, rendered_template)`

## Adapters

Courier comes with some built-in adapters

### Courier.Adapters.SMTP

The built-in SMTP adapter is implemented with [`gen_smtp`](


- `relay` mail server host
- `port` mail server port (defaults to `25` when `ssl` is `false`, defaults to `465` when `ssl` is `true`)
- `ssl` connect with SSL (defaults to `false`)
- `hostname` label for the `relay`
- `username` username used for authentication
- `password` password used for authentication

### Courier.Adapters.Logger

Will write deliver all messages to the `Logger`. All attachment encoded data will
render as `[File content]`

- `level` the `Logger` level to send the message to (defaults to `:info`)

### Courier.Adapters.Test

Exposes the ETS adapter from a REST based API

### Courier.Adapters.Web

CourierWeb adds a web interface for viewing the messages sent. To use it
add the library to your `mix.exs` file.  For more information on this adapter please refer to

### Writing your own adapter

Creating your own adapter is simple. The only functions necessary are
`start_link/1` and `deliver/2`

defmodule MyApp.Adapters.Custom do
  def start_link(_opts), do: :ignore

  def deliver(%Mail.Message{} = message, opts) do
    # your customized mailer

The `message` passed into `deliver/2` is not a rendered [RFC2822]( message.
If you need the rendered version you can use `mail` to render it:

rendered_message = Mail.render(message, Mail.Renderers.RFC2822)

Please refer to the `mail` library to learn more about creating custom
message renderers.

Each adapter is treated as its own OTP supervisor within your mailer's
supervisor tree. This will give you the opportunity to create more
complex adapters with their own workers. Just override
`start_link/1` however you'd like. The configuration options declared
for your mailer within the given mix environment are passed in as the

## Authors ##

* [Brian Cardarella](

[We are very thankful for the many contributors](

## Versioning ##

This library follows [Semantic Versioning](

## Looking for help with your Elixir project? ##

[At DockYard we are ready to help you build your next Elixir project]( We have a unique expertise in Elixir and Phoenix development that is unmatched. [Get in touch!](

At DockYard we love Elixir! You can [read our Elixir blog posts](
or come visit us at [The Boston Elixir Meetup]( that we organize.

## Want to help? ##

Please do! We are always looking to improve this library. Please see our
[Contribution Guidelines](
on how to properly submit issues and pull requests.

## Legal ##

[DockYard](, Inc. &copy; 2016


[Licensed under the MIT license](