# `PhoenixKit.Modules.Emails.Templates`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1)

Context module for managing email templates.

This module provides the business logic and database operations for email templates,
including CRUD operations, template rendering, variable substitution, and usage tracking.

## Main Functions

- `list_templates/1` - List templates with filtering and pagination
- `get_template/1` - Get template by ID
- `get_template_by_name/1` - Get template by name
- `create_template/1` - Create a new template
- `update_template/2` - Update existing template
- `delete_template/1` - Delete template
- `render_template/2` - Render template with variables

## Examples

    # List all active templates
    Templates.list_templates(%{status: "active"})

    # Get template by name
    template = Templates.get_template_by_name("magic_link")

    # Render template with variables
    Templates.render_template(template, %{"user_name" => "John", "url" => "https://example.com"})

# `activate_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L300)

Activates an email template by setting its status to "active".

## Examples

    iex> Templates.activate_template(template)
    {:ok, %Template{status: "active"}}

# `archive_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L282)

Archives an email template by setting its status to "archived".

## Examples

    iex> Templates.archive_template(template)
    {:ok, %Template{status: "archived"}}

# `billing_credit_note_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1676)

Returns the HTML template for billing credit note emails.

IMPORTANT: In a credit note, the roles are reversed compared to invoice:
- The company (seller) is now the PAYER (issuing the refund)
- The customer is now the PAYEE (receiving the refund)

# `billing_credit_note_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1811)

Returns the text template for billing credit note emails.

# `billing_invoice_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1276)

Returns the HTML template for billing invoice emails.

# `billing_invoice_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1429)

Returns the text template for billing invoice emails.

# `billing_payment_confirmation_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1868)

Returns the HTML template for billing payment confirmation emails.

# `billing_payment_confirmation_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1986)

Returns the text template for billing payment confirmation emails.

# `billing_receipt_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1483)

Returns the HTML template for billing receipt emails.

# `billing_receipt_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1619)

Returns the text template for billing receipt emails.

# `clone_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L318)

Clones an existing template with a new name.

## Examples

    iex> Templates.clone_template(template, "new_welcome_email")
    {:ok, %Template{name: "new_welcome_email"}}

# `count_templates`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L89)

Returns the count of templates matching the given filters.

# `create_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L194)

Creates a new email template.

## Examples

    iex> Templates.create_template(%{name: "welcome", subject: "Welcome!", ...})
    {:ok, %Template{}}

    iex> Templates.create_template(%{invalid: "data"})
    {:error, %Ecto.Changeset{}}

# `delete_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L257)

Deletes an email template.

System templates (is_system: true) cannot be deleted.

## Examples

    iex> Templates.delete_template(template)
    {:ok, %Template{}}

    iex> Templates.delete_template(system_template)
    {:error, :system_template_protected}

# `get_active_template_by_name`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L174)

Gets an active template by name.

Only returns templates with status "active".

## Examples

    iex> Templates.get_active_template_by_name("magic_link")
    %Template{}

# `get_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L110)

Gets a template by ID.

Returns `nil` if the template does not exist.

## Examples

    iex> Templates.get_template(1)
    %Template{}

    iex> Templates.get_template(999)
    nil

# `get_template!`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L134)

Gets a template by ID, raising an exception if not found.

## Examples

    iex> Templates.get_template!(1)
    %Template{}

    iex> Templates.get_template!(999)
    ** (Ecto.NoResultsError)

# `get_template_by_name`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L155)

Gets a template by name.

Returns `nil` if the template does not exist.

## Examples

    iex> Templates.get_template_by_name("magic_link")
    %Template{}

    iex> Templates.get_template_by_name("nonexistent")
    nil

# `get_template_stats`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L510)

Gets template statistics for dashboard display.

Returns a map with various statistics about templates.

## Examples

    iex> Templates.get_template_stats()
    %{
      total_templates: 10,
      active_templates: 8,
      draft_templates: 1,
      archived_templates: 1,
      system_templates: 4,
      most_used: %Template{},
      categories: %{"system" => 4, "transactional" => 6}
    }

# `list_templates`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L78)

