Email correspondence

[ngoiyaeric]

When a user or agent is invited to the platform, chats should be able to correspond via email into the platform for Invitee. Similar to github functionality.

[ngoiyaeric]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Introduce Resend as the email service with a clean utility layer in lib/email/
• Extend the database with migrations for the existing chatParticipants schema and new email metadata columns on messages
• Build participant management as server actions following established patterns, updating chat queries to respect participant access
• Implement bidirectional email flow using unique reply-to addresses for routing and RFC 5322-compliant threading headers for proper email client display

Design Choices

Design Choice 1: Email Service Provider Selection

Options Considered:

1. Resend - Modern API, excellent Next.js integration, supports both sending and inbound webhooks
2. SendGrid - Mature platform, comprehensive features, more complex setup
3. Postmark - Strong deliverability focus, good inbound processing

Chosen Option: 1

Rationale: Resend offers the simplest integration path for Next.js applications with native TypeScript support and straightforward webhook handling for inbound emails.

Design Choice 2: Reply Routing Mechanism

Options Considered:

1. Unique reply-to addresses per chat (e.g., reply+{chatId}+{token}@replies.domain.com)
2. Parse In-Reply-To headers to match stored Message-ID values
3. Combination approach using both address routing and header validation

Chosen Option: 3

Rationale: Use unique reply-to addresses as the primary routing mechanism with header validation as secondary verification—this provides reliable routing while maintaining email threading standards and preventing spoofing.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Email Infrastructure & Schema Foundation

Establish the core email sending capability and extend the database schema to support email threading and participant tracking. This phase creates the foundation that all subsequent email features will build upon.

Task 1: Add Email Service Integration

Set up Resend as the email service provider with configuration and a reusable utility layer.

• Add resend package to dependencies
• Create lib/email/client.ts with initialized Resend client reading from environment variables
• Create lib/email/send.ts with typed wrapper functions for sending emails (accepting recipient, subject, body, optional headers)
• Add environment variables to .env.local.example: RESEND_API_KEY, EMAIL_FROM_ADDRESS, EMAIL_REPLY_DOMAIN

Task 2: Create Database Migration for Chat Participants

Generate and apply a Drizzle migration to create the chat_participants table that exists in schema but not in the database.

• Create new migration file in drizzle/migrations/ that creates the chat_participants table matching the schema definition
• Include the unique constraint on (chat_id, user_id) and foreign key cascade rules
• Update the Drizzle journal to track the new migration

Task 3: Extend Messages Schema for Email Metadata

Add columns to the messages table to support email threading and track email-originated messages.

• Add migration for new columns on messages: email_message_id (text, nullable), email_in_reply_to (text, nullable), email_source (boolean, default false)
• Update lib/db/schema.ts to include these new fields in the messages table definition
• Update lib/types/index.ts to extend the AIMessage type with optional email metadata fields

🤖 Prompt for AI agents

Set up the email infrastructure and extend the database schema to support email
threading and participant tracking. The goal is to establish the foundational
layer that all subsequent email features will depend on.

**Task 1: Add Email Service Integration**
- Install the `resend` npm package as a dependency
- Create `lib/email/client.ts` that initializes and exports a Resend client
instance, reading the API key from environment variables
- Create `lib/email/send.ts` with typed wrapper functions for sending emails;
the function signature should accept recipient, subject, body, and optional
headers
- Add the following environment variable placeholders to `.env.local.example`:
`RESEND_API_KEY`, `EMAIL_FROM_ADDRESS`, `EMAIL_REPLY_DOMAIN`

**Task 2: Create Database Migration for Chat Participants**
- Create a new migration file under `drizzle/migrations/` that generates the
`chat_participants` table to match the existing schema definition
- The migration must include the unique constraint on `(chat_id, user_id)` and
the appropriate foreign key cascade rules
- Update the Drizzle migration journal to register the new migration

**Task 3: Extend Messages Schema for Email Metadata**
- Create a new Drizzle migration that adds the following nullable columns to the
`messages` table:
  - `email_message_id` (text, nullable)
  - `email_in_reply_to` (text, nullable)
  - `email_source` (boolean, default `false`)
- Update `lib/db/schema.ts` to reflect these new fields in the messages table
definition
- Update `lib/types/index.ts` to extend the `AIMessage` type with these optional
email metadata fields

Phase 2: Participant Management & Invitation Flow

Build the server-side logic for managing chat participants and enhance the user invitation flow to send welcome emails. This establishes who receives notifications and how users are onboarded.

Task 1: Create Participant Management Server Actions

