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

Email interceptor for logging outgoing emails in PhoenixKit.

This module provides functionality to intercept outgoing emails and create
comprehensive logs for tracking purposes. It integrates seamlessly with
the existing mailer system without disrupting email delivery.

## Features

- **Transparent Interception**: Logs emails without affecting delivery
- **Selective Logging**: Respects sampling rate and system settings
- **AWS SES Integration**: Automatically adds configuration sets
- **Rich Metadata Extraction**: Captures headers, size, attachments
- **User Context**: Links emails to users when possible
- **Template Recognition**: Identifies email templates and campaigns

## Integration

The interceptor is designed to be called by the mailer before sending:

    # In PhoenixKit.Mailer.deliver_email/1
    email = EmailInterceptor.intercept_before_send(email, opts)
    # ... then send email normally

## Configuration

The interceptor respects all email tracking system settings:

- Only logs if `email_enabled` is true
- Saves body based on `email_save_body` setting
- Applies sampling rate from `email_sampling_rate`
- Adds AWS SES configuration set if configured

## Examples

    # Basic interception
    logged_email = PhoenixKit.Modules.Emails.Interceptor.intercept_before_send(email)

    # With additional context
    logged_email = PhoenixKit.Modules.Emails.Interceptor.intercept_before_send(email,
      user_uuid: "018f1234-5678-7890-abcd-ef1234567890",
      template_name: "welcome_email",
      campaign_id: "welcome_series"
    )

    # Check if email should be logged
    if PhoenixKit.Modules.Emails.Interceptor.should_log_email?(email) do
      # Log the email
    end

# `add_tracking_headers`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.62/lib/modules/emails/interceptor.ex#L174)

Adds tracking headers to an email for identification.

## Examples

    iex> email_with_headers = PhoenixKit.Modules.Emails.Interceptor.add_tracking_headers(email, log, [])
    %Swoosh.Email{headers: %{"X-PhoenixKit-Log-Id" => "123"}}

# `build_ses_headers`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.62/lib/modules/emails/interceptor.ex#L199)

Builds AWS SES specific tracking headers and configuration.

## Examples

    iex> PhoenixKit.Modules.Emails.Interceptor.build_ses_headers(log, [])
    %{"X-SES-CONFIGURATION-SET" => "my-tracking-set"}

# `create_email_log`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.62/lib/modules/emails/interceptor.ex#L160)

Creates an email log entry from a Swoosh.Email struct.

## Examples

    iex> PhoenixKit.Modules.Emails.Interceptor.create_email_log(email, user_uuid: "018f1234-5678-7890-abcd-ef1234567890")
    {:ok, %Log{}}

# `detect_provider`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.62/lib/modules/emails/interceptor.ex#L136)

Extracts provider information from email or mailer configuration.

## Examples

    iex> PhoenixKit.Modules.Emails.Interceptor.detect_provider(email, [])
    "aws_ses"

# `intercept_before_send`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.62/lib/modules/emails/interceptor.ex#L83)

Intercepts an email before sending and creates a tracking log.

Returns the email (potentially modified with tracking headers) and
creates a log entry if tracking is enabled.

## Options

- `:user_uuid` - Associate with a specific user
- `:template_name` - Name of the email template
- `:campaign_id` - Campaign identifier for grouping
- `:provider` - Override provider detection
- `:configuration_set` - Override AWS SES configuration set
- `:message_tags` - Additional tags for the email

## Examples

    iex> email = new() |> to("user@example.com") |> from("app@example.com")
    iex> PhoenixKit.Modules.Emails.Interceptor.intercept_before_send(email, user_uuid: "018f1234-5678-7890-abcd-ef1234567890")
    %Swoosh.Email{headers: %{"X-PhoenixKit-Log-Id" => "456"}}

# `should_log_email?`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.62/lib/modules/emails/interceptor.ex#L112)

Determines if an email should be logged based on system settings.

Considers sampling rate, system enablement, and email characteristics.

## Examples

    iex> PhoenixKit.Modules.Emails.Interceptor.should_log_email?(email)
    true

# `update_after_failure`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.62/lib/modules/emails/interceptor.ex#L357)

Updates an email log after send failure.

## Examples

    iex> PhoenixKit.Modules.Emails.Interceptor.update_after_failure(log, error)
    {:ok, %Log{}}

# `update_after_send`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.62/lib/modules/emails/interceptor.ex#L242)

Updates an email log after successful sending.

This is called after the email provider confirms the send.

## Examples

    iex> PhoenixKit.Modules.Emails.Interceptor.update_after_send(log, provider_response)
    {:ok, %Log{}}

---

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