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.
# 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
end
defmodule Sample.UserEmail do
import Swoosh.Email
def welcome(user) do
new
|> to({user.name, user.email})
|> from({"Dr B Banner", "[email protected]"})
|> subject("Hello, Avengers!")
|> html_body("<h1>Hello #{user.name}</h1>")
|> text_body("Hello #{user.name}\n")
end
end
# In an IEx session
Sample.UserEmail.welcome(%{name: "Tony Stark", email: "[email protected]"}) |> 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
end
end-
Add swoosh to your list of dependencies in
mix.exs:def deps do [{:swoosh, "~> 0.9.0"}] end
-
(Optional - only for Elixir < 1.4) Ensure swoosh is started before your application:
def application do [applications: [:swoosh]] end
-
(Optional) If you are using
Swoosh.Adapters.SMTPorSwoosh.Adapters.Sendmail, you also need to add gen_stmp to your deps and list of applications:# You only need to do this if you are using Elixir < 1.4 def application do [applications: [:swoosh, :gen_smtp]] end def deps do [{:swoosh, "~> 0.9.0"}, {:gen_smtp, "~> 0.12.0"}] end
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!
Swoosh does not make any special arrangements for sending emails in a non-blocking manner.
To send asynchronous emails in Swoosh, one can simply leverage Elixir's standard library:
Task.start(fn ->
%{name: "Tony Stark", email: "[email protected]"}
|> Sample.UserEmail.welcome
|> Sample.Mailer.deliver
end)Please take a look at the official docs for Task for further options.
Note: it is not to say that Task.start is enough to cover the whole async aspect of sending emails. It is more to say that
the implementation of sending emails is very application specific. For example, the simple example above might be sufficient
for some small applications but not so much for more mission critial applications. Runtime errors, network errors and errors
from the service provider all need to be considerred and handled, maybe differently as well. Whether to retry, how many times
you want to retry, what to do when everything fails, these questions all have different answers in different context.
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
<html>
<head>
<title><%= @email.subject %></title>
</head>
<body>
<%= render @view_module, @view_template, assigns %>
</body>
</html>
# web/templates/email/welcome.html.eex
<div>
<h1>Welcome to Sample, <%= @username %>!</h1>
</div>
# web/emails/user_email.ex
defmodule Sample.UserEmail do
use Phoenix.Swoosh, view: Sample.EmailView, layout: {Sample.LayoutView, :email}
def welcome(user) do
new
|> to({user.name, user.email})
|> from({"Dr B Banner", "[email protected]"})
|> subject("Hello, Avengers!")
|> render_body("welcome.html", %{username: user.username})
end
endFeels familiar doesn't it? Head to the phoenix_swoosh repo for more details.
You can attach files to your email using the Swoosh.Email.attachment/2 function. Just give the path of your
file as an argument and we will do the rest. It also works with a %Plug.Upload{} struct.
All built-in adapters have support for attachments.
new()
|> to("[email protected]")
|> from({"Jarvis", "[email protected]"})
|> subject("Invoice May")
|> text_body("Here is the invoice for your superhero services in May.")
|> attachment("/Users/jarvis/invoice-peter-may.pdf")
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: "[email protected]"})
assert_email_sent Sample.UserEmail.welcome(user)
end
endSwoosh 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.LocalThen, use the Mix task to start the mailbox preview server
$ mix swoosh.mailbox.serverOr 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"]
end
endIf 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!
Clone the repo and fetch its dependencies:
$ git clone https://github.com/swoosh/swoosh.git
$ cd swoosh
$ mix deps.get
$ mix test
$ MIX_ENV=docs mix docs
See LICENSE