Implement server actions for adding, removing, and querying chat participants.

• Create lib/actions/participants.ts with server actions following the pattern in lib/actions/users.ts
• Implement addParticipant(chatId, userId, role?) - adds a user to a chat with duplicate checking via the unique constraint
• Implement removeParticipant(chatId, userId) - removes a participant with ownership validation
• Implement getParticipants(chatId) - returns all participants for a chat with their user details (email, role)
• Implement getChatsForParticipant(userId) - returns chats where user is a participant (for future chat list integration)

Task 2: Update Chat Access Queries

Modify chat retrieval logic to grant access based on participant membership, not just ownership.

• Update getChat in lib/actions/chat-db.ts to check chatParticipants table in addition to chats.userId ownership
• Update getChatsPage to optionally include chats where the user is a participant (via LEFT JOIN or UNION with chatParticipants)
• Ensure the chat owner is implicitly treated as a participant for notification purposes

Task 3: Enhance User Addition with Invitation Email

Extend the addUser flow to send a welcome/invitation email when a new user is added to the platform.

• Create email template function in lib/email/templates/ for the invitation email (simple text/HTML with platform name, inviter context if available)
• Modify addUser in lib/actions/users.ts to call the email sending utility after successful database insert
• Handle email sending failures gracefully—log the error but don't fail the user creation (the user record is still valuable)

🤖 Prompt for AI agents

Build participant management server actions and enhance the user invitation flow
to send welcome emails. The goal is to establish who receives notifications and
how users are onboarded into chats.

**Task 1: Create Participant Management Server Actions**
- Create `lib/actions/participants.ts` following the same patterns used in
`lib/actions/users.ts`
- Implement the following server actions:
- `addParticipant(chatId, userId, role?)`: adds a user to a chat; use the unique
constraint on `(chat_id, user_id)` to prevent duplicates
- `removeParticipant(chatId, userId)`: removes a participant; include ownership
validation before deletion
- `getParticipants(chatId)`: returns all participants for a chat including user
details such as email and role
- `getChatsForParticipant(userId)`: returns all chats where the user is a
participant (for future use)

**Task 2: Update Chat Access Queries**
- In `lib/actions/chat-db.ts`, update `getChat` to also check the
`chatParticipants` table in addition to `chats.userId` ownership when
determining access
- Update `getChatsPage` to include chats where the user is a participant using a
LEFT JOIN or UNION with the `chatParticipants` table
- Ensure the chat owner is implicitly considered a participant for notification
purposes

**Task 3: Enhance User Addition with Invitation Email**
- Create an invitation email template function under `lib/email/templates/` that
produces simple text/HTML content including the platform name and inviter
context if available
- In `lib/actions/users.ts`, modify `addUser` to call the email sending utility
after a successful database insert
- Handle email sending failures gracefully: log the error but do not fail the
user creation — the user record remains valid regardless of email delivery

Phase 3: Email Correspondence System

Implement the bidirectional email flow: outbound notifications when chat messages are created, and inbound processing to convert email replies into chat messages.

Task 1: Implement Outbound Email Notifications

Send email notifications to chat participants when new messages are posted, with proper threading headers.

