# `PhoenixKit.Modules.Emails.SQSProcessor`
[🔗](https://github.com/BeamLabEU/phoenix_kit_emails/blob/0.4.2/lib/phoenix_kit/modules/emails/sqs_processor.ex#L1)

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.

# `parse_sns_message`

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`

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

---

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