Email Inbox UX — Product Requirements

Status: Product requirements draft (discovery + roadmap), not a definitive “what is live now” reference. Informed by: Jason Bail (BCS Senior Enterprise Engineer), Adam Martinez (BCS Field Ops) Related: docs/poc/bcs-poc-analysis.md

[!IMPORTANT] If you need current operator behavior (RBAC controls, supervisor/admin dashboard actions, SLA policy editing, and policy history), start with docs/product/inbox-rbac-sla-operations-guide.md.

This document remains the product intent and roadmap source.

This document captures UX requirements for Ordermatic’s email integration and inbox management features — beyond what the current forwardable-address PoC covers. Scoped into three tiers:

PoC — must work for the Thursday demo
V1 — needed before BCS production go-live
Roadmap — directionally committed but not yet scheduled

Current state snapshot (April 2026)

Role-aware inbox operations are now capability-gated (standard user, supervisor, org admin).
Supervisor/admin dashboard surfaces ship with SLA and analytics controls.
SLA threshold policy editing + audit-backed history are live for eligible roles.
Client and API paths are deny-by-default for privileged inbox actions.

For implementation details and system behavior, see docs/architecture/unified-inbox.md.

1. Email Connector Architecture

Current State (PoC)

Forwardable email address per org/rep. The user sets up a forwarding rule in their email client to copy incoming mail to their Ordermatic forwardable address. Ordermatic processes inbound messages and triages them.

Pros: Zero per-rep auth, works with any email provider, fast to deploy. Cons: Forwarding rules must be configured manually per rep, not a live two-way sync, can’t write back to the source inbox (archive, label, reply).

V1 — OAuth Direct Connector

Provider	Scope	Priority
Microsoft 365 / Outlook	`Mail.Read`, `Mail.ReadWrite`, `Mail.Send`	🔴 HIGH — BCS, most distributors
Google Workspace / Gmail	Already partially in place	🟡 MEDIUM — smaller accounts

What OAuth unlocks:

Read inbox without forwarding rules
Write back: archive, label, mark read, move messages
Send replies from within Ordermatic (follow-up threads — see §6)
Admin can connect org-level shared mailbox + individual rep mailboxes
Near-real-time delivery (webhooks/push) vs polling

Change management note (from BCS call): Canal’s per-rep OAuth was flagged as a barrier. Consider: org admin connects the org mailbox + grants Ordermatic access to rep mailboxes via delegated permissions (M365 admin consent flow), so reps don’t have to do anything. One admin action → all reps covered.

Roadmap — Additional Connectors

Generic IMAP/SMTP (for self-hosted mail servers — common in industrial distribution)
Shared mailbox support (orders@company.com as a first-class inbox type)
Webhook/push delivery via M365 Graph subscriptions

2. Inbox Triage — AI Filtering

Current State

AI leans toward including messages as potential orders. Result: noise (receipts, marketing, personal emails) gets surfaced alongside real orders.

V1 Requirements

Classification tiers (not binary):

Tier	Label	Action
Order	`order`	Extract and queue for review
Quote request	`quote`	Extract and queue separately
Follow-up / response	`follow_up`	Attach to existing order thread
Not an order	`noise`	Auto-archive, never surface
Uncertain	`review`	Surface to admin for manual triage

Configurable thresholds: org admin can tune the confidence threshold for auto-archive vs surface.

Training feedback loop: when a human marks something as noise or re-classifies it, that signal improves the classifier over time (per-org model refinement).

Key insight from BCS: ~60% of their volume is email. Noise suppression is not optional — if a CSR’s inbox is filled with false positives, they’ll turn off the integration.

3. Org Admin Oversight — All Inboxes View

The Problem (from BCS)

Orders live in individual rep inboxes. When Daniel (Dallas branch manager) is on vacation, no one knows which orders he received. Result: missed orders, irate customers.

“He doesn’t give out his password… the orders get missed.” — Jason Bail

V1 Requirements

Org admin can:

See a unified queue of all orders across all connected rep inboxes + org inboxes
Filter by rep, branch, status, date range
See the source inbox for each order (whose email it came from)
Take action on any order regardless of which inbox it arrived in

Rep view:

Sees only their own inbox queue by default
Can be granted visibility into other inboxes (delegated access — see §4)

Branch grouping:

Orders grouped by branch (for multi-location distributors like BCS)
Branch admins see their branch + can be escalated to org-level if needed

Implementation note: This is the core differentiator vs Canal’s model. Canal requires per-rep auth — every rep has an account. Our model: org admin connects everything, reps benefit without touching settings.

4. Delegated Inbox Access

The Problem

When a rep is out, orders need to be rerouted. Today: nothing happens. V1: org admin can delegate access to another rep or a centralized order desk team.

V1 Requirements