• Create lib/email/notifications.ts with a notifyParticipants(chatId, message, excludeUserId) function
• Generate unique Message-ID values using format <msg-{messageId}@{domain}> and store in the message record
• Set In-Reply-To and References headers based on the previous message in the chat thread (query last message's email_message_id)
• Set the Reply-To address using format reply+{chatId}+{verificationToken}@{replyDomain} where token is derived from chatId + secret
• Call notifyParticipants from the message save flow in lib/actions/chat-db.ts after successful message insertion

Task 2: Create Inbound Email Webhook Endpoint

Build the API endpoint that receives email replies from Resend's inbound webhook.

• Create app/api/email/inbound/route.ts with POST handler for Resend webhook payload
• Parse the reply-to address to extract chatId and verification token
• Validate the token to prevent spoofed replies (recreate expected token from chatId + secret and compare)
• Look up the sender's email in the users table to get their userId; reject if sender not found or not a participant
• Extract the reply content from the email body (handle text and HTML, strip quoted content/signatures where feasible)

Task 3: Create Chat Messages from Email Replies

Process validated inbound emails and create corresponding chat messages.

• Extend the inbound webhook handler to call createMessage from lib/actions/chat-db.ts
• Set message fields: chatId from parsed address, userId from sender lookup, role as 'user', content as extracted reply text
• Set email metadata fields: email_source: true, email_message_id from inbound email's Message-ID, email_in_reply_to from inbound email's In-Reply-To header
• Trigger the outbound notification flow to notify other participants of the new message (excluding the sender)
• Return appropriate HTTP status codes: 200 for success, 400 for validation failures, 401 for unauthorized senders

Task 4: Wire Notifications into Chat Save Flow

Integrate the notification system with the existing chat persistence mechanism.

• Identify the onSetAIState callback in app/actions.tsx where chats are auto-saved after AI responses
• Add a call to notifyParticipants after the saveChat operation completes for assistant messages
• For user-submitted messages (via the submit action), ensure notifications are sent to other participants
• Ensure notifications are only sent for chats that have participants beyond the owner

🤖 Prompt for AI agents

Implement the full bidirectional email correspondence system: outbound
notifications when messages are created, and inbound webhook processing to
convert email replies into chat messages. The goal is a complete email loop
between the platform and participants.

**Task 1: Implement Outbound Email Notifications**
- Create `lib/email/notifications.ts` exporting a `notifyParticipants(chatId,
message, excludeUserId)` function
- For each notification, generate a unique `Message-ID` using the format
`<msg-{messageId}@{domain}>` and store it in the message record
- Set `In-Reply-To` and `References` email headers by querying the previous
message's `email_message_id` in the chat thread
- Set the `Reply-To` address using the format
`reply+{chatId}+{verificationToken}@{replyDomain}`, where the token is derived
from the chatId combined with a server secret
- After successful message insertion in `lib/actions/chat-db.ts`, call
`notifyParticipants`

**Task 2: Create Inbound Email Webhook Endpoint**
- Create `app/api/email/inbound/route.ts` with a POST handler to receive Resend
inbound webhook payloads
- Parse the inbound `Reply-To` address to extract `chatId` and the verification
token
- Validate the token by recreating the expected value from chatId + secret and
comparing; reject if mismatched
- Look up the sender's email in the `users` table to resolve their `userId`;
reject the request if the sender is not found or is not a chat participant
- Extract reply content from the email body, handling both text and HTML formats
and stripping quoted content/signatures where feasible

**Task 3: Create Chat Messages from Email Replies**
- Within the inbound webhook handler, call `createMessage` from
`lib/actions/chat-db.ts` with the following fields:
  - `chatId`: parsed from the reply-to address
  - `userId`: resolved from sender lookup
  - `role`: `'user'`
  - `content`: extracted reply text
  - `email_source: true`
  - `email_message_id`: from the inbound email's Message-ID header
  - `email_in_reply_to`: from the inbound email's In-Reply-To header
- After creating the message, trigger `notifyParticipants` to notify other
participants, excluding the sender
- Return HTTP status codes: `200` for success, `400` for validation failures,
`401` for unauthorized senders

**Task 4: Wire Notifications into Chat Save Flow**
- In `app/actions.tsx`, locate the `onSetAIState` callback where chats are
auto-saved after AI responses
- After the `saveChat` operation completes for assistant messages, add a call to
`notifyParticipants`
- For user-submitted messages via the `submit` action, also ensure
`notifyParticipants` is called for other participants
- Add a guard to only trigger notifications when the chat has participants
beyond the owner

Research

Codebase Summary

This is a Next.js application using Supabase for authentication and PostgreSQL (via Drizzle ORM) for data persistence. The codebase has a chat system with chats, messages, and a defined but unused chatParticipants table. User management exists via admin-only server actions, but there is no invitation system—users are added directly to the database without notification. Critically, there is zero email infrastructure: no email service, no SMTP configuration, and no notification mechanisms of any kind. The email correspondence feature requires building email sending/receiving capabilities from scratch while leveraging the existing chat and user management patterns.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up the email infrastructure and extend the database schema to support email
threading and participant tracking. The goal is to establish the foundational
layer that all subsequent email features will depend on.

**Task 1: Add Email Service Integration**
- Install the `resend` npm package as a dependency
- Create `lib/email/client.ts` that initializes and exports a Resend client
instance, reading the API key from environment variables
- Create `lib/email/send.ts` with typed wrapper functions for sending emails;
the function signature should accept recipient, subject, body, and optional
headers
- Add the following environment variable placeholders to `.env.local.example`:
`RESEND_API_KEY`, `EMAIL_FROM_ADDRESS`, `EMAIL_REPLY_DOMAIN`

**Task 2: Create Database Migration for Chat Participants**
- Create a new migration file under `drizzle/migrations/` that generates the
`chat_participants` table to match the existing schema definition
- The migration must include the unique constraint on `(chat_id, user_id)` and
the appropriate foreign key cascade rules
- Update the Drizzle migration journal to register the new migration

**Task 3: Extend Messages Schema for Email Metadata**
- Create a new Drizzle migration that adds the following nullable columns to the
`messages` table:
  - `email_message_id` (text, nullable)
  - `email_in_reply_to` (text, nullable)
  - `email_source` (boolean, default `false`)
- Update `lib/db/schema.ts` to reflect these new fields in the messages table
definition
- Update `lib/types/index.ts` to extend the `AIMessage` type with these optional
email metadata fields
===============================================================================

Task: 2

Build participant management server actions and enhance the user invitation flow
to send welcome emails. The goal is to establish who receives notifications and
how users are onboarded into chats.

**Task 1: Create Participant Management Server Actions**
- Create `lib/actions/participants.ts` following the same patterns used in
`lib/actions/users.ts`
- Implement the following server actions:
- `addParticipant(chatId, userId, role?)`: adds a user to a chat; use the unique
constraint on `(chat_id, user_id)` to prevent duplicates
- `removeParticipant(chatId, userId)`: removes a participant; include ownership
validation before deletion
- `getParticipants(chatId)`: returns all participants for a chat including user
details such as email and role
- `getChatsForParticipant(userId)`: returns all chats where the user is a
participant (for future use)

**Task 2: Update Chat Access Queries**
- In `lib/actions/chat-db.ts`, update `getChat` to also check the
`chatParticipants` table in addition to `chats.userId` ownership when
determining access
- Update `getChatsPage` to include chats where the user is a participant using a
LEFT JOIN or UNION with the `chatParticipants` table
- Ensure the chat owner is implicitly considered a participant for notification
purposes

**Task 3: Enhance User Addition with Invitation Email**
- Create an invitation email template function under `lib/email/templates/` that
produces simple text/HTML content including the platform name and inviter
context if available
- In `lib/actions/users.ts`, modify `addUser` to call the email sending utility
after a successful database insert
- Handle email sending failures gracefully: log the error but do not fail the
user creation — the user record remains valid regardless of email delivery
===============================================================================

Task: 3

Implement the full bidirectional email correspondence system: outbound
notifications when messages are created, and inbound webhook processing to
convert email replies into chat messages. The goal is a complete email loop
between the platform and participants.

**Task 1: Implement Outbound Email Notifications**
- Create `lib/email/notifications.ts` exporting a `notifyParticipants(chatId,
message, excludeUserId)` function
- For each notification, generate a unique `Message-ID` using the format
`<msg-{messageId}@{domain}>` and store it in the message record
- Set `In-Reply-To` and `References` email headers by querying the previous
message's `email_message_id` in the chat thread
- Set the `Reply-To` address using the format
`reply+{chatId}+{verificationToken}@{replyDomain}`, where the token is derived
from the chatId combined with a server secret
- After successful message insertion in `lib/actions/chat-db.ts`, call
`notifyParticipants`

**Task 2: Create Inbound Email Webhook Endpoint**
- Create `app/api/email/inbound/route.ts` with a POST handler to receive Resend
inbound webhook payloads
- Parse the inbound `Reply-To` address to extract `chatId` and the verification
token
- Validate the token by recreating the expected value from chatId + secret and
comparing; reject if mismatched
- Look up the sender's email in the `users` table to resolve their `userId`;
reject the request if the sender is not found or is not a chat participant
- Extract reply content from the email body, handling both text and HTML formats
and stripping quoted content/signatures where feasible

**Task 3: Create Chat Messages from Email Replies**
- Within the inbound webhook handler, call `createMessage` from
`lib/actions/chat-db.ts` with the following fields:
  - `chatId`: parsed from the reply-to address
  - `userId`: resolved from sender lookup
  - `role`: `'user'`
  - `content`: extracted reply text
  - `email_source: true`
  - `email_message_id`: from the inbound email's Message-ID header
  - `email_in_reply_to`: from the inbound email's In-Reply-To header
- After creating the message, trigger `notifyParticipants` to notify other
participants, excluding the sender
- Return HTTP status codes: `200` for success, `400` for validation failures,
`401` for unauthorized senders

**Task 4: Wire Notifications into Chat Save Flow**
- In `app/actions.tsx`, locate the `onSetAIState` callback where chats are
auto-saved after AI responses
- After the `saveChat` operation completes for assistant messages, add a call to
`notifyParticipants`
- For user-submitted messages via the `submit` action, also ensure
`notifyParticipants` is called for other participants
- Add a guard to only trigger notifications when the chat has participants
beyond the owner

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!