Compose, deliver and test your emails easily in Elixir.
Swoosh comes with many adapters, including SendGrid, Mandrill, Mailgun, Postmark and SMTP. See the full list of adapters below.
The complete documentation for Swoosh is available online at HexDocs.
Elixir 1.13+ and Erlang OTP 24+
# 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
enddefmodule 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
email = Sample.UserEmail.welcome(%{name: "Tony Stark", email: "[email protected]"})
Sample.Mailer.deliver(email)# 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!(params)
UserEmail.welcome(user) |> Mailer.deliver()
end
endSee Swoosh.Mailer for more
configuration options.
-
Add swoosh to your list of dependencies in
mix.exs:def deps do [{:swoosh, "~> 1.16"}] end
-
(Optional-ish) Most adapters (non SMTP ones) use
Swoosh.ApiClientto talk to the service provider. Swoosh comes withSwoosh.ApiClient.Hackneyconfigured by default. If you want to use it, you just need to includeHackneyas a dependency of your app.Swoosh also accepts
FinchandReqout-of-the-box. SeeSwoosh.ApiClient.FinchandSwoosh.ApiClient.Reqfor details.If you need to integrate with another HTTP client, it's easy to define a new API client. Follow the
Swoosh.ApiClientbehaviour and configure Swoosh to use it:config :swoosh, :api_client, MyApp.ApiClient
But if you don't need
Swoosh.ApiClient, you can disable it by setting the value tofalse:config :swoosh, :api_client, false
This is the case when you are using
Swoosh.Adapters.Local,Swoosh.Adapters.Testand adapters that are SMTP based, that don't require an API client. -
(Optional) If you are using
Swoosh.Adapters.SMTP,Swoosh.Adapters.SendmailorSwoosh.Adapters.AmazonSES, you also need to addgen_smtpto your dependencies:def deps do [ {:swoosh, "~> 1.6"}, {:gen_smtp, "~> 1.0"} ] end
Swoosh supports the most popular transactional email providers out of the box and also has an SMTP adapter. Below is the list of the adapters currently included:
| Provider | Swoosh adapter | Remarks |
|---|---|---|
| SMTP | Swoosh.Adapters.SMTP | |
| Mua | Swoosh.Adapters.Mua | SMTP alternative |
| SendGrid | Swoosh.Adapters.Sendgrid | |
| Brevo | Swoosh.Adapters.Brevo | Sendinblue |
| Sendmail | Swoosh.Adapters.Sendmail | |
| Mandrill | Swoosh.Adapters.Mandrill | |
| Mailgun | Swoosh.Adapters.Mailgun | |
| Mailjet | Swoosh.Adapters.Mailjet | |
| MsGraph | Swoosh.Adapters.MsGraph | |
| Postmark | Swoosh.Adapters.Postmark | |
| SparkPost | Swoosh.Adapters.SparkPost | |
| Amazon SES | Swoosh.Adapters.AmazonSES | |
| Amazon SES | Swoosh.Adapters.ExAwsAmazonSES | |
| Dyn | Swoosh.Adapters.Dyn | |
| Scaleway | Swoosh.Adapters.Scaleway | |
| SocketLabs | Swoosh.Adapters.SocketLabs | |
| Gmail | Swoosh.Adapters.Gmail | |
| MailPace | Swoosh.Adapters.MailPace | OhMySMTP |
| SMTP2GO | Swoosh.Adapters.SMTP2GO | |
| ProtonBridge | Swoosh.Adapters.ProtonBridge | |
| Mailtrap | Swoosh.Adapters.Mailtrap | |
| ZeptoMail | Swoosh.Adapters.ZeptoMail |
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.)Check the documentation of the adapter you want to use for more specific configurations and instructions.
Adding new adapters is super easy and we are definitely looking for contributions on that front. Get in touch if you want to help!
The Recipient Protocol enables you to easily make your structs compatible with Swoosh functions.
defmodule MyUser do
@derive {Swoosh.Email.Recipient, name: :name, address: :email}
defstruct [:name, :email, :other_props]
endNow you can directly pass %MyUser{} to from, to, cc, bcc, etc.
See Swoosh.Email.Recipient for more details.
Swoosh does not make any special arrangements for sending emails in a non-blocking manner. Opposite to some stacks, sending emails, talking to third party apps, etc in Elixir do not block or interfere with other requests, so you should resort to async emails only when necessary.
One simple way to deliver emails asynchronously is by leveraging Elixir's
standard library. First add a Task supervisor to your application root,
usually at lib/my_app/application.ex:
def start(_, _) do
children = [
...,
# Before the endpoint
{Task.Supervisor, name: MyApp.AsyncEmailSupervisor},
MyApp.Endpoint
]
Supervisor.start_link(children, strategy: :one_for_one)
endNow, whenever you want to send an email:
Task.Supervisor.start_child(MyApp.AsyncEmailSupervisor, fn ->
%{name: "Tony Stark", email: "[email protected]"}
|> Sample.UserEmail.welcome()
|> Sample.Mailer.deliver()
end)Please take a look at the official docs for Task and Task.Supervisor for further options.
One of the downsides of sending email asynchronously is that failures won't be reported to the user, who won't have an opportunity to try again immediately, and tasks by default do not retry on errors. Therefore, if the email must be delivered asynchronously, a safer solution would be to use a queue or job system. Elixir's ecosystem has many job queue libraries.
- Oban is the current community favourite. It uses PostgreSQL for storage and coordination.
- Exq uses Redis and is compatible with Resque / Sidekiq.
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, or a %Swoosh.Attachment{}
struct, which can be constructed using Swoosh.Attachment.new detailed here in
the docs.
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, MyApp.Mailer,
adapter: Swoosh.Adapters.LocalIn your Phoenix project you can forward directly to the plug
without spinning up a separate webserver, like this:
# in web/router.ex
if Mix.env == :dev do
scope "/dev" do
pipe_through [:browser]
forward "/mailbox", Plug.Swoosh.MailboxPreview
end
endYou can also start a new server if your application does not depends on Phoenix:
# in config/dev.exs
# to run the preview server alongside your app
# which may not have a web interface already
config :swoosh, serve_mailbox: true# in config/dev.exs
# to change the preview server port (4000 by default)
config :swoosh, serve_mailbox: true, preview_port: 4001When using serve_mailbox: true make sure to have either plug_cowboy or
bandit as a dependency of your app.
{:plug_cowboy, ">= 1.0.0"}
# or
{:bandit, ">= 1.0.0"}And finally you can also use the following Mix task to start the mailbox preview server independently:
mix swoosh.mailbox.serverNote: the mailbox preview won't display emails
being sent from outside its own node. So if you are testing using an IEx session,
it's recommended to boot the application in the same session.
iex -S mix phx.server or iex -S mix swoosh.mailbox.server will do the trick.
If you are curious, this is how it the mailbox preview looks like:
Note : To show the preview we use the cdn-version of Tailwindcss. If you have set a content-security-policy you may have to add https://cdn.tailwindcss.com to default-src to have the correct make up.
The preview is also available as a JSON endpoint.
curl http://localhost:4000/dev/mailbox/jsonSwoosh starts a memory storage process for local adapter by default. Normally it does no harm being left around in production. However, if it is causing problems, or you don't like having it around, it can be disabled like so:
# config/prod.exs
config :swoosh, local: falseThe following events are emitted:
[:swoosh, :deliver, :start]: occurs whenMailer.deliver/2begins.[:swoosh, :deliver, :stop]: occurs whenMailer.deliver/2completes.[:swoosh, :deliver, :exception]: occurs whenMailer.deliver/2throws an exception.[:swoosh, :deliver_many, :start]: occurs whenMailer.deliver_many/2begins.[:swoosh, :deliver_many, :stop]: occurs whenMailer.deliver_many/2completes.[:swoosh, :deliver_many, :exception]: occurs whenMailer.deliver_many/2throws an exception.
View example in docs
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 testMIX_ENV=docs mix docsSee LICENSE
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent