Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

```html

Automating Email Campaign Management: Building a Multi-Platform Blast System with SES Suppression List Integration

What Was Done

This session focused on implementing an automated email campaign management system that integrates Amazon SES (Simple Email Service) suppression list management with a multi-platform contact outreach strategy. The core work involved:

  • Refactoring /Users/cb/Documents/repos/tools/jada_blast.py to support batch email delivery with intelligent bounce handling
  • Integrating SES suppression list exports to clean contact databases before campaign execution
  • Creating task card infrastructure for platform-specific outreach workflows (GetMyBoat, WeddingWire, and other non-live platforms)
  • Implementing a "widening-gap cadence" strategy to progressively expand contact reach while respecting bounce constraints

Technical Details: The Blast Script Architecture

The jada_blast.py script serves as the primary orchestration layer for campaign delivery. Rather than treating email sending as a monolithic operation, we architected it as a pipeline with distinct stages:

# Pseudo-structure of the refactored workflow
1. Load contact list from platform (CSV/JSON)
2. Query SES suppression list for bounced addresses
3. Filter contacts: remove bounced + apply rate limits
4. Build email batch with templated content
5. Send via SES with delivery tracking
6. Log metrics to dashboard
7. Update task cards with results

This approach isolates concerns: contact sourcing, compliance filtering, content rendering, delivery, and observability are each independently testable. The key decision here was filtering suppressed contacts before sending rather than handling bounces reactively. This prevents wasting SES quota on addresses we know will hard-bounce, which is crucial when operating at scale across multiple platforms.

The script also implements a staged rollout pattern. Rather than blast all contacts simultaneously, it supports cohort-based sending:

  • Stage 1: Verified/engaged contacts (highest deliverability confidence)
  • Stage 2: Warm leads from previous interactions
  • Stage 3: Cold outreach (widening the gap as confidence builds)

SES Suppression List Integration

Amazon SES maintains suppression lists for bounce complaints and unsubscribe requests. The implementation queries this data via the AWS CLI before campaign execution:

aws sesv2 get-suppressed-destination \
  --email-address user@example.com \
  --reason BOUNCE

# Returns suppression status and metadata

We export the full suppression list periodically and maintain a local cache at /Users/cb/Documents/repos/data/ses_suppressed_contacts.json. This cache is updated before each campaign run:

  • Reduces API calls (one bulk export vs. individual lookups per contact)
  • Enables offline analysis of suppression patterns (bounce rate trends, complaint categories)
  • Provides fallback data if SES API is temporarily unavailable

The filtering logic is strict: any contact appearing in the SES suppression list is excluded before batch construction. This is non-negotiable for maintaining sender reputation.

Multi-Platform Task Card System

Beyond email, the campaign strategy includes direct platform outreach. We created task cards for each non-live booking platform:

  • GetMyBoat: Platform-native messaging (task card: t-getmyboat-001)
  • WeddingWire: Review/messaging integration (task card: t-weddingwire-001)
  • Additional platforms as identified in dashboard research

Each task card contains:

  • Platform API documentation links
  • Authentication credential references (stored separately in repos.env, never in task bodies)
  • Contact list size and targeting parameters
  • Expected delivery timeline and success metrics

Why this structure? Centralizing platform metadata in task cards allows the jada_blast.py script to loop through platforms dynamically, pulling configuration without hardcoding provider-specific logic. This enables adding new platforms without modifying the core blast script.

Infrastructure and Credential Management

All platform credentials are stored in /Users/cb/Documents/repos/.env/repos.env with strict access controls. The blast script loads credentials at runtime:

# Within jada_blast.py (conceptual)
import os
from dotenv import load_dotenv

load_dotenv("/Users/cb/Documents/repos/.env/repos.env")
SES_REGION = os.getenv("AWS_REGION")
GETMYBOAT_API_KEY = os.getenv("GETMYBOAT_API_KEY")
# Never log or expose these values

SES itself is configured for the primary AWS account with:

  • Sending limits: Rate-limited to prevent reputation damage (24-hour send quota monitored)
  • Bounce handling: Automatic soft/hard bounce categorization
  • Complaint handling: User unsubscribe/complaint tracking
  • DKIM/SPF: Pre-configured for domain verification (domain details not included here for security)

Key Architectural Decisions

1. Suppression-First Filtering
We chose to filter against SES suppression lists before building email batches rather than catching bounces after sending. Rationale: Bouncing from suppressed addresses costs SES quota and harms sender reputation. The suppression list is the source of truth; respecting it prevents false positives.

2. Task Card-Driven Platform Configuration
Instead of a centralized platform registry, we use dashboard task cards as the single source of truth for which platforms are active and what credentials to use. This allows CB to enable/disable platforms without touching code—just update the task card status or notes.

3. Staged Cadence Rollout
The "widening-gap" strategy sends to high-confidence contacts first, then progressively expands. This de-risks the campaign: if early stages fail, we catch issues before burning all contact equity. It also allows monitoring deliverability metrics between stages.

4. Local Suppression Cache
Rather than live-querying SES for every contact, we cache the suppression list locally. This reduces latency, API calls, and external dependencies. Cache invalidation happens at script startup, ensuring data freshness without constant API overhead.

What's Next

The foundation is in place. Upcoming work includes:

  • Implementing per-platform delivery tracking and success metrics
  • Building dashboard visualizations for campaign performance (delivery rate, bounce analysis, engagement tracking)
  • Creating automated remediation: if bounce rate exceeds threshold, pause campaign and alert
  • Expanding platform coverage as new integration opportunities emerge
  • Monitoring SES quota usage and implementing auto-scaling for high-volume campaigns

The architecture is now flexible enough to support multiple platforms and delivery channels while maintaining strict compliance with email best practices and AWS SES guidelines.

```