Subscribe Free

Join 2670+ others. No spamming.
I promise!

We are currently under high development. Follow us at github.

Looking for Python Tutorials?
Check these awesome tutorials



swoosh / swoosh


Compose, deliver and test your emails easily in Elixir -



Build Status Inline docs Deps Status

Compose, deliver and test your emails easily in Elixir.

We have applied the lessons learned from projects like Plug, Ecto and Phoenix in designing clean and composable APIs, with clear separation of concerns between modules. Out of the box it comes with adapters for Sendgrid, Mandrill, Mailgun, Postmark and SparkPost, as well as SMTP.

The complete documentation for Swoosh is located here.

Getting started

# In your config/config.exs file
config :sample, Sample.Mailer,
  adapter: Swoosh.Adapters.Sendgrid,
  api_key: "SG.x.x"

# In your application code
defmodule Sample.Mailer do
  use Swoosh.Mailer, otp_app: :sample

defmodule Sample.UserEmail do
  import Swoosh.Email

  def welcome(user) do
    |> to({,})
    |> from({"Dr B Banner", ""})
    |> subject("Hello, Avengers!")
    |> html_body("<h1>Hello #{}</h1>")
    |> text_body("Hello #{}\n")

# In an IEx session
Sample.UserEmail.welcome(%{name: "Tony Stark", email: ""}) |> Sample.Mailer.deliver

# Or in a Phoenix controller
defmodule Sample.UserController do
  use Phoenix.Controller
  alias Sample.UserEmail
  alias Sample.Mailer

  def create(conn, params) do
    user = # create user logic
    UserEmail.welcome(user) |> Mailer.deliver


  1. Add swoosh to your list of dependencies in mix.exs:

    def deps do
      [{:swoosh, "~> 0.7.0"}]
  2. Ensure swoosh is started before your application:

    def application do
      [applications: [:swoosh]]
  3. (Optional) If you are using Swoosh.Adapters.SMTP or Swoosh.Adapters.Sendmail, you also need to add gen_stmp to your deps and list of applications:

    def application do
      [applications: [:swoosh, :gen_smtp]]
    def deps do
      [{:swoosh, "~> 0.7.0"},
       {:gen_smtp, "~> 0.11.0"}]


Swoosh supports the most popular transactional email providers out of the box and also has a SMTP adapter. Below is the list of the adapters currently included:

Provider Swoosh adapter
SMTP Swoosh.Adapters.SMTP
Sendgrid Swoosh.Adapters.Sendgrid
Mandrill Swoosh.Adapters.Mandrill
Mailgun Swoosh.Adapters.Mailgun
Postmark Swoosh.Adapters.Postmark
SparkPost Swoosh.Adapters.SparkPost

Configure which adapter you want to use by updating your config/config.exs file:

config :sample, Sample.Mailer,
  adapter: Swoosh.Adapters.SMTP
  # adapter config (api keys, etc.)

Adding new adapters is super easy and we are definitely looking for contributions on that front. Get in touch if you want to help!

Phoenix integration

If you are looking to use Swoosh in your Phoenix project, make sure to check out the phoenix_swoosh project. It contains a set of functions that make it easy to render the text and HTML bodies using Phoenix views, templates and layouts.

Taking the example from above the "Getting Started" section, your code would look something like this:

# web/templates/layout/email.html.eex
    <title><%= @email.subject %></title>
    <%= render @view_module, @view_template, assigns %>

# web/templates/email/welcome.html.eex
  <h1>Welcome to Sample, <%= @username %>!</h1>

# web/emails/user_email.ex
defmodule Sample.UserEmail do
  use Phoenix.Swoosh, view: Sample.EmailView, layout: {Sample.LayoutView, :email}

  def welcome(user) do
    |> to({,})
    |> from({"Dr B Banner", ""})
    |> subject("Hello, Avengers!")
    |> render_body("welcome.html", %{username: user.username})

Feels familiar doesn't it? Head to the phoenix_swoosh repo for more details.


In your config/test.exs file set your mailer's adapter to Swoosh.Adapters.Test so that you can use the assertions provided by Swoosh in Swoosh.TestAssertions module.

defmodule Sample.UserTest do
  use ExUnit.Case, async: true

  import Swoosh.TestAssertions

  test "send email on user signup" do
    # Assuming `create_user` creates a new user then sends out a `Sample.UserEmail.welcome` email
    user = create_user(%{username: "ironman", email: ""})
    assert_email_sent Sample.UserEmail.welcome(user)

Mailbox preview in the browser

Swoosh ships with a Plug that allows you to preview the emails in the local (in-memory) mailbox. It's particularly convenient in development when you want to check what your email will look like while testing the various flows of your application.

For email to reach this mailbox you will need to set your Mailer adapter to Swoosh.Adapters.Local:

# in config/dev.exs
config :sample, Mailer,
  adapter: Swoosh.Adapters.Local

Then, use the Mix task to start the mailbox preview server

$ mix swoosh.mailbox.server

Or in your Phoenix project you can forward directly to the plug, like this:

# in web/router.ex
if Mix.env == :dev do
  scope "/dev" do
    pipe_through [:browser]

    forward "/mailbox", Plug.Swoosh.MailboxPreview, [base_path: "/dev/mailbox"]

If you are curious, this is how it looks:



Documentation is written into the library, you will find it in the source code, accessible from iex and of course, it all gets published to hexdocs.


We are grateful for any contributions. Before you submit an issue or a pull request, remember to:

  • Look at our Contributing guidelines
  • Not use the issue tracker for help or support requests (try StackOverflow, IRC or Slack instead)
  • Do a quick search in the issue tracker to make sure the issues hasn't been reported yet.
  • Look and follow the Code of Conduct. Be nice and have fun!

Running tests

Clone the repo and fetch its dependencies:

$ git clone
$ cd swoosh
$ mix deps.get
$ mix test

Building docs

$ MIX_ENV=docs mix docs