@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.

@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.

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.

@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.

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

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_id - 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_id: user.id,
  campaign_id: "password_recovery"
)

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

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

Send a test tracking email to verify email delivery and tracking functionality.

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

This function sends a test email with test links to verify that the email tracking system is working correctly.

Parameters

• recipient_email - The email address to send the test email to
• user_id - Optional user ID to associate with the test email (default: nil)

Returns

• {:ok, %Swoosh.Email{}} - Email sent successfully
• {:error, reason} - Email failed to send

Examples

iex> PhoenixKit.Mailer.send_test_tracking_email("admin@example.com")
{:ok, %Swoosh.Email{}}

iex> PhoenixKit.Mailer.send_test_tracking_email("admin@example.com", 123)
{:ok, %Swoosh.Email{}}