Designing a Unified Inbox and Omnichannel Messaging for Your App

Customers talk to you over email, chat, SMS, and social—but your team needs one place to respond. This deep-dive covers the data model, routing logic, provider webhooks, compliance, and real-time UX patterns to build a reliable unified inbox. Includes practical prompts to start building with AI.

Customers don’t care which channel you prefer. They’ll email you, reply on social, text your support number, chat from your site, and expect your team to pick up the same conversation with context intact. A unified inbox solves this by normalizing every message, threading it into the right conversation, and giving your team a single place to read, respond, and automate.

This article is a practical architecture guide to designing and building a unified inbox and omnichannel messaging layer in your app. We’ll cover the core data model, inbound and outbound flows, routing and assignment, compliance and opt-outs, real-time UX, and how to evolve from a single channel MVP to a multi-channel system without rewriting everything.

Start with the workflow, not the channel

Before thinking about IMAP, webhooks, or SMS gateways, define the operator workflow:

  • New inbound messages automatically appear at the top of a shared inbox.
  • Conversations can be assigned to a teammate or team queue.
  • Agents reply from the same thread regardless of channel.
  • Customers receive responses on the channel they used (or the best available fallback).
  • Statuses (open, pending, waiting on customer, resolved) and SLAs drive prioritization.
  • Conversation history is visible regardless of channel switches by the customer.

Define this “operator contract” first. Then choose channel adapters that conform to the model, not the other way around.

Core concepts and a channel-agnostic data model

A good unified inbox normalizes every channel into a small, stable set of entities:

  • Contact: A real-world person or organization you converse with (e.g., Acme, or Jane Doe). A contact can have many identities (email address, phone number, social handle, app user ID).
  • Identity: A uniquely addressable endpoint on a channel (jane@, +1-555..., @jane_acme). Each identity belongs to exactly one contact.
  • Channel: Email, Web Chat, SMS, WhatsApp, Facebook Messenger, X/Twitter DM, In-App, etc. Treat as an enum with config per adapter.
  • Conversation: A long-lived thread between your team and a contact. It can span channels if you allow cross-channel merging.
  • Message: A single inbound or outbound piece of content (text, attachments, rich content). Messages belong to a conversation and a channel.
  • Participant: Mapping between a conversation and users/teams (assignee, followers, CC-equivalents).
  • Mailbox/Queue: A routing target (Support, Sales, Billing). Useful for permissions and assignment.
  • Event: Typed changes for audit and automations (status changed, SLA breached, assignment updated, tag added, delivery failed).

Suggested relational schema (conceptual)

{ contacts(id, display_name, org_id, created_at, ...), identities(id, contact_id, channel, handle, is_primary, verified_at, ...), conversations(id, contact_id, subject, status, priority, mailbox_id, opened_at, closed_at, ...), messages(id, conversation_id, channel, direction, body, html_body, provider_message_id, parent_message_id, sent_at, received_at, author_user_id, ...), attachments(id, message_id, url_or_blob_ref, filename, mime, size, virus_scan_status, ...), participants(id, conversation_id, user_id, role), tags(id, name), conversation_tags(conversation_id, tag_id), events(id, conversation_id, type, payload_json, created_at), mailboxes(id, name, visibility, assignment_mode, business_hours_json, ...), channel_accounts(id, channel, config_json, credentials_secret_ref, mailbox_id, ...), routing_rules(id, mailbox_id, priority, predicate_json, action_json, ...) }

Keep this model stable and map every provider’s quirks into it. The payoff is consistency: your UI, automations, and analytics operate across channels the same way.

Inbound flow: from provider webhook to conversation

