REST API Overview & Docs

Relevant source files

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

• src/lib/openapi.ts
• src/app/app/page.tsx
• README.md
• src/app/api/vibe/route.ts
• src/app/api/keys/route.ts
• src/app/api/workspaces/settings/route.ts
• src/app/api/unsubscribe/route.ts

The Send Again REST API provides programmatic access to email sending, contact management, and workspace configuration. It is designed for developers and AI agents to integrate email infrastructure directly into their applications. The API supports core functionalities including managing contacts (CRUD operations), enqueuing email send jobs with support for dry runs, and querying delivery history and analytics.

The API is primarily accessible via the /api prefix, and a full OpenAPI 3.1.0 specification is available at /api/openapi.json. Interactive developer documentation is typically served at the /docs route. Sources: README.md:95-99, src/lib/openapi.ts:1-10

Authentication Mechanisms

Send Again utilizes two primary authentication methods to secure API endpoints: Supabase JWT tokens and scoped API Keys.

Authentication Types

Scheme	Type	Header Format	Scope/Description
JWT	HTTP Bearer	Authorization: Bearer <token>	Supabase JWT. Works on all endpoints.
API Key	HTTP Bearer	Authorization: Bearer sk_...	Scoped keys for specific operations like sending and contacts.

Sources: src/lib/openapi.ts:12-25, README.md:104-107

API Key Scoping

API keys (starting with sk_) can be restricted to specific permissions to adhere to the principle of least privilege. If scopes are omitted during key creation, the key defaults to full access for backward compatibility. Sources: src/lib/openapi.ts:19-24, src/app/api/keys/route.ts:31-45

The following scopes are available:

• contacts.read: View contact lists and individual contact details.
• contacts.write: Create, update, or delete contacts.
• send.read: View send jobs and status.
• send.write: Initiate new email sends.

Sources: src/lib/openapi.ts:47-52, src/app/app/page.tsx:141-146

Core API Modules

Contact Management

The Contacts API allows for individual or batch operations on recipient data within a workspace. It supports "upsert" logic where providing an existing email updates the associated metadata fields.

The workspace filter is mandatory for JWT authentication but is automatically resolved when using an API Key. Sources: src/lib/openapi.ts:162-180, src/lib/openapi.ts:21-25

Email Sending & Jobs

Sending emails through /api/send triggers the creation of a SendJob. This job is processed asynchronously to handle rate limits and large recipient lists.

Parameter	Type	Required	Description
workspaceId	string	Yes	Target workspace for the send.
subject	string	Yes	Email subject line.
html	string	Yes	Email body in HTML format.
recipientMode	enum	No	manual, all_contacts, verified_contacts, etc.
dryRun	boolean	No	If true, returns recipient count without sending. Defaults to false.

Sources: src/lib/openapi.ts:312-340, src/app/app/page.tsx:162-185

Job Lifecycle and Status

The API allows tracking the progress of a send through the /api/send/status endpoint.

Analytics and History

The API provides endpoints to retrieve historical send data and aggregated performance metrics.

• /api/history: Returns paginated entries of sent messages, including SES event types like Delivery, Open, Click, Bounce, and Complaint.
• /api/history/analytics: Provides delivery rate and engagement analytics filtered by topic (subject line) or workspace.

Sources: src/lib/openapi.ts:446-485, src/app/app/page.tsx:1120-1160

AI-Powered "Vibe" Generation

Send Again includes an internal API for generating or revising email content using OpenAI.

• Endpoint: POST /api/vibe
• Target: Can target either email (body content) or footer.
• Logic: It accepts an instruction (prompt) and the currentHtml to perform iterative improvements.
• Requirement: Requires OPENAI_API_KEY to be configured in the environment.

Sources: src/app/api/vibe/route.ts:85-115, src/app/app/page.tsx:1350-1375

Workspace Configuration

Workspaces represent distinct sending identities (usually tied to a domain). The API manages their settings including default sender details and custom footers.

Field	Description
from	Default sender email address (must match domain).
fromName	Optional display name for the sender.
rateLimit	Interval (ms) between individual email sends.
footerHtml	HTML content appended to every sent email.
websiteUrl	Primary URL for the workspace, used in unsubscribe links.

Sources: src/lib/openapi.ts:79-93, src/app/api/workspaces/settings/route.ts:50-85

Summary of Endpoint Access

Method	Path	Auth	Description
GET	/api/workspaces	JWT	List authorized workspaces.
PUT	/api/workspaces/settings	JWT	Update workspace configuration.
POST	/api/send	JWT/Key	Enqueue a send job.
GET	/api/send/status	JWT/Key	Check job progress.
POST	/api/contacts	JWT/Key	Batch import/update contacts.
GET	/api/history	JWT	Fetch detailed send logs.
POST	/api/keys	JWT	Create a new scoped API Key.

Sources: src/lib/openapi.ts:162-460, README.md:100-115