Inbound Email Processing

10 min

Functional Specification

1. Overview & Purpose

This document outlines the functional requirements for an automated AI agent within the CommandIT platform responsible for processing inbound emails sent to designated CommandIT email addresses associated with Service Boards, Alert Endpoints, Projects, Problems, Change Requests, and specific Configuration Items (CIs). The agent's purpose is to autonomously ingest, filter, identify senders, identify potential alerts and hand them off to the CommandIT Global Alert Processing Engine, handle direct emails for specific entities (Projects, CIs, etc.), triage remaining emails to existing tickets or create new ones intelligently, and log outcomes before cleaning up temporary data. This reduces manual effort, standardizes intake, and improves response consistency.

1a. Core Principles & Goals

This document specifies the CommandIT Support AI agent designed to:

Provide a helpful, empathetic, confident, and human-like conversational experience with high emotional intelligence (EQ). (Applies more to Chat AI, less relevant here)
Leverage all accessible data within the CommandIT platform to avoid asking users for information already known. (Applies primarily to sender/CI identification)
Possess superior context awareness compared to human agents by synthesizing CommandIT data from multiple modules proactively. (Applies to classification, CI linking, etc.)
Resolve common issues directly and automatically... (Not applicable here - Triage focus)
Minimize the creation of duplicate tickets within the CommandIT PSA module by identifying existing relevant tickets, problems, or incidents.
Identify recurring or related issues across users and devices using CommandIT data to aid troubleshooting and potentially trigger Problem Management workflows within CommandIT. (Primarily via Global Alert Engine or analysis of created tickets)
Ensure tickets are created accurately, completely, and efficiently within CommandIT using templates and contextual data.
Maintain a user-focused approach, respecting requests for human assistance promptly. (Less direct interaction here)
Operate within defined communication policies, avoiding admission of fault or making unauthorized commitments. (Applies if AI sends error notifications)
Attempt to de-escalate frustrated or hostile users using defined protocols. (Not applicable here)
Operate securely, respecting user privacy and permissions, especially when performing actions or accessing data within the CommandIT platform.
Accurately track its operational costs (e.g., LLM usage) and associate them with interactions/tickets as non-billable expenses for internal accounting and KPI analysis.
Continuously improve through feedback loops and analysis of operational data captured by CommandIT and LangSmith, including identifying its own capability gaps.

2. Core Workflow

