Workspace Management

Relevant source files

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

• src/app/api/workspaces/route.ts
• src/app/api/workspaces/settings/route.ts
• src/lib/db.ts
• src/app/app/page.tsx
• src/lib/openapi.ts
• src/lib/auth.ts

Workspace Management is the core organizational system within the Send Again platform, allowing users to isolate email campaigns, contacts, and configurations by domain. Each workspace is identified by a unique domain name (e.g., example.com) and serves as a boundary for security, deliverability settings, and billing.

The system facilitates multi-tenancy by linking users to specific workspaces through a membership model. It manages critical infrastructure settings, including Amazon SES configuration, DNS automation for deliverability (SPF, DKIM, DMARC), and credit-based usage tracking.

Sources: src/app/api/workspaces/route.ts:47-60, src/lib/db.ts:400-420, README.md:9-15

Data Model and Relationships

Workspaces are primarily defined by their id, which must follow a domain name format. The relationship between users and workspaces is managed via the workspace_memberships table, which supports roles like "owner" and "member".

Core Entities

Entity	Description	Source
Workspace	The top-level container defined by a domain ID.	src/lib/openapi.ts:74-88
Workspace Settings	Metadata including sender addresses, rate limits, and footers.	src/lib/db.ts:601-615
Membership	Links a user_id to a workspace_id with a specific role.	src/lib/db.ts:391-404
Billing Status	Tracks credit balance and subscription state per workspace.	src/lib/db.ts:696-715

Entity Relationship Diagram

The following diagram illustrates the relationships between users, workspaces, and their associated configurations.

Workspace Lifecycle

Creation and Bootstrap

When a user first authenticates, the system can preserve existing workspace data by claiming current SES domains for the bootstrap owner if the email matches the INITIAL_OWNER_EMAIL. New workspaces are created by providing a valid domain ID, which triggers an entry in the memberships table with an "owner" role.

Deletion and Data Scrubbing

Workspace deletion is a restricted operation available only to users with the "owner" role. Deletion performs a cascading cleanup across multiple tables to ensure data isolation is maintained.

Key tables scrubbed during deletion:

• sends and linked email_events
• send_jobs and send_job_recipients
• contacts and contact_unsubscribes
• api_keys
• workspace_billing and workspace_settings

Sources: src/app/api/workspaces/route.ts:98-120, src/lib/db.ts:482-550

Configuration and Settings

Workspace settings control the behavior of the email engine and the appearance of outgoing messages. These settings are managed via PUT /api/workspaces/settings.

Settings Schema

Field	Type	Description
from_address	String	The default email address used for sends (must match domain).
from_name	String	Optional display name for the sender.
rate_limit	Integer	Delay in milliseconds between individual sends (Default: 300ms).
footer_html	String	HTML appended to every email, supporting {{unsubscribe_url}}.
contact_source	Object	Provider and config for automated contact syncing (e.g., http_json).

Sources: src/app/api/workspaces/settings/route.ts:51-85, src/lib/db.ts:620-644

Deliverability Setup

Workspaces include an automated setup process for domain verification and DNS configuration. The system supports three DNS providers for automatic record insertion:

1. Namecheap: Uses API User and Whitelisted IP.
2. Cloudflare: Uses API Token and Zone ID.
3. Route 53: Uses AWS Hosted Zone ID.

The setup verifies 6 key components: Verification Token, SPF, DKIM, DMARC, Configuration Set existence, and the Unsubscribe page reachability.

Sources: src/app/app/page.tsx:850-980, src/app/app/page.tsx:1420-1550

Security and Access Control

Access to workspace data is governed by the requireWorkspaceAuth utility. It supports two authentication methods:

• Supabase JWT: Validates the user's session and checks their membership in the requested workspace.
• API Keys: Validates a hashed key (sk_...) and resolves the workspace ID directly from the key metadata, ignoring manual workspace filters.

API Key Scoping

Workspaces can issue multiple API keys, each restricted to specific scopes:

• contacts.read / contacts.write
• send.read / send.write

Sources: src/lib/auth.ts:85-115, src/lib/openapi.ts:25-45, src/lib/db.ts:135-150

Billing and Usage

Each workspace has an independent billing profile managed through workspace_billing.

Usage is tracked in real-time. When a send job is processed, the system calls consume_workspace_credits via a database RPC to decrement the credit_balance and increment lifetime_credits_consumed.

Sources: src/lib/db.ts:805-830, src/lib/db.ts:835-858

Summary

Workspace Management in Send Again provides a robust multi-tenant architecture. By isolating settings, billing, and deliverability configurations per domain, the system ensures that users can manage multiple distinct sending identities from a single account while maintaining strict data separation and infrastructure compliance.