AWS SES

This document describes the integration of AWS Simple Email Service (SES) as an email provider in the Campaign Service. It covers API usage, best practices, error handling, and architecture considerations.

How SES Works

• API: AWS SDK (SendRawEmail / SendTemplatedEmail). Prefer AWS SDK with IAM roles for servers in AWS.
• Authentication: IAM roles (preferred for ECS/EKS tasks) or IAM user keys stored securely.
• Capabilities: reputation metrics via SES, sending statistics, event publishing via SNS (deliveries, bounces, complaints, opens/clicks if using open tracking via Amazon Pinpoint or custom tracking).

Main considerations — AWS SES

• Best when you want to stay inside AWS ecosystem and leverage IAM, SNS, and CloudWatch directly.
• Typically lower cost at scale and integrates well with other AWS services (SNS, SQS, CloudWatch, Kinesis).
• Use when you need predictable scaling and strong operational control; plan for SNS wiring and domain verification steps.

Why we might NOT use SES

Short list of practical reasons SES can be a poor fit for some teams or workloads:

• Developer ergonomics: SES is AWS-centric and usually requires more setup (IAM, SNS, SQS) compared with provider-first REST APIs like Mailgun which are friendlier for rapid development and debugging.
• Built-in tracking limitations: SES doesn't provide simple built-in open/click tracking without Amazon Pinpoint; implementing reliable tracking requires extra infra (redirects, pixel endpoints) and increases engineering effort.
• Sandbox & quota restrictions: new SES accounts are in a sandbox with sending limits and restricted recipients until production access is requested — slows onboarding and testing.
• Event plumbing complexity: SES events arrive via SNS and often need SQS buffering and message verification, which is more operational work than webhook-based providers.
• Regional & account limits: SES is region-specific and has account-level quotas; multi-region or cross-account setups are more complex than global SaaS providers.
• Deliverability tooling: SES gives solid deliverability but fewer built-in tools for campaign-level tagging, suppression lists, or granular per-message analytics compared to specialist providers.

Tracking opens & clicks (SES)

SES does not provide built-in open/click tracking out of the box the way some email providers do (unless you use Amazon Pinpoint or advanced SES event packages). To track opens and clicks reliably you should implement application-level tracking alongside SES. Below are recommended approaches and operational considerations.

1. Tracking identifiers

• Generate a unique tracking id per message (e.g., uuid or deterministic id based on message id) and store it with the Message/StepExecution record.
• Include the tracking id in:
  • open pixel URL: https://tracking.example.com/open/[trackingId].gif
  • click URLs: https://tracking.example.com/click/[trackingId]?redirect=[base64-url]

2. Open tracking (pixel)

• Inject a 1x1 tracking pixel image in HTML emails that references your tracking endpoint.
• When the tracking pixel is requested, record an open event with timestamp, user-agent, and IP. Use HEAD requests or return a tiny GIF/png.
• Caveats: image-blocking and privacy protections (many clients block third-party images or proxy requests), so opens are an undercount. Use opens as directional signals, not absolute metrics.

3. Click tracking (redirect)

• Rewrite links in the email to pass through a tracker service that:
  • logs a click event with trackingId, recipient, and timestamp
  • optionally performs short-link lookups or safety checks
  • redirects to the final URL (HTTP 302)
• Deduplicate clicks by trackingId + normalized target URL + IP/session heuristics if you need unique-click metrics.

5. Aggregation & rate calculations

• Definitions:
  • sent_count = messages accepted by SES (or marked sent by your system)
  • delivered_count = messages received by inbox providers (SES delivery notifications / provider webhooks)
  • open_count = unique opens (unique trackingId or recipient+device fingerprint)
  • click_count = unique clicks

8. Monitoring & alerts

• Emit these metrics to CloudWatch: unique_opens, unique_clicks, delivered_count, bounce_count, complaint_count.
• Alert on:
  • bounce_rate > X% (per-account / per-domain)
  • complaint_rate > Y% (immediate paging)
  • sudden drop in open_rate or click_rate (possible deliverability/regression)

9. SES-specific options

• Amazon Pinpoint can provide built-in open/click tracking integrated with SES; consider it if you prefer managed tracking.
• Use SES configuration-sets + event publishing for deliveries/bounces/complaints; combine with your tracking endpoints for opens/clicks.

Tracking ingestion flow

If you want code snippets for a performant tracking endpoint (fast HTTP accept + enqueue), or example aggregation queries for computing open/click rates, I can add them next.