Inbound messages follow a predictable pipeline:

  1. Receive event: Via provider webhook (email, social DM), gateway callback (SMS), or your own chat widget POST. Validate signatures and timestamps to reject spoofed requests.
  2. Normalize: Convert provider payload to your canonical Message shape. Extract text, HTML, attachments, author handle, thread metadata, timestamps.
  3. Idempotency: Assign a deterministic event key (e.g., provider event ID + channel account) and store a dedupe record before processing. If seen, skip.
  4. Identity resolution: Find or create an Identity based on the handle (email address, phone, social user ID). Link to a Contact. Implement merge rules later.
  5. Thread matching: Attach to an existing open Conversation if a reliable thread key is present. Otherwise, apply heuristics (last recent conversation with same identity and subject) or create a new conversation.
  6. Store message: Persist normalized content and attachments. Run virus scan asynchronously.
  7. Auto-tag and route: Apply routing rules (keywords, language, VIP list, product area). Assign to a mailbox or agent queue. Set priority/SLA.
  8. Real-time notify: Publish a conversation update to subscribed clients (WebSockets or SSE) to light up the UI.

Email specifics worth handling

  • Parse Message-Id, In-Reply-To, and References headers for threading.
  • Honor DMARC, SPF, and DKIM checks for trust and spoof detection.
  • Strip quoted text and “reply above this line” markers to extract the new content.
  • Detect auto-replies and out-of-office to set appropriate status and avoid loops.

SMS, WhatsApp, and chat specifics

  • Normalize media messages (images, audio) and handle provider-hosted URLs expiring; copy securely to your storage.
  • Track opt-in and opt-out states per identity and channel; respect regulatory keywords (STOP, START) and country rules.
  • For web chat, generate a temporary chat session identity and merge into a contact when the user signs in.

Outbound flow: adapters, delivery receipts, and fallbacks

Outbound messages should go through a channel-agnostic SendMessage API:

  1. Compose: The agent writes a reply in the UI, optionally using templates and variables.
  2. Choose channel: Default to the channel of the last inbound message, or let agents switch. Validate compliance (e.g., SMS opt-in, WhatsApp template rules).
  3. Enqueue: Write an outbound message record with status=pending and push a job to a queue.
  4. Adapter send: The adapter transforms the canonical message to provider format, applies rate limits, and sends.
  5. Receipt handling: Webhooks update status (delivered, read, failed). Persist on the message and emit events.
  6. Fallbacks: If a channel fails for policy or deliverability, allow a manual or rules-driven fallback (e.g., from WhatsApp to SMS). Log the reason.

Drafts, internal notes, and macros

  • Drafts live on the conversation and are per-agent until sent.
  • Internal notes are messages with direction=internal; never deliver externally.
  • Macros are templated sets of actions: add tags, set status, insert a message template, schedule a follow-up.

Conversation lifecycle and states

Keep conversation status simple and automatable:

  • Open: Needs agent action.
  • Pending: Waiting on third-party or internal action; SLA paused if your policy allows.
  • Waiting on customer: Customer needs to respond; snooze or auto-close after time.
  • Resolved: Closed; re-open on inbound reply.

Use a small state machine so automations are reliable and analytics are interpretable. Emit events when status changes to drive dashboards and alerts.

Routing, assignment, and SLAs

Build routing rules as data, not code. A rules engine can evaluate predicates against message and contact fields:

  • Predicates: channel=email, subject contains "refund", language=es, contact.tier=Enterprise, business_hours=true, mailbox=Support
  • Actions: assign to team=Billing, set priority=High, add tag=Refund, SLA=2h, auto-reply=template RefundReceived

Assignment modes:

  • Round-robin: Evenly distribute new conversations to available agents.
  • Push: Put into a queue; agents “take” when ready.
  • Expertise-based: Match product area or language to agent skills.

Track SLA clocks per conversation with pause/resume and breach events. Use business hours calendars per mailbox to avoid unfair breaches.

Identity and contact merging

Customers switch channels. Your model should allow merging identities into a single contact without losing history:

  • Provide an admin tool to merge contacts and reassign identities safely.
  • Support cross-channel linking: If an email signature reveals a phone number that matches an existing contact, suggest a merge.
  • Once merged, show the full conversation history across all channels in the timeline.

Be cautious with auto-merges. Prefer human-in-the-loop suggestions to avoid privacy or data protection issues.

Permissions and mailbox scoping

