Skip to content

Email Orchestration Workflow (EML)

Module Purpose: The central nervous system of the platform. It continuously connects to mailboxes (Outlook/Gmail/IMAP), extracts intent from unstructured emails using AI, and routes them to the correct workflow (Sales, ERP, or Support).

[!NOTE] Philosophy: "No Email Left Behind." Every incoming email must either be converted to a Lead, linked to an Order, or explicitly archived. Zero inbox is the goal.

Use Case Quick Reference

ID Title Priority
EML-001 Monitor Email Mailboxes P1
EML-002 Classify Email to CRM Stream P1
EML-003 Classify Email to ERP Stream P1
EML-004 Create Lead from Email P1
EML-005 Link Email to Existing Lead P1
EML-006 Track Quote Milestone P1
EML-007 Lookup Order in ERP P1
EML-008 Set Dispatch Priority Flag P1
EML-009 Send Dispatch Confirmation P1
EML-010 Assign Task ID to Email P1
EML-011 Update Task Status P1
EML-012 Send Escalation Alert P2
EML-013 Multi-Entity Validation P1
EML-014 Pincode Route Planning P2
EML-015 Campaign Result Tracking P2
EML-016 Outlook-to-Salesforce Push P2

UC-EML-001: Monitor Email Mailboxes

What It Does

Continuously polls connected mailboxes (Outlook 365, Gmail, IMAP), fetches new emails, downloads attachments, and pushes them into the central processing queue. Example: fetching sales@pebble.com every 30 seconds.

Who: System Background Worker
When: Continuous (24/7)
Why: To ensure real-time responsiveness without humans manually checking inboxes.

How It Works

  1. Poll: Worker wakes up every 30s.
  2. Fetch: Connects via OAuth2/IMAP. Queries UNSEEN messages.
  3. Download:
  4. Fetches Body (HTML/Text).
  5. Fetches Attachments (PDF, Excel, Images).
  6. Generates unique ID EML-202X-XXXX.
  7. Mark: Sets email value as READ on the server (if configured) or just tracks ID to avoid re-fetch.
  8. Enqueue: Pushes to processing_queue for EML-002.

Edge Cases

Token Expiry: Automatically refreshes OAuth tokens. If refresh fails, alerts Admin.
Giant Attachment: If > 25MB, skips download, leaves link to original email, flags warning.

UC-EML-002: Classify Email to CRM Stream

What It Does

The "Traffic Cop". Analyzes incoming email content to decide if it belongs to the Sales/CRM pipeline (Enquiry, Complaint) or elsewhere.

Who: System AI Engine
When: Immediately after Ingestion

How It Works

  1. Input: Subject + Body Text.
  2. Analysis: AI Keyword Scanner matches against CRM definitions:
  3. "Quote", "Price", "Availability" -> Enquiry
  4. "Complaint", "Broken", "Late" -> Complaint
  5. "Demo", "Visit" -> Meeting Request
  6. Action:
  7. If Match: Tag as Stream: CRM.
  8. Forward to EML-004.

[!TIP] Implementation Reference: Detailed User Stories and Acceptance Criteria for this classification logic are defined in prd-ai-email-classification.md.

Success Signals

✅ Correctly segregates Sales emails from Spam/Ops emails.

UC-EML-003: Classify Email to ERP Stream

What It Does

Identifies operational emails related to existing orders, logistics, or procurement, which belong in the ERP workflow rather than Sales.

Who: System AI Engine
When: Immediately after Ingestion

How It Works

  1. Pattern Match: Looks for Order Patterns (e.g., PO-1234, INV-987) or Logistics keywords (Dispatch, Tracking, Invoice).
  2. Action:
  3. If Match: Tag as Stream: ERP.
  4. Extract Order ID if present.
  5. Forward to EML-007.

[!TIP] Implementation Reference: Detailed extraction rules and multi-intent handling for ERP streams are in prd-ai-email-classification.md.

Edge Cases

Ambiguous Email: "Where is my order?" (Could be Complaint or Status Check). Logic: Default to CRM Complaint for human review if sentiment is negative.

