# `PhoenixKit.Mailer`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.108/lib/phoenix_kit/mailer.ex#L1)

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.

# `deliver`

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

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

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`

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

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`

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{}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*