Design permissions so teams only see what they should:

  • Mailbox visibility: Agents can access only assigned mailboxes.
  • Conversation-level access: Assigned agent, their team, and admins can view; others see redacted or no access.
  • Private notes: Internal-only regardless of mailbox.

Audit trails are critical. Log reads of sensitive content, assignment changes, tag updates, and exports.

Real-time UX: responsive without being noisy

Agents expect immediate updates. Use server push (WebSockets or SSE) to broadcast:

  • New conversations in visible mailboxes.
  • Message arrivals and delivery/read receipts.
  • Status, tag, and assignment changes.

Implement presence (who else is viewing) and composer collision (warn if two agents are replying). Optimistic UI is great, but reconcile with server truth to avoid duplicates.

Compliance, privacy, and safety

  • Opt-outs: Per identity and channel. Enforce at send time. Keep a suppression list.
  • PII handling: Classify and mask in logs. Restrict export permissions. Provide data subject request workflows to locate and delete a contact’s data when required by law.
  • Attachment security: Virus scan on upload or fetch. Use time-limited signed URLs. Strip dangerous HTML on email render.
  • Credential storage: Provider tokens and API keys in a secrets manager with least-privilege scopes.

Search, reporting, and analytics

Invest early in useful filters:

  • Status, mailbox, assignee, tag, channel, language, sentiment (if you compute it responsibly), first response time, last activity.
  • Text search across subject and message body; consider full-text indexing with highlighting.

Key dashboards:

  • Volume by channel, hour of day, and mailbox.
  • First response time and resolution time distributions.
  • Backlog and SLA breach counts.
  • Agent workload and performance (be careful and fair with metrics).

Automation: do the obvious things automatically

  • Auto-responders: Business-hours aware, language-aware, with smart throttling to avoid loops.
  • Classification: Lightweight triage (billing vs. technical vs. sales) based on keywords or models; never let automation prevent a human from replying.
  • Snooze: Wake a conversation later and return it to Open if the customer hasn’t replied.
  • Follow-ups: Schedule a reminder if no agent reply in X minutes for high-priority conversations.

Channel adapters: keep them thin and replaceable

Model adapters as pure transformers plus a small send/receive boundary:

  • Inbound: Validate → Normalize → Publish canonical event.
  • Outbound: Accept canonical message → Map fields → Enforce policy → Send → Emit receipt events.

Do not let provider-specific fields leak into your core model unless absolutely necessary (store them in a provider_metadata JSON column when you must retain them).

Performance and reliability

  • Queues everywhere: Inbound processing, outbound sending, and heavy tasks (parsing, virus scan, NLP). Keep webhooks fast.
  • Idempotency keys: Across inbound events and outbound retries to avoid duplicates.
  • Outbox pattern: For at-least-once delivery of your internal events.
  • Dead-letter queues: Capture poison messages with enough context to replay after fixes.
  • Backpressure: Rate-limit per channel account to respect provider quotas and avoid bans.

Deliverability and branding

For email, configure authenticated sending on your customers’ domains if you support multi-tenant mailboxes. Provide onboarding steps to set up DNS records (SPF, DKIM, DMARC). For SMS/WhatsApp, ensure brand registration where required and use approved templates for initiations.

UI patterns that keep agents fast

  • Three-pane layout: Mailboxes/filters, conversation list, message thread.
  • Keyboard shortcuts: Reply, assign, tag, snooze, resolve.
  • Inline attachments with quick preview and safe download.
  • Suggested actions: Based on routing rules or simple classifiers.

MVP first, then expand channels

Don’t start by integrating everything. A pragmatic path:

  1. Phase 1 (Email-only): Build the core model, conversation UI, assignment, and SLAs using inbound email plus outbound sending.
  2. Phase 2 (Web chat): Add your own chat widget and identity merging when users sign in.
  3. Phase 3 (SMS/WhatsApp): Add a telephony gateway with opt-in/out enforcement and rate limits.
  4. Phase 4 (Social): Add DMs for the platforms that matter to your customers. Build fallbacks and provider policy checks.

