Inbound Email Processing

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 identify alert use heuristics (sender, subject, keywords, target address) to determine if email represents a processable alert 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' 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 template use template specified by alert rule action parameters (if applicable) or attempt best match via nlu or use board/ci default fallback (if no template) determine classification, agreement, priority (incl sentiment , potentially rule override), search similar, analyze next steps 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) task creation generate initial tickettasks based on analysis/template kb suggestion (fallback) if no template, add kb links to internal notes ticket save call createticket (using potential overrides from rule parameters) store created ticket id 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