Search documentation of phoenix_kit

# PhoenixKit.Emails.Event (phoenix_kit v1.6.19)

View Source

Email event schema for managing delivery events in PhoenixKit.

This schema records events that occur after email sending, such as delivery, bounce, complaint, open, and click events. These events are typically received from email providers like AWS SES through webhooks.

## Schema Fields

- `email_log_id`: Foreign key to the associated email log
- `event_type`: Type of event (send, delivery, bounce, complaint, open, click)
- `event_data`: JSONB map containing event-specific data from the provider
- `occurred_at`: Timestamp when the event occurred
- `ip_address`: IP address of the recipient (for open/click events)
- `user_agent`: User agent string (for open/click events)
- `geo_location`: JSONB map with geographic data (country, region, city)
- `link_url`: URL that was clicked (for click events)
- `bounce_type`: Type of bounce (hard, soft, for bounce events)
- `complaint_type`: Type of complaint (abuse, auth-failure, fraud, etc.)

## Event Types

- send: Email was successfully sent to the provider
- delivery: Email was successfully delivered to recipient's inbox
- bounce: Email bounced (permanent or temporary failure)
- complaint: Recipient marked email as spam
- open: Recipient opened the email (AWS SES tracking)
- click: Recipient clicked a link in the email

## Associations

- `email_log`: Belongs to the EmailLog that this event is associated with

## Usage Examples

    # Create a delivery event
    {:ok, event} = PhoenixKit.Emails.Event.create_event(%{
      email_log_id: log.id,
      event_type: "delivery",
      event_data: %{
        timestamp: "2024-01-15T10:30:00.000Z",
        smtp_response: "250 OK"
      }
    })

    # Create an open event with managing data
    {:ok, event} = PhoenixKit.Emails.Event.create_event(%{
      email_log_id: log.id,
      event_type: "open",
      ip_address: "192.168.1.1",
      user_agent: "Mozilla/5.0...",
      geo_location: %{country: "US", region: "CA", city: "San Francisco"}
    })

    # Get all events for an email
    events = PhoenixKit.Emails.Event.for_email_log(log_id)

# Summary

## Functions

