SES Webhook Processing

Relay receives real-time email lifecycle events from Amazon SES via an SNS-to-webhook pipeline. These events update email logs, trigger suppressions, and power analytics.

Event Pipeline

SES → SNS Topic → HTTPS Webhook → Relay API → Cosmos DB

1. SES sends an event when an email is delivered, bounced, complained about, opened, or clicked
2. SNS (Simple Notification Service) forwards the event to Relay's webhook endpoint
3. Relay processes the event, updates the email log, and takes action (suppression, alerts)
4. Cosmos DB stores the updated log entry and metrics

The SES configuration set theonerelay-events routes all events to the SNS topic theonerelay-ses-events.

Event Types

Event	What It Means	Action Taken
Delivery	Recipient's mail server accepted the email	Log status → delivered, record delivered_at
Bounce	Email could not be delivered	Log status → bounced, record bounce type. Hard bounces add to suppression list
Complaint	Recipient marked email as spam	Log status → complained, add to suppression list
Open	Recipient opened the email (tracking pixel loaded)	Record opened_at (first open), increment open_count
Click	Recipient clicked a tracked link	Add URL to clicked_links array
Reject	SES rejected the email before sending	Log status → rejected, record reason

Event Processing Details

Delivery Events

When SES confirms delivery:

• Email log status updates from sent to delivered
• delivered_at timestamp is recorded
• Daily stats delivered counter increments

Bounce Events

When a bounce occurs:

• Email log status updates to bounced
• bounce_type (Permanent/Transient) and bounce_sub_type are recorded
• For permanent bounces: recipient address is added to the suppression list
• For transient bounces: no suppression; SES retries automatically
• Daily stats bounced counter increments
• Bus event relay.email.bounced is emitted

Complaint Events

When a complaint is received:

• Email log status updates to complained
• Recipient address is added to the suppression list with reason complaint
• Daily stats complained counter increments
• Bus event relay.email.complained is emitted

Open and Click Events

• Opens: opened_at set on first open, open_count incremented on each open
• Clicks: Clicked URL appended to clicked_links array
• Daily stats opened and clicked counters increment

Webhook Security

The webhook endpoint validates incoming requests:

• SNS message signature verification — Confirms the request came from AWS SNS
• Topic ARN validation — Only accepts events from the configured SNS topic
• Subscription confirmation — Handles SNS subscription confirmation automatically

ℹ️The webhook endpoint is public (no API key required) because SNS cannot send authentication headers. Security relies on SNS signature verification.

Application Webhooks

You can configure Relay to forward processed events to your own application webhook. This is useful for real-time notifications when emails bounce or are delivered.

To set up:

1. Go to Settings
2. Add one or more Webhook URLs
3. Relay forwards processed events to these URLs with the event type, message ID, and relevant data

Relay retries failed webhook deliveries with exponential backoff.

Bus Events

Relay emits The One Bus events for key email lifecycle changes:

Bus Event	When
relay.email.sent	Email successfully submitted to SES
relay.email.bounced	Email bounced (includes bounce type)
relay.email.complained	Recipient filed a spam complaint
relay.alert.bounce_rate	Hourly bounce rate exceeds threshold
relay.email.inbound	Inbound email received and routed

Other products subscribe to these events for their own processing (e.g., PSA can show delivery status on ticket notifications).