Email Sending Engine (SES)

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/ses.ts
• src/app/api/send/route.ts
• src/app/api/workspaces/setup/route.ts
• src/app/app/page.tsx
• src/lib/openapi.ts
• README.md

The Email Sending Engine is the core infrastructure component of the Send Again platform, responsible for interfacing with Amazon Simple Email Service (SES). It manages domain verification, DKIM configuration, configuration sets for tracking, and the actual assembly and transmission of raw MIME messages. The engine ensures high deliverability by enforcing domain-specific sending rules and handling various AWS-specific setup requirements.

Sources: src/lib/ses.ts, README.md:1-10

Core Architecture and Data Flow

The engine acts as a bridge between the application's internal send job processor and the AWS SES API. When a send request is initiated, the engine validates the sender's identity, resolves recipients based on defined modes (e.g., all contacts, verified only), and constructs a raw email message including both HTML and plain-text versions.

The diagram above illustrates the high-level flow from an API request to the final transmission through AWS SES and subsequent event tracking via SNS.
Sources: src/app/api/send/route.ts:121-255, src/lib/ses.ts:169-204

Domain Verification and Setup

The platform automates the verification of domains and DKIM (DomainKeys Identified Mail) to ensure that emails sent are not marked as spam. Verification is handled through specific SDK commands that generate required DNS records.

Verification Components

• Identity Management: Uses ListIdentitiesCommand and GetIdentityVerificationAttributesCommand to track the status of domains.
• DKIM Tokens: Uses VerifyDomainDkimCommand to generate three CNAME tokens required for DNS setup.
• Configuration Sets: Automatically checks for or creates configuration sets used for event tracking (bounces, complaints, opens, clicks).

Command / Function	Purpose	Data Returned
verifyDomain	Initiates domain identity verification	Verification Token (TXT)
setupDkim	Generates DKIM tokens for a domain	Array of 3 DKIM Tokens
getDomainSetupStatus	Aggregates verification and DKIM status	DomainSetupStatus object
createConfigurationSet	Creates a tracking group in SES	Void

Sources: src/lib/ses.ts:1-105, src/app/api/workspaces/setup/route.ts:133-165

Email Construction and Transmission

The engine does not use simple text fields for sending; instead, it builds a SendRawEmailCommand. This allows the platform to support complex features like multi-part MIME boundaries, UTF-8 subject encoding, and "One-Click" unsubscribe headers.

Message Assembly Logic

1. Format Source: Normalizes the "From" address, escaping quotes and including the display name (e.g., "Sender Name" <sender@domain.com>).
2. HTML to Plain Text: Automatically converts HTML content to a readable plain-text fallback using regex to preserve links and basic formatting.
3. MIME Boundary: Generates a unique boundary string for multipart/alternative content.
4. Headers: Includes standard headers (To, Subject, MIME-Version) and optional List-Unsubscribe headers.

API Endpoint: /api/send

The primary endpoint for initiating email sends supports multiple recipient resolution modes.

Parameter	Type	Description
workspaceId	String	Must match the authenticated workspace.
recipientMode	Enum	manual, all_contacts, verified_contacts, unverified_contacts.
dryRun	Boolean	If true, returns recipient count without actual transmission.
to	Array	Required if mode is manual.
html	String	The email body. Workspace footers are appended automatically.

Sources: src/app/api/send/route.ts:18-50, src/lib/openapi.ts:316-350

Configuration and Environment

The engine relies on specific AWS environment variables for authentication and regional targeting. It defaults to eu-west-3 if no region is specified.

const ses = new SESClient({
  region: process.env.AWS_REGION ?? "eu-west-3",
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

Sources: src/lib/ses.ts:14-22, README.md:65-70

Conclusion

The Email Sending Engine (SES) provides a robust abstraction over the AWS SES SDK, handling the complexities of raw MIME message construction and domain verification. By integrating directly with the workspace management system and the job processor, it enables scalable, compliant email campaigns while maintaining high deliverability standards through automated DNS and DKIM setup.