change_event(email_event, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for managing email event changes.

changeset(email_event, attrs)

Creates a changeset for email event creation and updates.

create_bounce_event(email_log_id, bounce_type, reason \\ nil)

Creates a bounce event with bounce details.

create_click_event(email_log_id, link_url, ip_address \\ nil, user_agent \\ nil, geo_data \\ %{})

Creates a click event with link and managing data.

create_complaint_event(email_log_id, complaint_type \\ "abuse", feedback_id \\ nil)

Creates a complaint event with complaint details.

create_event(attrs \\ %{})

Creates an email event.

create_from_ses_webhook(email_log, webhook_data)

Creates a delivery event from AWS SES webhook data.

create_open_event(email_log_id, ip_address \\ nil, user_agent \\ nil, geo_data \\ %{})

Creates an open event with managing data.

create_queued_event(email_log_id)

Creates a queued event when email is queued for sending.

create_send_event(email_log_id, provider \\ nil)

Creates a send event when email is successfully sent to provider.

delete_event(email_event)

Deletes an email event.

event_exists?(email_log_id, event_type)

Checks if an event already exists for a specific email log and type.

for_email_log(email_log_id)

Gets all events for a specific email log.

for_email_log_by_type(email_log_id, event_type)

Gets events of a specific type for an email log.

for_period_by_type(start_date, end_date, event_type)

Gets events of a specific type within a time range.

get_event!(id)

Gets a single email event by ID.

get_event_stats(start_date, end_date)

Gets event statistics for a time period.

get_geo_distribution(event_type, start_date, end_date)

Gets geographic distribution of events.

get_latest_event_by_type(email_log_id, event_type)

Gets the most recent event of a specific type for an email log.

get_top_clicked_links(start_date, end_date, limit \\ 10)

Gets the most clicked links for a time period.

has_event_type?(email_log_id, event_type)

Checks if an event of a specific type exists for an email log.

update_event(email_event, attrs)

Updates an email event.

# Functions

# change_event(email_event, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for managing email event changes.

## Examples

    iex> PhoenixKit.Emails.Event.change_event(event)
    %Ecto.Changeset{data: %PhoenixKit.Emails.Event{}}

# changeset(email_event, attrs)

Creates a changeset for email event creation and updates.

Validates required fields and ensures data consistency. Automatically sets occurred_at on new records if not provided.

# create_bounce_event(email_log_id, bounce_type, reason \\ nil)

Creates a bounce event with bounce details.

## Examples

    iex> PhoenixKit.Emails.Event.create_bounce_event(log_id, "hard", "No such user")
    {:ok, %PhoenixKit.Emails.Event{}}

# create_click_event(email_log_id, link_url, ip_address \\ nil, user_agent \\ nil, geo_data \\ %{})

Creates a click event with link and managing data.

## Examples

    iex> PhoenixKit.Emails.Event.create_click_event(log_id, "https://example.com/link", "192.168.1.1")
    {:ok, %PhoenixKit.Emails.Event{}}

# create_complaint_event(email_log_id, complaint_type \\ "abuse", feedback_id \\ nil)

Creates a complaint event with complaint details.

## Examples

    iex> PhoenixKit.Emails.Event.create_complaint_event(log_id, "abuse")
    {:ok, %PhoenixKit.Emails.Event{}}

# create_event(attrs \\ %{})

Creates an email event.

## Examples

    iex> PhoenixKit.Emails.Event.create_event(%{
      email_log_id: 1,
      event_type: "delivery"
    })
    {:ok, %PhoenixKit.Emails.Event{}}

    iex> PhoenixKit.Emails.Event.create_event(%{event_type: "invalid"})
    {:error, %Ecto.Changeset{}}

# create_from_ses_webhook(email_log, webhook_data)

Creates a delivery event from AWS SES webhook data.

## Examples

    iex> data = %{
      "eventType" => "delivery",
      "mail" => %{"messageId" => "abc123"},
      "delivery" => %{"timestamp" => "2024-01-15T10:30:00.000Z"}
    }
    iex> PhoenixKit.Emails.Event.create_from_ses_webhook(log, data)
    {:ok, %PhoenixKit.Emails.Event{}}

# create_open_event(email_log_id, ip_address \\ nil, user_agent \\ nil, geo_data \\ %{})

Creates an open event with managing data.

## Examples

    iex> PhoenixKit.Emails.Event.create_open_event(log_id, "192.168.1.1", "Mozilla/5.0...")
    {:ok, %PhoenixKit.Emails.Event{}}

# create_queued_event(email_log_id)

Creates a queued event when email is queued for sending.

## Examples

    iex> PhoenixKit.Emails.Event.create_queued_event(log_id)
    {:ok, %PhoenixKit.Emails.Event{}}

# create_send_event(email_log_id, provider \\ nil)

Creates a send event when email is successfully sent to provider.

## Examples

    iex> PhoenixKit.Emails.Event.create_send_event(log_id)
    {:ok, %PhoenixKit.Emails.Event{}}

# delete_event(email_event)

Deletes an email event.

## Examples

    iex> PhoenixKit.Emails.Event.delete_event(event)
    {:ok, %PhoenixKit.Emails.Event{}}

# event_exists?(email_log_id, event_type)

Checks if an event already exists for a specific email log and type.

Returns true if an event of the given type already exists for the email log, false otherwise. This is used to prevent duplicate event creation.

## Examples

    iex> PhoenixKit.Emails.Event.event_exists?(log_id, "delivery")
    true

    iex> PhoenixKit.Emails.Event.event_exists?(log_id, "open")
    false

# for_email_log(email_log_id)

Gets all events for a specific email log.

Returns events ordered by occurred_at (most recent first).

## Examples

    iex> PhoenixKit.Emails.Event.for_email_log(log_id)
    [%PhoenixKit.Emails.Event{}, ...]

# for_email_log_by_type(email_log_id, event_type)

Gets events of a specific type for an email log.

## Examples

    iex> PhoenixKit.Emails.Event.for_email_log_by_type(log_id, "open")
    [%PhoenixKit.Emails.Event{}, ...]

# for_period_by_type(start_date, end_date, event_type)

Gets events of a specific type within a time range.

## Examples

    iex> PhoenixKit.Emails.Event.for_period_by_type(start_date, end_date, "click")
    [%PhoenixKit.Emails.Event{}, ...]

# get_event!(id)

Gets a single email event by ID.

Raises `Ecto.NoResultsError` if the event does not exist.

## Examples

    iex> PhoenixKit.Emails.Event.get_event!(123)
    %PhoenixKit.Emails.Event{}

# get_event_stats(start_date, end_date)

Gets event statistics for a time period.

## Examples

    iex> PhoenixKit.Emails.Event.get_event_stats(start_date, end_date)
    %{delivery: 1450, bounce: 30, open: 800, click: 200, complaint: 5}

# get_geo_distribution(event_type, start_date, end_date)

Gets geographic distribution of events.

## Examples

    iex> PhoenixKit.Emails.Event.get_geo_distribution("open", start_date, end_date)
    %{"US" => 500, "CA" => 200, "UK" => 150}

# get_latest_event_by_type(email_log_id, event_type)

Gets the most recent event of a specific type for an email log.

## Examples

    iex> PhoenixKit.Emails.Event.get_latest_event_by_type(log_id, "open")
    %PhoenixKit.Emails.Event{}

# get_top_clicked_links(start_date, end_date, limit \\ 10)

Gets the most clicked links for a time period.

## Examples

    iex> PhoenixKit.Emails.Event.get_top_clicked_links(start_date, end_date, 10)
    [%{url: "https://example.com/product", clicks: 150}, ...]

# has_event_type?(email_log_id, event_type)

Checks if an event of a specific type exists for an email log.

## Examples

    iex> PhoenixKit.Emails.Event.has_event_type?(log_id, "open")
    true

# update_event(email_event, attrs)

Updates an email event.

## Examples

    iex> PhoenixKit.Emails.Event.update_event(event, %{event_data: %{updated: true}})
    {:ok, %PhoenixKit.Emails.Event{}}