Build your own Help Scout.

# Build a shared support inbox (replacing Help Scout)

You are building a shared email inbox for a support address like support@yourcompany.com, used by a team of 2 to 10 people. It replaces Help Scout for teams that only use the inbox, saved replies, notes, tags, customer history, a small help center, and a basic report. Build it end to end. Correct email threading matters more than anything else: if a customer's reply lands in the wrong conversation, nothing else counts.

## Stack

- Next.js (App Router) with TypeScript, Tailwind
- Postgres via Supabase or Neon, with Drizzle or Prisma
- Auth: magic-link email plus Google sign-in (Supabase Auth, Clerk, or NextAuth, whichever is simplest)
- Inbound email: Resend inbound, Postmark inbound, or a Cloudflare Email Worker, posting parsed JSON to `POST /api/inbound`
- Outbound email: Resend or Postmark, using the custom-headers option so you can set `Message-ID`, `In-Reply-To`, and `References`
- `mailparser` (or the provider's parsed payload) for MIME, `sanitize-html` for rendering HTML bodies, `marked` for markdown
- `date-fns` and `date-fns-tz` for every date calculation. Never do timezone math by hand.
- Realtime: Supabase Realtime or a 10-second poll for presence and new messages. Polling is fine to start.
- Deploy target: Vercel, with Vercel Cron for the daily report digest

If a different stack is already set up in this repo, use it and keep the behavior identical.

## Environment variables

- `DATABASE_URL`
- `AUTH_SECRET` plus whatever the auth provider needs
- `INBOUND_PROVIDER` (`resend` | `postmark` | `cloudflare`) and `INBOUND_WEBHOOK_SECRET`
- `OUTBOUND_PROVIDER` (`resend` | `postmark`), `RESEND_API_KEY` or `POSTMARK_SERVER_TOKEN`
- `STORAGE_BUCKET` and the storage credentials
- `CRON_SECRET` for the report digest
- `OPENROUTER_API_KEY` (optional)

## Data model

Every table has `id` (uuid), `created_at`, `updated_at`.

- `mailboxes`: `name`, `address` (e.g. `support@yourcompany.com`, unique), `display_name` (e.g. `Acme Support`), `timezone` (IANA, e.g. `America/New_York`), `reply_domain` (e.g. `yourcompany.com`), `signature_markdown`.
  One mailbox is enough. Keep `mailbox_id` on everything so a second one can be added later.
- `users`: `email` (unique), `name`, `avatar_url`, `role` (`admin` | `agent`), `signature_markdown` (nullable).
- `mailbox_members`: `mailbox_id`, `user_id`. Primary key on both.
- `customers`: `mailbox_id`, `email` (unique per mailbox, lowercased), `name` (nullable), `company` (nullable), `notes` (text), `custom` (jsonb), `conversation_count` (int, maintained by the app).
- `conversations`: `mailbox_id`, `number` (int, sequence per mailbox, unique with `mailbox_id`), `subject`, `customer_id`, `assignee_id` (nullable FK users), `status` (`active` | `pending` | `closed` | `spam`), `reply_token` (16 random bytes, base32, unique), `last_customer_message_at`, `last_agent_message_at` (nullable), `first_response_at` (nullable), `closed_at` (nullable), `message_count` (int).
- `messages`: `conversation_id`, `kind` (`inbound` | `outbound` | `note`), `author_user_id` (nullable, set for outbound and note), `from_email`, `from_name`, `to_emails` (text[]), `cc_emails` (text[]), `message_id` (text, unique, nullable for notes), `in_reply_to` (nullable), `references` (text[]), `subject`, `text_body`, `html_body` (nullable), `quoted_text` (nullable), `raw_headers` (jsonb), `sent_at` (timestamptz), `delivery_status` (`queued` | `sent` | `failed`, outbound only), `delivery_error` (nullable), `provider_message_id` (nullable).
  Index on `message_id`. Full text index on `text_body`.
- `attachments`: `message_id`, `filename`, `content_type`, `size_bytes`, `storage_key`.
- `tags`: `mailbox_id`, `name` (unique per mailbox, lowercase), `color`.
- `conversation_tags`: `conversation_id`, `tag_id`. Primary key on both.
- `saved_replies`: `mailbox_id`, `name`, `body_markdown`, `created_by`, `use_count` (int).
- `conversation_events`: `conversation_id`, `actor_user_id` (nullable), `type` (`status_changed` | `assigned` | `tagged` | `untagged` | `reopened_by_customer` | `merged`), `data` (jsonb).
  Rendered inline in the thread as small gray lines.
- `presence`: `conversation_id`, `user_id`, `state` (`viewing` | `replying`), `seen_at`. Primary key on (`conversation_id`, `user_id`).
- `collections`: `mailbox_id`, `slug`, `name`, `position`.
- `articles`: `collection_id`, `slug` (unique per collection), `title`, `body_markdown`, `published` (bool), `search_vector` (tsvector generated from title and body, GIN index), `view_count`.

Seed: one mailbox, two users (one admin), tags `billing`, `bug`, `question`, `refund`, three saved replies, one collection with three articles, and 30 conversations across the last 14 days with a mix of statuses, assignees, and reply counts.

## Screens

Left sidebar: Inbox, Customers, Help Center, Reports, Settings. Top bar has a search box that searches conversation subject, message body, and customer email.

### 1. Sign in

- Magic link or Google.
- The first user becomes admin and creates the mailbox (name, address, timezone).
- Admins invite by email. Invited users land in the inbox on first sign-in.

### 2. Inbox (`/inbox`)

- Folders on the left: Unassigned, Mine, All Active, Pending, Closed, Spam, plus one entry per tag with a count.
- Each row shows customer name, subject, a one-line preview of the latest message, assignee avatar, tags, and the relative time of the last message.
- Default sort for Active is oldest `last_customer_message_at` first, so the customer who has waited longest is at the top. Closed sorts newest first.
- Bulk select with checkboxes for assign, tag, and close.
- Keyboard: j/k to move, enter to open, e to close, a to assign to me, s to mark pending.
- Paginate at 50. Server components for the initial render.

### 3. Conversation (`/inbox/[number]`)

- Header: subject, `#number`, status dropdown, assignee dropdown, tag picker.
- Thread: messages oldest first. Inbound on the left, outbound on the right, notes with a yellow background and a lock icon. Events as gray one-liners between messages.
- Each message shows sender, time in the mailbox timezone, and a "Show quoted text" toggle when `quoted_text` is set.
- Attachments listed under the message with filename and size, downloadable through a signed URL.
- Right column: the customer card (name, email, company, notes, editable inline) and a "Previous conversations" list with status and date.
- Presence banner above the composer (see Collision detection).

### 4. Reply composer

- Lives at the bottom of the conversation. Tabs for Reply and Note.
- Toolbar: Insert saved reply (searchable dropdown), attach file, and a send button with a split menu: "Send and close" (default), "Send and keep active", "Send and mark pending".
- Cmd+Enter sends. Esc clears focus.
- Draft auto-saves to localStorage every 2 seconds keyed by conversation id and restores on reload.
- Optional "Draft reply" and "Summarize" buttons when `OPENROUTER_API_KEY` is set.

### 5. Customers (`/customers`, `/customers/[id]`)

- Table with search by name, email, or company. Columns: name, email, company, conversation count, last contact.
- Detail page: editable profile on the left, every conversation for that customer on the right, newest first, with status and assignee.
- Admins can merge two customers (moves conversations, keeps the older record, writes a `merged` event on each moved conversation).

### 6. Help Center admin (`/help-center`)

- Collections list with drag-to-reorder. Articles per collection.
- Article editor: title, slug (auto from title, editable), collection, markdown body with a live preview, published toggle.
- "View public page" link. Unpublished articles show a preview link that only works when signed in.

### 7. Public help center (`/help`, `/help/[collection]`, `/help/[collection]/[slug]`)

- No auth. Home lists collections with article counts.
- Search box hits `GET /api/help/search?q=` and shows the top 10 results with a highlighted snippet.
- Article page renders sanitized markdown with a table of contents from headings, a "Last updated" date, and a "Still stuck? Email us" mailto link to the mailbox address.
- Only `published = true` articles are reachable. Unpublished slugs return 404.

### 8. Reports (`/reports`)

- Date range picker, default last 30 days.
- A table with one row per day and a totals row. Below it, a per-agent table for the range.
- CSV export of both tables.

### 9. Settings (`/settings`)

- Mailbox: name, display name, timezone (searchable IANA list), signature.
- Members and pending invites. Admins can change roles and remove members.
- Tags: rename, recolor, merge into another tag.
- Saved replies: list, create, edit, delete, with a variables cheat sheet.
- Inbound: the webhook URL and secret with a copy button and a "Send test email" instruction.
- Export: conversations, messages, and customers as CSV.

## API endpoints

- `POST /api/inbound` (webhook, signature verified)
- `GET /api/conversations?folder=&tag=&q=&page=`
- `GET /api/conversations/:id`
- `PATCH /api/conversations/:id` (status, assignee, tags)
- `POST /api/conversations/:id/reply`
- `POST /api/conversations/:id/note`
- `POST /api/messages/:id/retry`
- `POST /api/conversations/:id/presence`, `DELETE` same path
- `GET /api/conversations/:id/presence`
- `GET /api/search?q=`
- `GET /api/customers/:id`, `PATCH /api/customers/:id`, `POST /api/customers/:id/merge`
- `GET /api/help/search?q=` (public)
- `GET /api/reports/daily?from=&to=`
- `GET /api/cron/report-digest` (protected by `CRON_SECRET`)
- `POST /api/ai/draft`, `POST /api/ai/summarize` (optional)

Every authenticated route checks that the user is a member of the mailbox that owns the record. Return 404 for records in other mailboxes.

## Behaviors

### Inbound email (`POST /api/inbound`)

1. Verify the provider's signature. Resend and Postmark sign webhooks. For Cloudflare use a shared secret header. Return 401 on failure.
2. Parse into: `message_id`, `in_reply_to`, `references[]`, `from` (email, name), `to[]`, `cc[]`, `subject`, `text`, `html`, `date`, `headers`, `attachments[]`. If the provider gives you raw MIME, run it through `mailparser`.
3. If `message_id` already exists in `messages`, return 200 and do nothing. Providers retry, and customers forward.
4. Drop and return 200 (log it) when any of these is true:
   - `Auto-Submitted` header is present and not `no`
   - `Precedence` is `bulk`, `junk`, or `auto_reply`
   - `X-Autoreply` or `X-Autorespond` is present
   - the from address starts with `mailer-daemon@`, `postmaster@`, `noreply@`, or `no-reply@`
   - the from address equals the mailbox address (your own sent mail looping back)
5. Find the conversation, in this order:
   - Any message whose `message_id` equals `in_reply_to` or any entry in `references`.
   - A `reply_token` in any `to` or `cc` address of the form `support+<token>@<reply_domain>`.
   - A conversation from the same customer whose normalized subject matches and whose `last_customer_message_at` or `last_agent_message_at` is within the last 30 days. Normalize by repeatedly stripping leading `Re:`, `RE:`, `Fwd:`, `FW:`, `AW:`, `SV:`, then trim and lowercase.
   - Otherwise none.
6. If none: find or create the customer by lowercased email. Split the display name into `name`; leave it null if absent. Create the conversation with `status = active`, `subject` (or `(no subject)`), a fresh `reply_token`, and `number` from the sequence.
7. Insert the inbound message. Split the body with a quote detector on `text` that cuts at the first line matching any of:
   - `^On .+ wrote:$` (allow the line to wrap once)
   - `^-----Original Message-----`
   - `^From: .+` followed within 3 lines by `^Sent: ` or `^Date: `
   - a run of 3 or more lines starting with `> `
   - in `html`, a `<div class="gmail_quote">` or `<blockquote type="cite">` boundary
   Everything after the cut goes in `quoted_text`. If the detector leaves `text_body` empty, keep the whole thing in `text_body` and null `quoted_text`.
8. Store attachments in object storage under `attachments/<message_id>/<filename>`. Reject any single file over 10 MB with a log line; keep the message.
9. Update the conversation: `last_customer_message_at = sent_at`, `message_count += 1`. If the status was `closed` or `pending`, set it to `active` and write a `reopened_by_customer` event. Increment the customer's `conversation_count` only on a new conversation.
10. Return 200 with `{ conversation_id, message_id, matched_by: "headers" | "token" | "subject" | "new" }`. Return 200 for every handled case so the provider stops retrying. Return 500 only on a database error.

Run steps 3 through 9 in one transaction so a retry mid-way can't leave a conversation without a message.

### Outbound reply (`POST /api/conversations/:id/reply`)

1. Body: `{ text_markdown, status_after: "closed" | "active" | "pending", attachments?: [] }`. Validate with zod. Notes go to `POST /api/conversations/:id/note` and are never emailed.
2. Render markdown to HTML and to plain text. Append the agent's signature if set, else the mailbox signature.
3. Generate `message_id = <conv-<conversation_id>-<uuid>@<reply_domain>>`. Set `in_reply_to` to the `message_id` of the most recent inbound message. Set `references` to that message's `references` plus its `message_id`, capped at the last 20 entries.
4. Send with:
   - `from: "<agent name> (<mailbox display_name>) <mailbox address>"`
   - `to: customer email`
   - `cc: the cc list from the last inbound message minus the mailbox address`
   - `reply_to: support+<reply_token>@<reply_domain>`
   - `subject: "Re: <conversation subject>"` (don't double the `Re:`)
   - the three threading headers above
5. Insert the outbound message with `delivery_status = queued` before sending. On provider success set `sent` and store `provider_message_id`. On failure set `failed`, store the error, and show a red "Not sent, retry" banner on the message in the thread. `POST /api/messages/:id/retry` reuses the same `message_id`.
6. Update the conversation: `last_agent_message_at`, `message_count`, `status = status_after`, `closed_at` when closing (null it when reopening), `first_response_at` if null. Write a `status_changed` event when the status changed. Bump `use_count` on any saved reply that was inserted.
7. If the conversation has no inbound message yet (an agent started it from a customer page), send without `In-Reply-To` and still set `Reply-To` with the token.

### Saved replies

- Variables: `{{customer.first_name}}`, `{{customer.name}}`, `{{customer.email}}`, `{{agent.first_name}}`, `{{agent.name}}`, `{{conversation.subject}}`, `{{conversation.number}}`, `{{mailbox.name}}`.
- `first_name` is the first whitespace-separated token of `name`.
- Fallbacks when a value is missing: `{{customer.first_name}}` becomes `there`, `{{customer.name}}` becomes the email local part, everything else becomes an empty string.
- Unknown variables stay as literal text so the agent notices.
- Put this in `lib/templates.ts` as a pure function and unit test it.

### Status, assignment, tags (`PATCH /api/conversations/:id`)

- Accepts `{ status?, assignee_id?, add_tags?: string[], remove_tags?: string[] }`. Every change writes a `conversation_events` row.
- Closing sets `closed_at`. Reopening (any status to `active`) nulls it.
- `spam` hides the conversation from every folder except Spam and increments `customers.custom.spam_count`. Future emails from that customer still create conversations; don't auto-drop them.
- Assigning to yourself from the inbox list is one keystroke (`a`).
- Tag names are created on first use, lowercased and trimmed. Merging tags in Settings moves every `conversation_tags` row and deletes the old tag.

### Collision detection

- The conversation page calls `POST /api/conversations/:id/presence` with `{ state: "viewing" | "replying" }` on open, every 15 seconds while open, on focus of the composer (`replying`), and on blur back to `viewing`. It calls `DELETE` on unmount and on `pagehide`.
- The server upserts `presence` with `seen_at = now()`.
- The page fetches (or subscribes to) presence every 10 seconds and shows a banner above the composer for every other user with `seen_at` within the last 45 seconds: "Sam is viewing this conversation" in gray, or "Sam is replying to this conversation" in amber with the composer border turned amber. Never show the current user.
- The presence endpoint deletes rows older than 5 minutes on every write.
- Sending a reply while someone else is `replying` still works, behind a confirm dialog: "Sam is also replying. Send anyway?"

### Reports (`GET /api/reports/daily?from=YYYY-MM-DD&to=YYYY-MM-DD`)

- Day boundaries are in the mailbox timezone. Convert every timestamp with `date-fns-tz` before bucketing. Never bucket on UTC dates.
- Per day: `new_conversations` (created that day), `replies_sent` (outbound messages with `delivery_status = sent` that day), `closed` (conversations with `closed_at` that day), `median_first_response_minutes` (over conversations created that day with `first_response_at` set), `median_resolution_minutes` (over conversations closed that day, `closed_at` minus `created_at`).
- Show medians as `1h 12m` in the UI and as integer minutes in CSV. Show a dash when there are no samples.
- Per agent for the range: `replies_sent`, `closed`, `median_first_response_minutes` over conversations where their reply was the first response.
- Cap the range at 366 days. Default to the last 30 days.
- The `report-digest` cron runs at 08:00 mailbox time and emails yesterday's row to every admin. Skip the send when there was no activity.

### Search

- `GET /api/search?q=` searches conversations by subject `ILIKE`, messages by `text_body` full text, and customers by email or name.
- Return the top 20 conversations with the matching snippet.
- Search inside the inbox respects the current folder.

### Help center

- `GET /api/help/search?q=` runs `websearch_to_tsquery('english', q)` against `articles.search_vector` where `published = true`, ranked with `ts_rank`, with `ts_headline` snippets. Limit 10.
- Markdown renders through `marked` and then `sanitize-html` with a strict allowlist: no scripts, no iframes, no inline event handlers, links get `rel="noopener"`.
- Headings get ids for the table of contents.
- Article pages are statically cached and revalidated on publish with `revalidatePath`.
- Increment `view_count` in the background; never block the page on it.

### Timezones and dates

- Store every timestamp as `timestamptz`.
- Render in the mailbox timezone in the app and the report. Lists show relative times ("14m ago"); hover and the thread show absolute times ("Sep 10, 2026, 3:42 PM EDT").
- The `sent_at` for an inbound message is the email's `Date` header when it parses and is within 24 hours of now. Otherwise use the webhook receipt time. A spoofed or broken `Date` header must not push a conversation to the top or bottom of the inbox.
- Report day buckets use the mailbox timezone at query time. If an admin changes the timezone, historical days re-bucket. That's expected; say so in the UI.

### Edge cases to handle

- A customer emails from two addresses about the same thing. Don't auto-merge. The customer merge tool in the UI handles it.
- A customer CCs a colleague. Replies go to the customer and CC the colleague. If the colleague replies, they join the same conversation by headers and get a customer record of their own.
- An agent replies to a conversation that was already closed by a teammate 10 seconds ago. The reply still sends; the status follows `status_after`.
- The same person emails support@ and billing@ (a future second mailbox). Customers are per mailbox, so they'd be two records. Fine for now.
- An inbound HTML-only email with no `text` part: derive `text_body` from the HTML with `html-to-text` before running the quote detector.
- Subject longer than 998 characters or containing newlines: truncate to 255 and strip control characters before storing.

## Integrations

- **Inbound provider.** Document all three setups in the README: Resend inbound (MX record plus webhook), Postmark inbound (MX record or forwarding plus webhook with basic auth in the URL), and a Cloudflare Email Worker that posts the raw message to the webhook with a shared secret. Provide an adapter per provider in `lib/inbound/<provider>.ts` that normalizes to one `InboundEmail` type. The route picks the adapter from `INBOUND_PROVIDER`.
- **Outbound provider.** Same shape: `lib/outbound/<provider>.ts` exposing `send(email: OutboundEmail): Promise<{ provider_message_id }>`. Both Resend and Postmark accept custom headers; set all three threading headers explicitly. Do not rely on the provider to generate `Message-ID`.
- **DNS.** README lists the exact records: MX for inbound, SPF, DKIM, DMARC (`p=none` to start). Explain that replies from support@ need DKIM on `reply_domain` or Gmail shows "via" and may junk them.
- **Storage.** Supabase Storage or S3 for attachments, private bucket, signed URLs that expire in 1 hour.
- **OpenRouter (optional, behind `OPENROUTER_API_KEY`).** "Draft reply" sends the last 10 messages plus the 3 best-matching published articles (reuse the help center search) and inserts the result into the composer for editing. "Summarize" writes a 3-sentence summary as a private note. Never send anything to the customer automatically.

## Non-goals

Do not build: live chat or a website widget, AI answers sent without a human, phone or SMS, WhatsApp or social channels, multiple brands, SSO, SLAs, a workflow rule editor, customer satisfaction ratings, a mobile app. If you're tempted, add a TODO comment instead. Keep `mailbox_id` on every table so a second inbox is a later feature and not a rewrite.

## Acceptance criteria

1. A new user signs in, creates the mailbox, and invites a teammate who signs in and sees the same inbox.
2. `POST /api/inbound` with a new email from `jane@example.org` creates a customer, a conversation with `status = active` and a `reply_token`, and one inbound message. `matched_by` is `new`.
3. Posting the same payload again (same `Message-ID`) returns 200 and creates nothing.
4. A reply from the app sends one email with `From` set to the mailbox address, `Reply-To` containing the `reply_token`, `In-Reply-To` equal to the customer's last `Message-ID`, and `References` containing every prior id in order. The outbound message is stored with its own `Message-ID`.
5. An inbound email whose `In-Reply-To` is the outbound `Message-ID` from criterion 4 lands in the same conversation with `matched_by = headers`, and a closed conversation flips back to `active` with a `reopened_by_customer` event.
6. An inbound email with no threading headers but addressed to `support+<token>@` lands in the right conversation with `matched_by = token`. One with no headers and no token but a matching normalized subject from the same customer within 30 days matches with `matched_by = subject`. The same subject from a different customer creates a new conversation.
7. An email with `Auto-Submitted: auto-replied` or from `mailer-daemon@` is dropped with a 200 and no rows.
8. A Gmail-style reply with `On Tue, Sep 8, 2026 at 3:41 PM Acme Support wrote:` followed by quoted lines stores only the new text in `text_body` and the rest in `quoted_text`.
9. Inserting a saved reply fills `{{customer.first_name}}` from the customer's name, falls back to `there` when the name is null, and leaves `{{unknown.var}}` untouched.
10. A note is stored with `kind = note`, appears in the thread, and no email is sent (assert the outbound mock was not called).
11. Two agents open the same conversation; within 20 seconds each sees the other's viewing banner, and focusing the composer changes the other agent's banner to "replying".
12. A customer's page lists every conversation for that email, and the inbox search finds a conversation by a word in a message body.
13. A published article is reachable and searchable at `/help`; unpublishing it makes the URL 404 and removes it from search.
14. The daily report for a seeded day matches hand-computed counts and medians, and a conversation created at 11:30 PM in `America/Los_Angeles` is bucketed on that calendar day even though it is the next day in UTC.

## Deliverables

- The app, migrations, and a seed script that creates the demo mailbox described above.
- `fixtures/inbound/` with real-shaped webhook payloads for each provider covering: a new email, a reply with `In-Reply-To`, a reply with only `References`, a reply with a `reply_token` and no headers, a subject-only match, an auto-reply, a bounce, a duplicate `Message-ID`, a Gmail quoted reply, an Outlook quoted reply, an HTML-only email, and an email with two attachments.
- `lib/threading.ts` (conversation matching), `lib/quotes.ts` (quoted text splitter), and `lib/templates.ts` (saved reply variables) as pure, unit-tested modules.
- README covering environment variables, the inbound and outbound provider setup with exact DNS records, how to replay a fixture against a local server with `curl`, and how to deploy to Vercel with the cron.

Build in this order: schema and migrations, then `lib/threading.ts` and `lib/quotes.ts` with their tests against the fixtures, then the inbound route, then the outbound reply, then the inbox and conversation screens, then everything else. Send yourself a real email through the deployed webhook before you build the reports.