Org admin can grant Rep A read + act access to Rep B’s Ordermatic inbox queue
Delegation can be permanent or time-bounded (“while rep is out of office”)
Delegated access shows in the queue with a clear indicator (“Delegated from: Daniel”)
Order desk role: a special role that gets delegated access to all reps by default (the “branch manager” use case)

Roadmap

Auto-delegation triggered by OOO detection (parse OOO auto-reply → temp delegate)
Routing rules: “if no action taken on order within 4 hours, route to order desk”

5. Inbox Management Actions

The Problem

Right now Ordermatic is read-only from the source inbox perspective. Reps still have to go back to Outlook to archive the email after they’ve processed it in Ordermatic. Creates duplicate workflows.

V1 Requirements

Actions available on any email in Ordermatic (synced back to source inbox via OAuth):

Action	Description	Priority
Archive	Remove from inbox, keep in processed	🔴 Must-have
Mark as processed	Add label/category in source inbox	🔴 Must-have
Mark as unread	Return to inbox queue	🟡 Should-have
Move to folder	Move to a designated folder in source inbox	🟡 Should-have
Snooze	Hide for N hours, re-surface	🟢 Nice-to-have

Status labels on orders (within Ordermatic, not source inbox):

Status	Meaning
`new`	Arrived, not yet reviewed
`in_review`	Someone has opened it
`submitted`	Sent to P21
`needs_attention`	Flagged for manual review (unmatched items, bad ship-to, etc.)
`on_hold`	Waiting on customer response
`completed`	Fully processed
`rejected`	Not an order / discarded

Status must be visible to org admin and anyone with delegated access — not just the rep who owns the inbox.

6. Order Follow-Up Threads

The Problem (from BCS)

Relationship is everything in distribution. CSRs want to respond to customers from within the order context — not go back to Outlook, find the thread, reply, then come back to Ordermatic. That’s the current friction.

“They spend the extra time with the customer on the phone because they want to maintain the relationship.” — David Boone (on call)

V1 Requirements

Each extracted order has a thread view: the original email + any subsequent replies in the same email chain
If a customer replies to an order email, that reply is surfaced on the order, not just in the rep’s inbox
Rep can reply directly from the order view (sends from their connected email account)
Common reply templates: “Order received, processing now”, “Need clarification on item X”, “Order submitted — confirmation #[p21_order_id]“

Roadmap

Reply suggestions generated by AI based on order content (e.g. “Item X is backordered, suggest alternative: Y”)
Internal notes on orders (visible to team, not sent to customer)
@mention a colleague on an order for escalation

7. Shared Mailbox / Branch Inbox Support

The Problem

BCS has discussed generic branch mailboxes (sanantonio.orders@building-controls.com, dallas.orders@building-controls.com) but hasn’t implemented because they didn’t have a reason to centralize until now.

V1 Requirements

Shared mailboxes are a first-class inbox type (not just individual rep inboxes)
Orders arriving in a shared mailbox are visible to anyone with access to that mailbox
Assignment: orders can be assigned from the shared queue to a specific rep
Useful pattern: orgs start with one shared mailbox (orders@) and expand to per-rep connections as they grow

Implementation Note for BCS Rollout

Recommend starting with a single shared mailbox per BCS branch as the fast-path to PoC:

BCS IT creates [branch].orders@building-controls.com
All reps forward their order emails to that address (or set up auto-forward rule)
Ordermatic connects to the shared mailbox via O365 delegated access
Branch admin gets full visibility immediately, without touching individual rep mailboxes

This is the lowest-friction path to centralization — no per-rep auth, no change management.

8. UX Principles (from Discovery)

These came directly from watching how BCS described their workflow:

Background processing is the goal — CSRs should not be forced to babysit the system. Orders should be processed and queued while they’re on the counter. They check the queue when they have a free moment, not because the system demands it.
Relationship first — The counter interaction is the value. Ordermatic removes the administrative burden around the relationship, not the relationship itself.
Never make P21 data worse — Don’t create garbage (duplicate ship-tos, bad part numbers, orphaned records). When uncertain, flag for human review. Autonomy is earned through accuracy, not assumed.
Crawl → Walk → Run — V1 has high human-in-the-loop. As accuracy improves (top result selected >90% of the time), automation can increase. Never skip steps.
One admin action should cover the whole org — The M365 admin consent model is the right UX pattern. One person connects, everyone benefits.

Appendix — BCS-Specific Configuration

For reference when building BCS’s production setup:

Setting	Value
Email provider	Microsoft 365
Default branch	TX-FARMERS-BRANCH (Farmers Branch, TX)
Other TX branches	San Antonio, Houston, Dallas, Austin
Suggested shared mailbox pattern	`[city].orders@building-controls.com`
Ship-to rule	Never auto-create. Match or flag.
Order volume	~408/day total, ~245/day email (~60%)
Avg lines/order	2.5
Pricing model	$1.25/order flat + $0.35/line over 5