PhoenixKit.Emails.Event (phoenix_kit v1.5.2)

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