Sending API
Relevant source files
The following files were used as context for generating this wiki page:
The Sending API is the core programmatic interface of the Send Again platform, designed to facilitate email dispatch, job tracking, and campaign management via a RESTful architecture. It allows developers and automated systems to enqueue email jobs, target specific contact segments, and monitor delivery progress in real-time.
Powered by Amazon SES, the API handles the complexities of recipient resolution, unsubscribe suppression, and rate limiting. It integrates closely with the workspace management system to ensure high deliverability through automated DNS configurations and per-domain sender identities.
Sources: README.md:5-15, src/lib/openapi.ts:250-260
API Authentication
The Sending API supports two primary methods of authentication. Security is scoped to ensure that API keys can be limited to specific actions, such as reading or writing send data.
- Supabase JWT: A standard Bearer token used for authenticated web sessions, granting access to all endpoints.
- API Keys: Scoped tokens (prefixed with
sk_) specifically for programmatic access. Keys can be limited tosend.readandsend.writescopes. When using an API key, theworkspaceIdis resolved from the key itself, ignoring manual workspace filters in the query.
Sources: src/lib/openapi.ts:15-30, src/app/api/send/route.ts:135-145
Email Dispatch Process
Sending an email involves several stages, from request validation to asynchronous background processing. The API primarily functions by creating "Send Jobs" rather than sending emails synchronously.
1. Request Validation and Recipient Resolution
When a POST request is sent to /api/send, the system validates the sender's domain against the workspace ID. It then resolves the final recipient list based on the provided recipientMode.
The system ensures that no emails are sent to addresses found in the workspace's unsubscribe set.
Sources: src/app/api/send/route.ts:153-220, src/app/api/unsubscribe/route.ts:90-110
2. Job Creation and Asynchronous Processing
Once recipients are resolved, a SendJob is created. If the request is not a dryRun, the system uses a background processing pattern (via after() in Next.js) to iterate through the job queue.
| Data Structure Field | Type | Description |
|---|---|---|
jobId | UUID | Unique identifier for the created send job. |
status | Enum | Current state: queued, running, completed, failed, or cancelled. |
total | Integer | Total number of recipients after suppression filters. |
rateLimit | Integer | Milliseconds to wait between individual SES sends. |
dryRun | Boolean | If true, calculates recipients without actual dispatch. |
Sources: src/lib/openapi.ts:77-92, src/app/api/send/route.ts:285-320
Endpoint Reference
POST /api/send
Initiates a new email dispatch or performs a recipient count calculation (dry run).
Request Body Parameters:
workspaceId(string): Target domain.from(string): Sender email (must match workspace domain).recipientMode(string):manual,all_contacts,verified_contacts, orunverified_contacts.html(string): The email body.dryRun(boolean): Defaultfalse.
Sources: src/lib/openapi.ts:250-280, src/app/api/send/route.ts:25-50
GET /api/send/status
Retrieves the real-time progress of a specific job, including success and failure counts.
Configuration and Rate Limiting
The API behavior is influenced by workspace settings and environment variables that control the throughput to Amazon SES.
- Batch Size: Controlled by
SEND_JOB_BATCH_SIZE, determining recipients per processing loop (default 50). - Concurrency: Controlled by
SEND_JOB_CONCURRENCY, determining parallel sends (default 4). - Configuration Set: Automatically resolved via
getSesConfigurationSetName()to ensure tracking of opens, clicks, and bounces via AWS SNS.
Sources: README.md:165-180, src/app/api/send/route.ts:335-345, src/app/api/workspaces/settings/route.ts:80-95
Unsubscribe Handling
The Sending API enforces a strict suppression policy. Every dispatch checks the recipients against the unsubscribed_emails table for the specific workspace. Unsubscribe links are generated using a signed token to verify the recipient's identity without requiring a login.
Sources: src/app/api/unsubscribe/route.ts:135-150, src/app/api/send/route.ts:210-215
Programmatic interaction with the Sending API ensures high-volume capability while maintaining deliverability standards through automated status monitoring and strict adherence to suppression lists.