Sending Email from a Phoenix App

A step-by-step guide to sending emails from a Phoenix web app (Elixir). If you don’t have any on hand - don’t worry, we will show you also how to create a Phoenix app, then how to write your first mailer to be sent from it and how to preview emails during development. Let’s go!

Phoenix is gaining traction as a highly useful web application framework, built on the Elixir language. Today we want to take you through a simple example where you can send email directly from a Phoenix app. It’s all part of learning to embrace new technologies designed to make your web applications easier and more efficient to build.

For sending emails from a Phoenix web app we will use the bamboo library. First, let’s look at the configuration process and walk through creating a simple Phoenix web app - in case you don’t have one you can follow our guide with code snippets.

Configuration

Let’s first up create a Phoenix app:

mix local.hex
mix archive.install https://github.com/phoenixframework/archives/raw/master/phx_new.ez
mix phx.new email_sender
cd email_sender

If you are creating an app for the first time, make sure your database config is correct - check config/{dev.exs|test.exs} files and look for the config :email_sender, EmailSender.Repo line.

The next thing to do is to generate a mail resource for our app:

mix phx.gen.html Mailing Message messages to:string subject:string body:string

Let’s then add our new resource’s endpoint to the router so we can perform basic CRUD operations (Create, Read, Update, Delete) on it:

# lib/email_sender_web/router.ex

defmodule EmailSenderWeb.Router do
  ...

  scope "/", EmailSenderWeb do
    ...
    resources "/messages", MessageController
  end
end

and migrate the database:

mix ecto.migrate

This way when you open /messages you will see a simple interface to manage your message records.

In order to send emails we need to add the bamboo library to our dependencies in the mix.exs file:

# mix.exs
def application do
  [
    mod: {EmailSender.Application, []},
    extra_applications: [:logger, :bamboo, :bamboo_smtp, :runtime_tools]
  ]
end

def deps do
  [
    ...
    {:bamboo, "~> 0.8"},
    {:bamboo_smtp, "~> 1.4.0"}
  ]
end

Now we can install the new dependencies:

mix deps.get

We also need to configure our application to use the Bamboo.LocalAdapter adapter for sending emails in our dev environment and the Bamboo.TestAdapter adapter in our test environment:

# config/dev.exs

...

config :email_sender, EmailSender.Mailer,
  adapter: Bamboo.LocalAdapter


# config/test.exs

...

config :email_sender, EmailSender.Mailer,
  adapter: Bamboo.TestAdapter

For our production config you can use the Bamboo.SMTPAdapter adapter, but remember about using environment variables for specifying SMTP credentials:

# config/prod.exs

...

config :email_sender, EmailExample.Mailer,
  adapter: Bamboo.SMTPAdapter,
  server: System.get_env("SMTP_SERVER") ,
  port: 1025,
  username: System.get_env("SMTP_USERNAME"),
  password: System.get_env("SMTP_PASSWORD"),
  tls: :if_available, # can be `:always` or `:never`
  ssl: false, # can be `true`
  retries: 1

...

Now we need to create our mailer module, that we previously specified in the config files:

# lib/email_sender/mailer.ex
defmodule EmailSender.Mailer do
  use Bamboo.Mailer, otp_app: :email_sender
end

First mailer

We now have a Phoenix web app ready, so we can move on to writing our first mailer. Let’s start by writing a test first so we can progress in the proven style of TDD (Test Driven Development):

# test/email_sender/email_test.exs
defmodule EmailSender.EmailTest do
  use ExUnit.Case
  use Bamboo.Test

  test "create" do
    email = EmailSender.Email.create("user@test.com",
                                     "test subject",
                                     "<h1>Hello!</h1>")
    assert email.to == "user@test.com"
    assert email.subject == "test subject"
    assert email.html_body =~ "Hello!"
  end
end

Since an email is just a struct it’s easy to test it. We can check the email’s content using the =~ operator, which compares if the html_body contains the text specified on the right of the operator.

If we run our tests with the mix test command, we should see an error similar to the one below:

** (UndefinedFunctionError) function EmailSender.Email.create/3 is undefined (module EmailSender.Email is not available)

Let’s make the test pass by implementing a simple mailer:

# lib/email_sender/email.ex
defmodule EmailSender.Email do
  import Bamboo.Email

  def create(to, subject, body) do
    new_email()
    |> to(to)
    |> from("me@example.com")
    |> subject(subject)
    |> html_body(body)
  end
end

Now, in order to send a message from the app, we need to call the new create method on the EmailSender.Email module and pass it to our Mailer:

email = EmailSender.Email.create("jdoe@mail.com", "Hello mail", "<h1>Hi Joe</h1>")
EmailSender.Mailer.deliver_now(email) # or EmailSender.Mailer.deliver_later(email)

Let’s run our tests again to ensure we made our test pass. Did yours pass? Ours did - so far so good.

Now we need to connect our Email with the Message record in the controller, so an email will be sent whenever a new message is created in the system.

Like before, we will start with test-first approach.

Let’s add a new test to the EmailSenderWeb.MessageControllerTest module:

# test/email_sender_web/controllers/message_controller_test.exs

defmodule EmailSenderWeb.MessageControllerTest do
  use EmailSenderWeb.ConnCase
  use Bamboo.Test

  ...

  describe "create message" do
    ...

    test "email is sent when data is valid", %{conn: conn} do
      post conn, message_path(conn, :create), message: @create_attrs

      assert_delivered_email EmailSender.Email.create(@create_attrs[:to],
                                                      @create_attrs[:subject],
                                                      @create_attrs[:body])
    end

    ...
  end

  ...
end

If we run our tests again, we will see a failing test:

There were 0 emails delivered to this process.

     If you expected an email to be sent, try these ideas:

     1) Make sure you call deliver_now/1 or deliver_later/1 to deliver the email
     2) Make sure you are using the Bamboo.TestAdapter
     3) Use shared mode with Bamboo.Test. This will allow Bamboo.Test
     to work across processes: use Bamboo.Test, shared: :true
     4) If you are writing an acceptance test through a headless browser, use
     shared mode as described in option 3.

Let’s make it green by updating the create action in the controller:

# lib/email_sender_web/controllers/message_controller.ex

defmodule EmailSenderWeb.MessageController do
  ...
  def create(conn, %{"message" => message_params}) do
    case Mailing.create_message(message_params) do
      {:ok, message} ->
        email = EmailSender.Email.create(message.to, message.subject, message.body)
        EmailSender.Mailer.deliver_now(email)

        conn
        |> put_flash(:info, "Message created successfully.")
        |> redirect(to: message_path(conn, :show, message))
      {:error, %Ecto.Changeset{} = changeset} ->
        render(conn, "new.html", changeset: changeset)
    end
  end
  ...
end

Now we should see all our tests pass again.

Email preview during development

Let’s not stop there, but instead broaden our options - by adding a feature that previews sent emails while developing the app, by adding an additional route to our router:

# lib/email_sender_web/router.ex

defmodule EmailSenderWeb.Router do
  ...

  if Mix.env == :dev do
    forward "/sent_emails", Bamboo.EmailPreviewPlug
  end
end

When we create a new message, the new email should appear in the /sent_emails mailbox:

Note: Remember that Bamboo.LocalAdapter must be used to make the email appear in the mailbox.

And that’s it! Your first mailer from a Phoenix web app is ready to be sent. Pretty easy, right? If you need other IT solutions or help in creating mobile or web apps - contact us! We’d love to see Elixir and Phoenix in more projects and are keen to help out!