PhoenixKit.Modules.Emails.SQSProcessor (phoenix_kit_emails v0.1.16)

Copy Markdown View Source

Processor for handling email events from AWS SQS messages.

This module is responsible for:

  • Parsing SNS messages from SQS
  • Processing different types of SES events
  • Updating email statuses in the database
  • Creating event records for tracking

Supported Event Types

  • Send - Email send confirmation through SES
  • Delivery - Successful email delivery to recipient
  • Bounce - Email bounce (hard/soft bounce)
  • Complaint - Spam complaint
  • Open - Email open (AWS SES tracking)
  • Click - Link click in email

Processing Architecture

SQS Message → SNS Parsing → Event Processing → Database Update

Security

  • Message structure validation
  • Event type checking
  • Protection against event duplication
  • Graceful handling of invalid data

Examples

# Parse SNS message
{:ok, event_data} = SQSProcessor.parse_sns_message(sqs_message)

# Process event
{:ok, result} = SQSProcessor.process_email_event(event_data)

process_email_event/1's normalized event-data contract

process_email_event/1 itself is provider-agnostic: it only cares that event_data matches AWS SES's own notification shape, %{"eventType" => type, "mail" => %{"messageId" => id}, "<type>" => %{...}}. This is a stable, public contract — any provider's events can be routed through it once translated into this shape, without touching this module. BrevoPollingJob/BrevoEventNormalizer do exactly that for Brevo's GET /v3/smtp/statistics/events events; parse_sns_message/1 and extract_ses_event/1 above remain AWS SES/SNS-specific and are not part of this contract.

Summary

Functions

parse_sns_message(arg1)

Parses SNS message from SQS into event data structure.

process_email_event(event_data)

Processes a normalized email event and updates corresponding database records. Provider-agnostic — see this module's @moduledoc for the exact event_data contract every caller (SES via SNS, Brevo via BrevoEventNormalizer, ...) must produce.

Functions

parse_sns_message(arg1)

Parses SNS message from SQS into event data structure.

Parameters

  • sqs_message - message from SQS queue

Returns

  • {:ok, event_data} - successfully parsed event data
  • {:error, reason} - parsing error

Examples

iex> SQSProcessor.parse_sns_message(sqs_message)
{:ok, %{
  "eventType" => "delivery",
  "mail" => %{"messageId" => "abc123"},
  "delivery" => %{"timestamp" => "2025-09-20T15:30:45.000Z"}
}}

process_email_event(event_data)

Processes a normalized email event and updates corresponding database records. Provider-agnostic — see this module's @moduledoc for the exact event_data contract every caller (SES via SNS, Brevo via BrevoEventNormalizer, ...) must produce.

Parameters

  • event_data - normalized event data, %{"eventType" => type, "mail" => %{"messageId" => id}, "<type>" => %{...}}

Returns

  • {:ok, result} - successful processing
  • {:error, reason} - processing error

Examples

iex> SQSProcessor.process_email_event(event_data)
{:ok, %{type: "delivery", log_uuid: "019...", updated: true}}