Swoosh

https://hexdocs.pm/swoosh/v1.19.8/
Admin
Swoosh is an Elixir library for composing, delivering, and testing emails with support for multiple...
Tokens:2,530
Snippets:27
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Mailbox Preview Server

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

This command starts the Swoosh mailbox preview server independently. It is recommended to run this in the same IEx session as your application if testing email sending from within that session.

```mix
mix swoosh.mailbox.server

```

--------------------------------

### Configure Swoosh Mailer Adapter

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Sets up the Swoosh mailer in the Elixir application configuration. This example shows how to configure it to use the SendGrid adapter with an API key.

```elixir
config :sample, Sample.Mailer,
  adapter: Swoosh.Adapters.Sendgrid,
  api_key: "SG.x.x"
```

--------------------------------

### Assert Email Sent in Elixir Tests with Swoosh

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Provides an example of how to test if an email was sent using `assert_email_sent/1` from `Swoosh.TestAssertions`. This is typically used within an Elixir test suite after an action that should trigger an email.

```elixir
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: "tony.stark@example.com"})
    assert_email_sent Sample.UserEmail.welcome(user)
  end
end
```

--------------------------------

### Clone Swoosh Repository and Fetch Dependencies

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Commands to clone the Swoosh project repository from GitHub, navigate into the directory, and fetch its dependencies using Mix.

```bash
git clone https://github.com/swoosh/swoosh.git
cd swoosh
mix deps.get

```

--------------------------------

### Run Swoosh Tests

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

This command executes the test suite for the Swoosh project after dependencies have been fetched.

```mix
mix test

```

--------------------------------

### Build Swoosh Documentation

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Command to build the project's documentation, typically for publishing to HexDocs. It sets the MIX_ENV to 'docs' before running the documentation task.

```mix
MIX_ENV=docs mix docs

```

--------------------------------

### Create Email Structure with Swoosh

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Defines a module for creating email structures using Swoosh. It imports `Swoosh.Email` and defines a function to construct a welcome email with sender, recipient, subject, and body.

```elixir
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
```

--------------------------------

### Fetch Mailbox Preview as JSON

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

This `curl` command demonstrates how to fetch the mailbox preview data as a JSON endpoint. It is useful for programmatic access to the preview data.

```bash
curl http://localhost:4000/dev/mailbox/json

```

--------------------------------

### Send Email in Phoenix Controller with Swoosh

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Shows how to integrate Swoosh email sending within a Phoenix controller. It creates a user, then generates and delivers a welcome email using the `Sample.Mailer`.

```elixir
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
```

--------------------------------

### Enable Mailbox Preview Server in Elixir Config

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Configures Swoosh to serve the mailbox preview directly as a standalone server in development. This is useful for applications that do not have a web interface. It can be configured in `config/dev.exs`.

```elixir
config :swoosh, serve_mailbox: true
```

--------------------------------

### Configure Local Mailer Adapter for Development in Elixir

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Shows how to set the mailer adapter to `Swoosh.Adapters.Local` in `config/dev.exs`. This adapter allows for previewing emails in a local, in-memory mailbox during development.

```elixir
config :sample, MyApp.Mailer,
  adapter: Swoosh.Adapters.Local
```

--------------------------------

### Send Email Asynchronously using Task.Supervisor in Elixir

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Demonstrates how to initiate an asynchronous email sending process using `Task.Supervisor.start_child/2`. This is useful when you want to send emails without blocking the main request flow. The provided function will be executed asynchronously.

```elixir
Task.Supervisor.start_child(MyApp.AsyncEmailSupervisor, fn ->
  %{name: "Tony Stark", email: "tony.stark@example.com"}
  |> Sample.UserEmail.welcome()
  |> Sample.Mailer.deliver()
end)
```

--------------------------------

### Forward to Mailbox Preview Plug in Phoenix Router

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

This Elixir code snippet shows how to forward requests to the `Plug.Swoosh.MailboxPreview` plug within a Phoenix project's router, specifically for the development environment. This enables viewing emails in the browser.

```elixir
if Mix.env == :dev do
  scope "/dev" do
    pipe_through [:browser]

    forward "/mailbox", Plug.Swoosh.MailboxPreview
  end
end
```

--------------------------------

### Configure Swoosh Mailer Adapter for Testing in Elixir

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Shows how to configure the mailer adapter to `Swoosh.Adapters.Test` in `config/test.exs`. This enables the use of `Swoosh.TestAssertions` for testing email sending in your Elixir applications.

```elixir
config :sample, MyApp.Mailer, adapter: Swoosh.Adapters.Test
```