Lists templates with optional filtering and pagination.

## Parameters

- `opts` - Keyword list with filtering options:
  - `:category` - Filter by category ("system", "marketing", "transactional")
  - `:status` - Filter by status ("active", "draft", "archived")
  - `:search` - Search in name, display_name, or description
  - `:is_system` - Filter by system templates (true/false)
  - `:limit` - Limit number of results
  - `:offset` - Offset for pagination
  - `:order_by` - Order by field (:name, :usage_count, :last_used_at, :inserted_at)
  - `:order_direction` - Order direction (:asc, :desc)

## Examples

    # List all templates
    Templates.list_templates()

    # List active marketing templates
    Templates.list_templates(%{category: "marketing", status: "active"})

    # Search templates
    Templates.list_templates(%{search: "welcome"})

    # Paginated results
    Templates.list_templates(%{limit: 10, offset: 20})

# `magic_link_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L876)

Returns the HTML template for magic link emails.

# `magic_link_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L928)

Returns the text template for magic link emails.

# `register_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L949)

Returns the HTML template for registration confirmation emails.

# `register_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L999)

Returns the text template for registration confirmation emails.

# `render_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L383)

Renders a template with the provided variables for a specific locale.

Returns a map with `:subject`, `:html_body`, and `:text_body` keys containing
the rendered content with variables substituted in the requested language.

This function performs validation to ensure all template variables are properly substituted:
- Checks for missing required variables
- Warns if any unreplaced `{{variable}}` placeholders remain
- Logs information about unused variables

## Parameters
- `template` — the EmailTemplate struct
- `variables` — map of variable names to values
- `locale` — the target locale code (default: `"en"`)

## Examples

    iex> Templates.render_template(template, %{"user_name" => "John"}, "uk")
    %{
      subject: "Ласкаво просимо, John!",
      html_body: "<h1>Ласкаво просимо, John!</h1>",
      text_body: "Ласкаво просимо, John!"
    }

## Validation

If required variables are missing or templates contain unreplaced variables,
warnings will be logged but the function will still return the rendered content.
This allows for graceful degradation in production.

# `reset_password_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1018)

Returns the HTML template for password reset emails.

# `reset_password_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1068)

Returns the text template for password reset emails.

# `seed_system_templates`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L572)

Seeds the database with system email templates.

This function creates the default system templates for authentication
and core functionality.

## Examples

    iex> Templates.seed_system_templates()
    {:ok, [%Template{}, ...]}

# `send_email`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L467)

Sends an email using a template.

This is a convenience wrapper around `PhoenixKit.Mailer.send_from_template/4`
that provides a cleaner API for sending templated emails.

## Parameters

- `template_name` - Name of the template (e.g., "welcome_email")
- `recipient` - Email address or {name, email} tuple
- `variables` - Map of template variables
- `opts` - Additional options (see `PhoenixKit.Mailer.send_from_template/4`)

## Examples

    # Send welcome email
    Templates.send_email("welcome_email", user.email, %{
      "user_name" => user.name,
      "activation_url" => activation_url
    })

    # Send with tracking
    Templates.send_email(
      "order_confirmation",
      customer.email,
      %{"order_number" => order.number},
      user_uuid: customer.uuid,
      metadata: %{order_uuid: order.uuid}
    )

# `test_email_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1087)

Returns the HTML template for test emails.

# `test_email_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1166)

Returns the text template for test emails.

# `track_usage`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L482)

Increments the usage count for a template and updates last_used_at.

This should be called whenever a template is used to send an email.

## Examples

    iex> Templates.track_usage(template)
    {:ok, %Template{usage_count: 1}}

# `update_email_html_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1207)

Returns the HTML template for email update confirmation emails.

# `update_email_text_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L1257)

Returns the text template for email update confirmation emails.

# `update_template`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.71/lib/modules/emails/templates.ex#L221)

Updates an existing email template.

## Examples

    iex> Templates.update_template(template, %{subject: "New Subject"})
    {:ok, %Template{}}

    iex> Templates.update_template(template, %{invalid: "data"})
    {:error, %Ecto.Changeset{}}

---

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