Swoosh

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.

Requirements

Elixir 1.16+ and Erlang OTP 26+

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
end

defmodule Sample.UserEmail do
  import Swoosh.Email

  def welcome(user) do
    new()
    |> to({user.name, user.email})
    |> from({"Dr B Banner", "hulk.smash@example.com"})
    |> 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: "tony.stark@example.com"})
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
end

See Swoosh.Mailer for more configuration options.

Installation

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

  def deps do
    [{:swoosh, "~> 1.24"}]
  end
  

• (Optional-ish) Most adapters (non SMTP ones) use Swoosh.ApiClient to talk to the service provider. Swoosh comes with Swoosh.ApiClient.Hackney configured by default. If you want to use it, you just need to include Hackney as a dependency of your app.

  Swoosh also accepts Finch and Req out-of-the-box. See Swoosh.ApiClient.Finch and Swoosh.ApiClient.Req for details.

  If you need to integrate with another HTTP client, it's easy to define a new API client. Follow the Swoosh.ApiClient behaviour 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 to false:

  config :swoosh, :api_client, false
  

  This is the case when you are using Swoosh.Adapters.Local, Swoosh.Adapters.Test and adapters that are SMTP based, that don't require an API client.

• (Optional) If you are using Swoosh.Adapters.SMTP, Swoosh.Adapters.Sendmail or Swoosh.Adapters.AmazonSES, you also need to add gen_smtp to your dependencies:

  def deps do
    [
      {:swoosh, "~> 1.6"},
      {:gen_smtp, "~> 1.0"}
    ]
  end
  

Adapters

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 | | | MailerSend | Swoosh.Adapters.Mailersend | | | 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 | | | Customer.io | Swoosh.Adapters.CustomerIO | | | 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 | | | Postal | Swoosh.Adapters.Postal | | | Lettermint | Swoosh.Adapters.Lettermint | | | Resend | Swoosh.Adapters.Resend | | | Azure Communication Services | Swoosh.Adapters.AzureCommunicationServices | | | ------ | Below are not fully featured services | ------ | | Loops | Swoosh.Adapters.Loops | | | PostUp | Swoosh.Adapters.PostUp | |

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!

For local development and tests, t