UC-EML-004: Create Lead from Email

What It Does

Auto-generates a "Prelead" record from a raw email. It scrapes the sender's info, company signature, and product interest to pre-fill the form, saving the rep 5 minutes of data entry.

Who: System
When: Classification = Enquiry

How It Works

  1. Scraping:
  2. Sender: Use From header.
  3. Company: Extract from @domain.com or Email Signature text.
  4. Phone: Regex scan signature for +91...
  5. Product: NLP keyword extraction from body ("Zinc Oxide", "Titanium").
  6. Creation:
  7. Inser into preleads table.
  8. Status: New.
  9. Source: Email Inbound.
  10. Snapshot: Saves HTML rendering of email as a static image/file attached to the lead for audit.

Success Signals

✅ Pre-fills 80% of fields accurately.
✅ Captures Email Signature details (Phone/Designation).

UC-EML-005: Link Email to Existing Lead

What It Does

Prevents duplicates. Checks if the sender john@apple.com already exists in the CRM. If yes, it logs this email as an "Activity" on John's timeline instead of creating a new Lead.

Who: System Dedupe Engine
When: Before creating new lead

How It Works

  1. Lookup: Query contacts table by Email Address.
  2. Match Found:
  3. Add Email to activities table linked to Contact ID.
  4. Bump "Last Interaction" timestamp.
  5. Notify Account Manager: "New email from John".
  6. Thread Check: If subject matches previous thread, attach to existing Ticket/Opp.
  7. No Match: Proceed to EML-004.

UC-EML-006: Track Quote Milestone

What It Does

Monitors the "Quote Sent" SLA. If a lead requested a quote but none was sent within 24 hours, it flags the manager.

Who: System Watchdog
When: Periodic Check

How It Works

  1. Trigger: Card moved to "Quote Requested" column.
  2. Timer: Starts 24h countdown.
  3. Check: Has a file been uploaded to "Quotations" tab?
  4. Breach: If Timer > 24h and No Quote:
  5. Turn Card Red.
  6. Send Email to Team Lead.

UC-EML-007: Lookup Order in ERP

What It Does

For ERP-stream emails, it acts as a bridge. It takes the specific Order ID mentioned in the email and calls the ERP API to fetch live status (e.g., "Packed", "Shipped").

Who: System Connector
When: Stream = ERP

How It Works

  1. Extraction: Identify ORD-2023-001.
  2. API Call: GET /erp/orders/ORD-2023-001.
  3. Enrichment:
  4. Add "Order Status: Shipped" tag to the email card.
  5. Display "Expected Delivery: 12th Jan" on the card face.

UC-EML-008: Set Dispatch Priority Flag

What It Does

Allows a Sales Rep to mark an order as "Urgent" directly from the email interface. This pushes a priority flag to the Warehouse ERP view.

Who: Sales Rep
When: Manual Action (Card Button)

How It Works

  1. User Action: Clicks "Mark Urgent Dispatch" on email card.
  2. System:
  3. Updates CRM Task Priority = High.
  4. API Push: Updates ERP Order priority field.
  5. Notify: Slack message to Warehouse Manager.

UC-EML-009: Send Dispatch Confirmation

What It Does

Closes the loop. When ERP marks order as "Shipped", system auto-sends the tracking details to the customer, replying to their original status enquiry thread.

Who: System Automation
When: ERP Status Change event

How It Works

  1. Trigger: ERP Webhook order.shipped.
  2. Compose:
  3. Template: "Your order {ID} has shipped via {Carrier}."
  4. Tracking URL: Generated dynamically.
  5. Send: Reply to last customer email thread.
  6. Close: Archive the enquiry card.

UC-EML-010: Assign Task ID to Email

What It Does

Ensures every actionable email has a unique internal ID (e.g., TSK-9988) separate from the email ID, used for SLA tracking and ticketing.

Who: System
When: On Ingestion