Testing strategies and sandboxes

  • Provider sandboxes: Use official test accounts, simulator numbers, or DM sandboxes where offered.
  • Contract tests: Validate your normalization logic against fixed provider payloads.
  • Chaos testing: Randomly drop or delay receipts to ensure your UI handles partial state gracefully.

Building this with AI: prompts that move the ball forward

YeshBe is a platform for building software with AI. You describe the system you want, refine it through conversation, and the platform helps you create the application—UI, data, workflows, and integrations—without starting from a blank codebase. Here are example prompts you can adapt when you’re ready to prototype a unified inbox.

Create a unified inbox web app for a small support team. Core features: mailboxes (Support, Sales), contacts with multiple identities, conversations with statuses (Open, Pending, Waiting on customer, Resolved), messages with attachments, assignment to agents, tags, and a three-pane UI. Add server push so new messages appear in real time.

Add an inbound email channel adapter. Receive provider webhooks, validate signatures, extract Message-Id, In-Reply-To, References, and normalize to our Message model. Implement idempotency to prevent duplicates. Thread to existing conversations by email headers or subject heuristics. Store attachments and queue virus scanning.

Add outbound sending for email with a queued job and delivery receipt handling. Update message status on delivered/failed. Show delivery status in the UI. Include a suppression list for opt-outs and enforce it before sending.

Add web chat as a second channel. Anonymous visitors get a temporary chat identity tied to a cookie. If they log in, merge the temporary identity into their contact. Update the UI to show cross-channel history for the contact.

Optional detailed spec to paste: - Entities: Contact, Identity, Conversation, Message, Attachment, Participant, Mailbox, Event, Tag - Conversation states: Open, Pending, Waiting on customer, Resolved (reopen on inbound) - Routing: simple rules based on subject keywords and mailbox business hours - Real-time: WebSockets; broadcast new messages and status changes - Security: RBAC with mailbox scoping; internal notes never leave the system - Testing: stub adapters for channels to simulate inbound/outbound flows

As you iterate, you can ask YeshBe to adjust data models, refine routing rules, add compliance checks, or scaffold provider integrations. Treat AI as an accelerator for your clear specifications and decisions.

Operational readiness: monitoring and runbooks

  • Health checks for webhook endpoints and outbound queues.
  • Provider quota monitors and alerts before throttling kicks in.
  • Dead-letter dashboards with replay buttons and sample payloads.
  • Runbooks for common incidents: DNS misconfig for email, expired API tokens, SMS template rejections, elevated bounce rates.

Common pitfalls and how to avoid them

  • Leaky provider details: Keep them in adapter metadata so your core model stays clean.
  • Over-threading: Being too aggressive at merging separate issues into one conversation. Prefer precise keys; let agents split threads if needed.
  • Ignoring opt-outs: Centralize suppression checks in the send path so nothing slips through.
  • UI lag: Without real-time updates, your agents will refresh constantly. Push updates from the start.
  • Noisy automations: Rate-limit auto-replies and don’t auto-close too fast; let customers re-open easily.

A minimal capability checklist

  • Contacts with multiple identities and a safe merge workflow.
  • Stable conversation model with clear statuses.
  • Idempotent inbound processing and queued outbound sending.
  • Adapter interfaces for each channel with normalization and receipts.
  • Routing rules, assignment, SLAs, and automation hooks.
  • Real-time updates and a fast, keyboard-friendly UI.
  • Opt-out compliance, virus scanning, and secure attachment delivery.
  • Search, filters, and operational metrics.

Where to go next

Start with email-only to validate your model and operator workflow. Add chat next to exercise real-time behavior, then introduce SMS or WhatsApp with strict compliance. By keeping your data model stable and adapters thin, you can add channels without breaking the core experience.

When you’re ready to build, clearly specify your desired behaviors and let AI help you scaffold the app. With a sound architecture and careful treatment of provider details, you’ll give your team the superpower they’ve wanted for years: one place to read, respond, and resolve—no matter where the customer starts the conversation.

What will you build first?

Start with one sentence. You can change everything after you see it.

Free to start. No credit card.