Transactional Email Delivery
Relevant source files
The following files were used as context for generating this wiki page:
The Transactional Email Delivery system in Kocteau provides a minimal, dark-themed communication layer for user authentication and onboarding. Built using React Email and delivered via Resend (integrated through Supabase Auth), the system prioritizes a code-only approach for authentication to maintain a seamless security loop within the application UI.
Sources: apps/web/emails/README.md:1-10, README.md:110-120
Architecture and Data Flow
Kocteau utilizes a hybrid architecture where email templates are authored as React components but delivered through Supabase's authentication service. During local development, emails are intercepted by Inbucket, while production delivery is handled by Resend SMTP.
Email Delivery Lifecycle
The following diagram illustrates the path from a user action to the delivery of a transactional email:
The diagram shows how the system bifurcates based on environment and template requirements.
Sources: supabase/config.toml:104-124, README.md:151-158
Component-Based Template System
Transactional emails are built using a standardized "kit" to ensure visual consistency across all communications.
| Component | Purpose | File Path |
|---|---|---|
EmailShell | Standard dark-themed layout wrapper including logo and footer. | apps/web/emails/kocteau-email-kit.tsx:142 |
PrimaryButton | Restrained CTA button with specific padding and radius. | apps/web/emails/kocteau-email-kit.tsx:210 |
kocteauWelcomeEmail | Onboarding email for new users. | apps/web/emails/welcome-email.tsx |
supabase-otp-template | Minimal HTML version for Supabase Auth overrides. | apps/web/emails/README.md:14-20 |
Sources: apps/web/emails/kocteau-email-kit.tsx, apps/web/emails/welcome-email.tsx
Authentication Flow (OTP-First)
Kocteau uses an OTP-first authentication strategy. To prevent confusing loops, the system explicitly avoids Magic Links in favor of 6-digit codes that the user must manually enter within the application interface.
OTP Configuration
| Setting | Value | Description |
|---|---|---|
otp_length | 6 | Number of digits in the authentication code. |
otp_expiry | 3600 | Code expiration time in seconds (1 hour). |
max_frequency | 1s | Minimum delay between consecutive email sends. |
Sources: supabase/config.toml:235-245
Implementation Logic
For both Magic Link or OTP and Confirm Signup templates in the Supabase Dashboard, the platform uses a code-only format. Developers are instructed to use the placeholder {{ .Token }} and omit confirmation URL variables like {{ .ConfirmationURL }} to ensure the user stays within the app flow.
The sequence demonstrates the "loop" prevention by forcing code verification within the app.
Sources: README.md:213-222, apps/web/emails/README.md:20-30
Visual System and Branding
The email design follows a "minimal dark" aesthetic, aligning with the core product's cinematic and quiet tone.
- Color Palette: Background
#070707, Panel#0d0d0d, Primary Text#f7f4ee, and Muted Text#7d7d7d. - Typography: System UI stack for reliability; Monospace stack used exclusively for OTP codes.
- Logo: Production emails must use the PNG asset (
https://kocteau.com/logo-k.png) at42pxinstead of SVGs, as SVGs have inconsistent support in Gmail and Outlook. - Geometry: High-radius corners are used for the UI (e.g.,
24pxfor panels,18pxfor code blocks).
Sources: apps/web/emails/README.md:50-80, apps/web/emails/kocteau-email-kit.tsx:12-80
Configuration and Development
The system is configured to be local-first, allowing contributors to test email flows without production credentials.
Local Development Environment
In the local stack, emails are captured by an Inbucket server instead of being sent to real addresses.
- Preview Port:
3001(React Email) - Inbucket Port:
54324(Local Email UI)
# Preview templates locally
pnpm --filter web email:dev
# View captured OTPs
pnpm supabase:status
Sources: apps/web/emails/README.md:10-12, supabase/config.toml:104-110
Production SMTP (Resend)
In production, Supabase Auth is configured to use Resend SMTP. The configuration points to the specific HTML template for authentication flows.
[auth.email.template.magic_link]
subject = "Your Kocteau code"
content_path = "./supabase/templates/supabase-otp-template.html"
Sources: supabase/config.toml:254-260
Summary
Kocteau’s Transactional Email Delivery system is a purpose-built communication layer that facilitates an "OTP-first" authentication flow. By utilizing a shared component kit and code-only templates, the system ensures a consistent, secure, and minimal user experience that guides listeners back into the core product loop without the friction of external magic links.