How It Works

  1. Generate: TSK-YYYY-{Sequence}.
  2. Stamp: Save in database.
  3. Reference: Add to Email Subject in replies: [Ref: TSK-9988]. This ensures future replies thread correctly.

UC-EML-011: Update Task Status

What It Does

Syncs the visual Kanban status (e.g., "In Progress") with the underlying database record, ensuring reporting dashboards are accurate.

Who: System / User
When: Drag-and-drop event

How It Works

  1. Event: User drags card to "Done".
  2. Update: Set status = Closed, completed_at = Now().
  3. Log: Record "User X closed task TSK-9988" in audit log.

UC-EML-012: Send Escalation Alert

What It Does

The "Siren". If High Priority items sit untouched for > 4 hours, it notifies senior management.

Who: System Watchdog
When: Hourly Cron

How It Works

  1. Scan: Find cards where Priority = High AND Last_Activity > 4 hours.
  2. Alert:
  3. Level 1 (4h): Email User.
  4. Level 2 (8h): Email Manager.
  5. Level 3 (24h): Email VP Sales.

UC-EML-013: Multi-Entity Validation

What It Does

Checks if the customer exists in any of the group companies. Prevents creating "Acme Corp" in Entity A if it already exists in Entity B (unless intentional), or helps link them as Group Companies.

Who: System Validator
When: Lead Creation

How It Works

  1. Input: CIN / GST / PAN / Company Name.
  2. Global Search: Query Master DB across all Tenancy scopes.
  3. Result:
  4. Match Found: "Company exists in 'Alpha Pebble Singapore'. Linking as Group Account."
  5. No Match: "Clean to create."

UC-EML-014: Pincode-based Route Planning

What It Does

Helps field sales planning. When a rep visits a customer, system suggests "Nearby Leads" based on pincode proximity to maximize trip value.

Who: Sales Rep (Mobile App)
When: Planning visits

How It Works

  1. Input: Target Customer Pincode (e.g., 400001).
  2. Search: Find all Open Enquiries with Pincode within 5km radius.
  3. Display: List/Map view. "3 other leads near here."

UC-EML-015: Campaign Result Tracking

What It Does

Closes the ROAS loop. Tracks how many inbound enquiries resulted from specific email/marketing campaigns.

Who: System Analytics
When: Enquiry Ingestion

How It Works

  1. Match: Check if sender email target was in a recent Outbound Campaign list.
  2. Tag: If yes, tag Lead Source = "Campaign: Q1 Promo".
  3. Attribute: If this lead converts to Order, attribute revenue to that Campaign ID.

UC-EML-016: Outlook-to-Salesforce Push

What It Does

A manual plugin for Outlook. Allows users to "Right Click -> Push to Pebble" for emails that bypassed the auto-ingestion (e.g., personal inbox).

Who: User (Outlook Plugin)
When: Manual

How It Works

  1. Select: User highlights email in Outlook.
  2. Click: "Push to Pebble" button.
  3. Action: Plugin sends JSON payload (Body, Attachments) to Pebble Ingestion API v1/ingest/email.
  4. Feedback: Show "Success! Ticket #123 created."

See Also

  • PRD AI Email Classification: tasks/prd-ai-email-classification.md
  • Entity Triage PRD: tasks/prd-entity-triage.md
  • PRD Template: .agent/workflows/prd.md

Traceability Map

  • EML-001 Monitor Email Mailboxes -> Aligns with PRD: Email Orchestration UC-EML-001 and PRD US-001 (CRM/ERP routing) in tasks/prd-ai-email-classification.md.
  • EML-002 Classify Email to CRM Stream -> See PRD: AI Email Classification US-002; tasks/prd-ai-email-classification.md.
  • EML-003 Classify Email to ERP Stream -> See PRD: AI Email Classification US-003; tasks/prd-ai-email-classification.md.
  • EML-004 Create Lead from Email -> See PRD: AI Email Classification US-004; tasks/prd-ai-email-classification.md.
  • EML-013 Multi-Entity Validation -> See PRD: Entity Triage US-002/US-004; tasks/prd-entity-triage.md.

← Back to Use Cases