Search documentation of phoenix_kit

# PhoenixKit.Mailer (phoenix_kit v1.7.87)

Copy Markdown View Source

Mailer module for PhoenixKit emails.

This module handles sending emails such as confirmation emails, password reset emails, magic link emails, etc.

It can work in two modes:

1. Built-in mode: Uses PhoenixKit's own Swoosh mailer (default)
2. Delegation mode: Uses the parent application's mailer when configured

## Configuration

To use your application's mailer instead of PhoenixKit's built-in one:

    config :phoenix_kit,
      mailer: MyApp.Mailer

When delegation is configured, all emails will be sent through your application's mailer, allowing you to use a single mailer configuration across your entire application.

## Summary

### Functions

deliver(email, config \\ [])

Delivers an email.

deliver!(email, config \\ [])

Delivers an email, raises on error.

deliver_email(email, opts \\ [])

Delivers an email using the appropriate mailer.

deliver_many(emails, config \\ [])

Delivers a list of emails.

get_mailer()

Gets the mailer module to use for sending emails.

send_from_template(template_name, recipient, variables \\ %{}, opts \\ [])

Sends an email using a template from the database.

send_magic_link_email(user, magic_link_url)

Sends a magic link email to the user.

## Functions

# deliver(email, config \\ [])

    @spec deliver(Swoosh.Email.t(), Keyword.t()) :: {:ok, term()} | {:error, term()}

Delivers an email.

If the email is delivered it returns an `{:ok, result}` tuple. If it fails, returns an `{:error, error}` tuple.

# deliver!(email, config \\ [])

    @spec deliver!(Swoosh.Email.t(), Keyword.t()) :: term() | no_return()

Delivers an email, raises on error.

If the email is delivered, it returns the result. If it fails, it raises a `DeliveryError`.

# deliver_email(email, opts \\ [])

Delivers an email using the appropriate mailer.

If a parent application mailer is configured, delegates to it. Otherwise uses the built-in PhoenixKit mailer.

This function also integrates with the email tracking system to log outgoing emails when tracking is enabled.

# deliver_many(emails, config \\ [])

    @spec deliver_many(
      [
        %Swoosh.Email{
          assigns: term(),
          attachments: term(),
          bcc: term(),
          cc: term(),
          from: term(),
          headers: term(),
          html_body: term(),
          private: term(),
          provider_options: term(),
          reply_to: term(),
          subject: term(),
          text_body: term(),
          to: term()
        }
      ],
      Keyword.t()
    ) :: {:ok, term()} | {:error, term()}

Delivers a list of emails.

It accepts a list of `%Swoosh.Email{}` as its first parameter.

# get_mailer()

Gets the mailer module to use for sending emails.

Returns the configured parent application mailer if set, otherwise returns the built-in PhoenixKit.Mailer.

## Examples

    iex> PhoenixKit.Mailer.get_mailer()
    MyApp.Mailer  # if configured

    iex> PhoenixKit.Mailer.get_mailer()
    PhoenixKit.Mailer  # default

# send_from_template(template_name, recipient, variables \\ %{}, opts \\ [])

Sends an email using a template from the database.

This is the main function for sending emails using PhoenixKit's template system. It automatically:

- Loads the template by name
- Renders it with provided variables
- Tracks template usage
- Sends the email with tracking
- Logs to EmailSystem

## Parameters

- `template_name` - Name of the template in the database (e.g., "welcome_email")
- `recipient` - Email address (string) or {name, email} tuple
- `variables` - Map of variables to substitute in the template
- `opts` - Additional options:
  - `:user_uuid` - Associate email with a user (for tracking)
  - `:campaign_id` - Campaign identifier (for analytics)
  - `:from` - Override from address (default: configured from_email)
  - `:reply_to` - Reply-to address
  - `:metadata` - Additional metadata map for tracking

## Returns

- `{:ok, email}` - Email sent successfully
- `{:error, :template_not_found}` - Template doesn't exist
- `{:error, :template_inactive}` - Template is not active
- `{:error, reason}` - Other error

## Examples

    # Simple welcome email
    PhoenixKit.Mailer.send_from_template(
      "welcome_email",
      "user@example.com",
      %{"user_name" => "John", "url" => "https://app.com"}
    )

    # With user tracking
    PhoenixKit.Mailer.send_from_template(
      "password_reset",
      {"Jane Doe", "jane@example.com"},
      %{"reset_url" => "https://app.com/reset/token123"},
      user_uuid: user.uuid,
      campaign_id: "password_recovery"
    )

    # With metadata
    PhoenixKit.Mailer.send_from_template(
      "order_confirmation",
      customer.email,
      %{"order_id" => "12345", "total" => "$99.99"},
      user_uuid: customer.uuid,
      campaign_id: "orders",
      metadata: %{order_id: order.id, amount: order.total}
    )

# send_magic_link_email(user, magic_link_url)

Sends a magic link email to the user.

Uses the 'magic_link' template from the database if available, falls back to hardcoded template if not found.

## Examples

    iex> PhoenixKit.Mailer.send_magic_link_email(user, "https://app.com/magic/token123")
    {:ok, %Swoosh.Email{}}