Ingestion & Staging: Email arrives -> Store raw content temporarily in InboundEmailProcessingQueue (status 'Received') + temp object/attachment store -> Identify Target Entity Type/ID based on recipient address.
Initial Filtering:
- Check sender against EmailBlocklist (Inbound). If blocked -> Update queue ('Failed_Blocklist'), Log to EmailProcessingLog, Trigger Deletion. Stop.
- Check content against Spam Filter. If spam -> Update queue ('Failed_Spam'), Log to EmailProcessingLog, Trigger Deletion. Stop.
Processing State: Update queue record to 'Processing'.
Sender Identification: Determine OrgID & ContactID/UserID (Email match, Domain match (OrganizationDomains), Content Parsing). Apply confidence score. (May be deferred if Alert Engine handles).
Targeted Workflow Execution: Route based on target_entity_type:
- If Project/Problem/ChangeRequest: (If Sender ID successful) Process Content (Section 10) -> Create respective Update record -> Log Success (Section 11) -> Trigger Deletion (Section 11). Stop.
- If CI (Device, App, Domain etc. from CiEmailMappings): (If Sender ID successful) Force New Ticket Creation -> Link CI -> Proceed to New Ticket Logic (Section 8).
- If ServiceBoard/AlertEndpoint: Execute Alert Identification & Hand-off (Section 6).
Alert Identification & Hand-off:
- Identify if email is potential alert.
- If Potential Alert: Parse data -> Pass to CommandIT Global Alert Processing Engine [See Global Alert Processing Engine Documentation]. Receive outcome.
- If Outcome is 'Ignored': Log 'Discarded_Rule' (Section 11) -> Trigger Deletion (Section 11). Stop.
- If Outcome is 'TicketCreated:{ticket_id}': Retrieve ticket_id. Proceed to Content Processing (Section 10) -> Log Success (Section 11) -> Trigger Deletion (Section 11). Stop.
- If Outcome is 'ProcessingFailed:{error}': Proceed to Failure Handling (Section 13). Stop.
- If Outcome is 'ProceedWithStandardEmailTriage' (or if email wasn't identified as an alert): Continue to Ticket Association (Section 7).
Ticket Association (Standard Triage Path): Check for existing ticket references. If high-confidence match found -> Proceed to Update Existing Ticket (Section 9). Else -> Proceed to Create New Ticket (Section 8).
New Ticket Creation (Standard Triage Path or Forced by CI Email): Match TicketTemplates or use Fallback Logic (Board, Classify, Agreement, Priority [incl. sentiment], link CIs [incl. dynamic extraction], search similar, tasks, internal KB suggest) -> Populate fields dynamically -> Call createTicket. Proceed to Content Processing (Section 10).
Update Existing Ticket: Retrieve matched_ticket_id. Proceed to Content Processing (Section 10).
Content Processing & Logging to Target: Applies if Ticket/Project/Problem/Change update occurred. Filter attachments -> Copy valid -> Create appropriate Update record (TicketUpdates, ProjectUpdates, etc., type 'EmailLog', link attachments, AI annotations English, original body). Set Tickets.requester_email if ticket.
Outcome Logging & Cleanup: Log final outcome to EmailProcessingLog. Update InboundEmailProcessingQueue ('Complete_Processed'/'Complete_Discarded'). Trigger deletion of temporary raw email data.
Cost Logging: Log accumulated AI cost for triage to ExpenseEntries (non-billable, linked to ticket if applicable).
Failure Handling: If unrecoverable error -> Update queue ('Failed_Processing' + reason) -> Log failure to EmailProcessingLog. Do NOT delete raw data. Requires separate review/retry process.

3. Email Reception & Initial Handling

Monitored Addresses: Includes addresses defined in ServiceBoards, AlertIngestionEndpoints, Projects, Problems, ChangeRequests, and CiEmailMappings.
Target Identification: System MUST identify target_entity_type and target_entity_id from the recipient address. Store in InboundEmailProcessingQueue. Handle 'Not Found'.
Temporary Staging: Raw email ingested into InboundEmailProcessingQueue (status 'Received'). Raw EML/attachments stored temporarily (object storage preferred).

4. Blocklist & Spam Filtering

Blocklist Check: Query EmailBlocklist (block_type = 'InboundSender'). If blocked: update queue (Failed_Blocklist), log (Blocked_Sender), trigger deletion. Stop.
Spam Check: Use integrated filter. If spam: update queue (Failed_Spam), log (Discarded_Spam), trigger deletion. Stop.
Proceed: Update queue status to 'Processing'.

5. Sender Identification (Org & Contact/User)

Goal: Link email to OrgID and ContactID/UserID. Performed unless skipped/handled by subsequent logic.
Process: Use tools & NLU (Direct email match, Domain lookup (OrganizationDomains), Body/Signature parsing for names/identifiers). Assign confidence. Handle low confidence / unidentified via Failure Handling (Section 13).

6. Alert Identification & Hand-off to Global Engine

Trigger: Executes for emails targeting 'ServiceBoard' or 'AlertEndpoint' (unless configured otherwise).
Process:
1. Identify Alert: Use heuristics (sender, subject, keywords, target address) to determine if email represents a processable alert.
2. If Potential Alert:
  - Parse Data: Extract key identifiers, Severity, Status, message content. Create structured alert data.
  - Call Global Engine: Pass structured data to CommandIT Global Alert Processing Engine [See Global Alert Processing Engine Documentation].
  - Receive Outcome: Await status: 'Ignored', 'TicketCreated:{ticket_id}', 'ProcessingFailed:{error}', 'ProceedWithStandardEmailTriage'.
3. If Not Potential Alert: Proceed directly to standard triage (Section 7).
Action Based on Outcome:
- 'Ignored': Log 'Discarded_Rule' -> Trigger Deletion (Section 11). Stop.
- 'TicketCreated:{ticket_id}': Store ticket_id. Proceed to Content Processing (Section 10) -> Log ('Processed_UpdatedTicket'/'NewTicket_AlertEngine') -> Trigger Deletion. Stop.
- 'ProcessingFailed:{error}': Proceed to Failure Handling (Section 13), logging engine's error. Stop.
- 'ProceedWithStandardEmailTriage': Continue to Section 7.

7. Ticket Association (Standard Triage Path)

Trigger: Reached if email targets Board/Alert Endpoint AND Global Alert Engine outcome is 'ProceedWithStandardEmailTriage'.
Process: Check explicit refs; Check sender history; Check CI history. Use content matching. Assign confidence.
Decision: High-confidence match -> Update Existing Ticket (Section 9). Else -> Create New Ticket (Section 8).

8. New Ticket Creation (Standard Triage Path or Forced by CI Email)

Trigger: No existing ticket match (from Section 7) OR forced by CI-targeted email (from Section 5) OR triggered by Alert Rule via Global Engine.
Process:
1. Template: Use template specified by Alert Rule action_parameters (if applicable) OR attempt best match via NLU OR use board/CI default.
2. Fallback (If no template): Determine Classification, Agreement, Priority (incl. sentiment, potentially rule override), search similar, analyze next steps.
3. Dynamic Field Population & CI Linking: Parse email -> Extract entities -> Populate standard/custom fields, Tickets.form_answers. Link relevant CIs via TicketAffectedCIs (ensure CI from triggering email or rule context is linked).
4. Task Creation: Generate initial TicketTasks based on analysis/template.
5. KB Suggestion (Fallback): If no template, add KB links to internal notes.
6. Ticket Save: Call createTicket (using potential overrides from rule parameters). Store created_ticket_id.
7. Proceed to Content Processing (Section 10).

9. Update Existing Ticket

Trigger: High-confidence match found (from Section 7) OR determined by Global Alert Engine ('UpdateExistingCI' action outcome passed back, implies Ticket ID found).
Action: Retrieve matched_ticket_id. Proceed to Content Processing (Section 10) targeting this ticket.

10. Content Processing & Logging to Target

Applies if: Ticket created/updated, Project/Problem/Change update created.
Attachment Handling: Filter junk. Copy valid to Attachments. Link via appropriate ...UpdateAttachments table.
Content Logging: Create appropriate Update record (TicketUpdates, ProjectUpdates, etc.). Set note_type = 'EmailLog'. Set AI user_id. Format body (AI annotations English, preserve original body language). Link attachments.
Ticket Specific: Set Tickets.requester_email.

11. Outcome Logging & Cleanup

Log Final Status: Record final outcome in EmailProcessingLog linking relevant IDs. Use appropriate status value reflecting the outcome (e.g., 'Processed_NewTicket', 'Processed_UpdatedTicket', 'Processed_ProjectUpdate', 'Discarded_Rule', 'Processed_AlertCleared', 'Processed_NewAlertLogged', 'Processed_AlertUpdated').
Update Queue: Update InboundEmailProcessingQueue status ('Complete_Processed'/'Complete_Discarded'). Link log/update IDs.
Trigger Deletion: Initiate deletion of the queue record AND associated temporary raw email data.

12. Cost Logging

If processed successfully and related to a ticket, call addExpenseEntry to log accumulated AI cost as a non-billable expense against the ticket (ExpenseEntries table).

13. Failure Handling

If unrecoverable error in this agent's process OR received 'ProcessingFailed' from Global Alert Engine:
- Update InboundEmailProcessingQueue: set processing_status = 'Failed_Processing', increment retry_count, set last_attempt_at, store error details in status_reason.
- Log failure to EmailProcessingLog with error details.
- Do NOT delete temporary raw data.
- Requires separate monitoring/alerting/review process for 'Failed_Processing' queue.

14. Blocking Lists Definition

Requires EmailBlocklist table. Requires UI/API for management. Outbound service must check.

15. Additional Considerations

Confidence Scoring & Human Review: Define thresholds for Sender ID/Ticket Association in standard triage; implement review queue workflow for these and Failed_Processing queue.
Language Detection: Implement early.
OOO/Auto-Reply Handling: Implement detection.
Loop Prevention: Basic checks.
AI Permissions: Scope data access.
Feedback Loop: Mechanism for flagging incorrect triage.

16. Areas for Further Definition

Specific Spam filtering mechanism.
Detailed NLU models/prompts/logic (Sender ID, Ticket Match, Classification, Sentiment, Entity Extraction, Task Gen).
Confidence scoring implementation and thresholds for standard triage.
Human review queue design/workflow (for standard triage failures & Failed_Processing queue).
Interface/API contract with the CommandIT Global Alert Processing Engine.
Detailed definition of alert signature parsing/generation.
Alert Policy assignment mechanism details (Hierarchy lookup assumed, confirm).
Detailed error handling/retry strategy for Failed_Processing queue.
Temporary attachment storage/deletion mechanism specifics.
UI/API for on-demand email address generation (populating CiEmailMappings, Projects, etc.).
Final list of CI types eligible for dedicated email addresses via CiEmailMappings.
Language Detection specifics.
LLM/translation services needed.
Method for reliably capturing LLM/AI costs for triage.
Definition of expenseType values/currency/pricing source for cost tracking.
Error handling strategy for cost logging.
AI training/fine-tuning strategy for email processing.