--------------------------------

### Send Email in IEx Session with Swoosh

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Demonstrates how to send an email from an IEx session using Swoosh. It first creates an email structure and then passes it to the configured Mailer for delivery.

```elixir
email = Sample.UserEmail.welcome(%{name: "Tony Stark", email: "tony.stark@example.com"})
Sample.Mailer.deliver(email)
```

--------------------------------

### Add Swoosh Dependency to Mix Project

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Specifies how to add Swoosh as a dependency in a Mix project's `mix.exs` file. This ensures Swoosh is available for use in the Elixir application.

```elixir
def deps do
  [{:swoosh, "~> 1.19"}]
end
```

--------------------------------

### Configure Swoosh Adapter to SMTP

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Sets the Swoosh mailer adapter to use the `Swoosh.Adapters.SMTP`. This configuration snippet shows how to specify the adapter in `config/config.exs` and includes a placeholder for adapter-specific configurations.

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

--------------------------------

### Configure Swoosh API Client

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Configures Swoosh to use a custom API client. This allows integration with different HTTP client libraries or custom implementations for making API requests to email providers.

```elixir
config :swoosh, :api_client, MyApp.ApiClient
```

--------------------------------

### Configure Task Supervisor for Async Emails in Elixir

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

This snippet shows how to add a Task.Supervisor to your Elixir application's root for handling asynchronous email sending. This helps in preventing blocking operations. Ensure this is added before the endpoint in your application's child specification.

```elixir
def start(_type, _args) do
  children = [
    ...,
    # Before the endpoint
    {Task.Supervisor, name: MyApp.AsyncEmailSupervisor},
    MyApp.Endpoint
  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end
```

--------------------------------

### Configure Mailbox Preview Server Port in Elixir

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Allows customization of the port on which the Swoosh mailbox preview server runs. By default, it's port 4000. This configuration is set in `config/dev.exs`.

```elixir
config :swoosh, serve_mailbox: true, preview_port: 4001
```

--------------------------------

### Define Swoosh Mailer Module

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Defines a Mailer module using Swoosh's `use` macro. This module will handle email sending operations for the application, specifying the OTP application it belongs to.

```elixir
defmodule Sample.Mailer do
  use Swoosh.Mailer, otp_app: :sample
end
```

--------------------------------

### Attach Files to Emails using Swoosh in Elixir

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Illustrates how to add file attachments to an email using Swoosh. The `attachment/2` function accepts a file path. It also supports `%Plug.Upload{}` and `%Swoosh.Attachment{}` structs for more complex scenarios.

```elixir
new()
|> to("peter@example.com")
|> from({"Jarvis", "jarvis@example.com"})
|> subject("Invoice May")
|> text_body("Here is the invoice for your superhero services in May.")
|> attachment("/Users/jarvis/invoice-peter-may.pdf")
```

--------------------------------

### Configure Custom JSON Library for Swoosh in Elixir

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Demonstrates how to configure Swoosh to use a different JSON library, such as Elixir's built-in `JSON` module, instead of the default `Jason`. This is done in the `config/config.exs` file.

```elixir
config :swoosh, :json_library, JSON
```

--------------------------------

### Add gen_smtp Dependency for SMTP Adapters

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Includes `gen_smtp` as a dependency when using SMTP-based Swoosh adapters like `Swoosh.Adapters.SMTP`, `Swoosh.Adapters.Sendmail`, or `Swoosh.Adapters.AmazonSES`. This library is required for handling SMTP communication.

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

--------------------------------

### Define Recipient Protocol for Swoosh

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Demonstrates how to make a custom struct compatible with Swoosh's recipient functions using the `@derive {Swoosh.Email.Recipient, ...}` macro. This allows instances of `MyUser` to be used directly with `from`, `to`, `cc`, and `bcc`.

```elixir
defmodule MyUser do
  @derive {Swoosh.Email.Recipient, name: :name, address: :email}
  defstruct [:name, :email, :other_props]
end
```

--------------------------------

### Disable Local Storage in Production

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Configuration snippet for disabling Swoosh's default memory storage process in production environments by setting `:local` to `false` in `config/prod.exs`.

```elixir
config :swoosh, local: false

```

--------------------------------

### Disable Swoosh API Client

Source: https://hexdocs.pm/swoosh/v1.19.8/swoosh

Configures Swoosh to disable its API client. This is useful when using adapters that do not require an API client, such as SMTP-based adapters or testing adapters.

```elixir
config :swoosh, :api_client, false
```
Tokens:
Raw