Introducing Swoosh Gallery

At Remote, we send many kinds of emails to our customers: emails about new payments, invoices, approved time off, onboarding new employees, and so on. There are so many emails, we needed to make sure we did not lose count of all the emails we send! This is the story of how we solved that issue — and how it can help you, too!

Swoosh

We use Swoosh to build and send out our application’s emails. It is easy to use, and it has many adapters that you can choose. It also has a really cool feature in which you can see all the outgoing emails of your app during the development time. For instance, you could open a tab at http://localhost:4000/dev/mailbox, click the button of your app to send an email, and see the email you sent sent pop up there.

The Swoosh Mailbox is really handy, but there are a few gotchas:

• If you want to see the preview of the email, first you have to make your app send it by going through the process of submitting a new invoice or inviting a new user to your team.

• It’s a development-time-only thing. If you were to expose this in production, you would expose private data from all your emails.

What if we could see the email just like in the mailbox, but with fake data and without going through all the hoops to send it?

Introducing Swoosh Gallery

We came up with Swoosh Gallery, a library that displays all the Swoosh emails of your Elixir app into a single place.

With Swoosh Gallery, you can gather all your emails in a single place and see all the information you had in Swoosh’s Mailbox without the need of manually sending it. You can also reuse all the email setup you already have in place; you just need to provide some preview fake data.

Getting started with Swoosh Gallery

1. Add the dependency to your app.

1def deps do
2  [
3    {:swoosh_gallery, "~> 0.1.0"}
4  ]
5end

2. Create a Gallery module, that will hold all the emails you want to preview, using a path and the module responsible for building the email:

1defmodule MyApp.Mailer.Gallery do
2  use Swoosh.Gallery
3
4  preview "/welcome", MyApp.Mailer.WelcomeMailer
5end

3. In you WelcomeMailer module, implement two new methods: preview/0 and preview_details/0. They are used to build your email struct and provide details such as title and description in the gallery page.

1defmodule MyApp.Mailer.WelcomeMailer do
2  # the expected Swoosh / Phoenix.Swoosh code that you already have to deliver emails
3  use Phoenix.Swoosh, view: SampleWeb.WelcomeMailerView, layout: {MyApp.LayoutView, :email}
4
5  def welcome(user) do
6    new()
7    |> from("noreply@sample.test")
8    |> to({user.name, user.email})
9    |> subject("Welcome to Sample App")
10    |> render_body("welcome.html", user: user)
11  end
12
13  # `preview/0` function that builds your email using fixture data
14  def preview do
15    user = %{email: "user@sample.test", name: "Test User!"}
16    welcome(user)
17  end
18
19  # `preview_details/0` with some useful metadata about your mailer
20  def preview_details do
21    [
22      title: "Welcome to MyApp!",
23      description: "First email to welcome users into the platform",
24      tags: [step: "onboarding"]
25    ]
26  end
27end
28

4. For the last step, mount the Gallery on your app’s router:

1forward "/dev/gallery", MyApp.Mailer.Gallery

Now, if you access http://localhost:4000/dev/gallery in your browser, you should see the “Welcome” email above with all the information you need! Add more emails to the gallery, and now you have a single place for all your emails!

Static Gallery pages

Another cool feature from the Swoosh Gallery is that you can generate static pages with it, so you can host it in GitHub Pages, Netlify, or Vercel, for example. In the root of your project, run the command below:

1mix swoosh.gallery.html --gallery MyApp.Mailer.Gallery --path "_build/emails"

Now, open _build/emails/index.html and you should see the same page from the gallery above!

Fast email building feedback

You can use this during development time to see how your email is being rendered without having to send it. There are cases in which sending an email requires a long setup of the app or creating a new account manually through the browser, but with the Swoosh Gallery, you just open the gallery and see it!

What will you do with Swoosh Gallery?

Swoosh Gallery is our new open source library that integrates with Swoosh to display and organize your emails in a single place without having to send manually. You can use it during development time, in production, or by sharing the gallery as static pages. This helps all stakeholders of the company know what is sent to customers and helps developers quickly see the changes done to the email.