@agenticmail/core 0.5.52 → 0.5.56

package/README.md

@@ -28,7 +28,7 @@ Every other AgenticMail package depends on this one.
 
 ## What This Package Does
 
-AgenticMail Core provides 15 major components organized into modules:
+AgenticMail Core provides 16 major components organized into modules:
 
 ### Agent Management
 - **AccountManager** — Creates, lists, finds, and deletes AI agent accounts. Each agent gets their own email address, login credentials, and a unique API key. Agent names must be email-safe (letters, numbers, dots, hyphens, underscores only).
@@ -58,6 +58,7 @@ AgenticMail Core provides 15 major components organized into modules:
 - **scanOutboundEmail** — Scans every outgoing email before it's sent, looking for sensitive data that an AI agent shouldn't be leaking. Detects API keys (AWS, OpenAI, GitHub, Stripe, and many more), passwords, private keys (SSH, PGP, RSA), personally identifiable information (Social Security numbers, credit card numbers, bank account numbers, passport numbers, dates of birth, driver's licenses), database connection strings, JWT tokens, cryptocurrency wallet addresses, webhook URLs, environment variable blocks, and more. Also checks attachment filenames for risky file types. If any high-severity match is found, the email is blocked. Emails between local agents (`@localhost` recipients) skip scanning entirely.
 - **sanitizeEmail** — Cleans up incoming email HTML to remove hidden content that could be used for prompt injection or phishing. Strips invisible Unicode characters (tag characters, zero-width joiners, bidirectional controls, soft hyphens), removes hidden HTML elements (display:none, visibility:hidden, font-size:0, white-on-white text, off-screen positioned elements, hidden iframes), removes script tags, strips data: and javascript: URIs, and removes suspicious HTML comments that contain words like "ignore", "system", "instruction", or "prompt". Returns both the cleaned content and a list of everything it found and removed.
 - **scoreEmail** — Scores incoming email for spam and threat indicators using 47 pattern-matching rules across 9 categories. Returns a numeric score (0-100), whether it's classified as spam (score 40+) or a warning (score 20-39), the top threat category, and a list of every rule that matched with its score contribution.
+- **classifyEmailRoute** — Assigns incoming mail a route class such as `ignore_spam`, `ignore_newsletter`, `archive_automated`, `project_update`, `deal_escalation`, or `agent_instruction`. The classification includes the suggested action, confidence, reason, and whether a human gate is required before downstream action.
 - **isInternalEmail** — Detects whether an email is from another local agent (agent-to-agent communication on `@localhost`). Importantly, it recognizes relay emails — if the "from" address is `@localhost` but the reply-to address is external, it's a forwarded relay email and should be treated as external, not internal.
 - **buildInboundSecurityAdvisory** — Analyzes incoming email attachments and spam matches to build a structured security advisory with risk levels (critical, high, medium) for attachments, double-extension detection (like `invoice.pdf.exe`), and link warnings.
 

package/dist/index.cjs

@@ -737,6 +737,7 @@ __export(index_exports, {
   TunnelManager: () => TunnelManager,
   WARNING_THRESHOLD: () => WARNING_THRESHOLD,
   buildInboundSecurityAdvisory: () => buildInboundSecurityAdvisory,
+  classifyEmailRoute: () => classifyEmailRoute,
   closeDatabase: () => closeDatabase,
   createTestDatabase: () => createTestDatabase,
   debug: () => debug,
@@ -1107,9 +1108,11 @@ var import_mailparser = require("mailparser");
 async function parseEmail(raw) {
   const parsed = await (0, import_mailparser.simpleParser)(raw);
   const xOriginalFrom = parsed.headers?.get("x-original-from");
+  const xAgenticMailRelay = parsed.headers?.get("x-agenticmail-relay");
   const originalFromAddr = typeof xOriginalFrom === "string" ? xOriginalFrom.trim() : void 0;
+  const isAgenticMailInboundRelay = xAgenticMailRelay === "inbound";
   let fromAddrs = parsed.from?.value ?? [];
-  if (originalFromAddr && fromAddrs.length > 0 && fromAddrs[0].address?.endsWith("@localhost")) {
+  if (originalFromAddr && fromAddrs.length > 0 && (isAgenticMailInboundRelay || fromAddrs[0].address?.endsWith("@localhost"))) {
     fromAddrs = [{ name: fromAddrs[0].name || "", address: originalFromAddr }];
   }
   const toAddrs = parsed.to ? Array.isArray(parsed.to) ? parsed.to.flatMap((t) => t.value) : parsed.to.value : [];
@@ -2238,6 +2241,178 @@ var AgentDeletionService = class {
 // src/index.ts
 init_spam_filter();
 
+// src/mail/route-classifier.ts
+var DEAL_TERMS = [
+  "contract",
+  "proposal",
+  "quote",
+  "pricing",
+  "price",
+  "budget",
+  "purchase order",
+  "invoice",
+  "deal",
+  "renewal",
+  "msa",
+  "sow",
+  "deadline",
+  "urgent",
+  "asap",
+  "time sensitive"
+];
+var INSTRUCTION_TERMS = [
+  "task",
+  "instruction",
+  "please",
+  "can you",
+  "could you",
+  "follow up",
+  "draft",
+  "reply",
+  "send",
+  "research",
+  "summarize",
+  "investigate",
+  "action item",
+  "todo"
+];
+var AUTOMATION_SUBJECT_TERMS = [
+  "receipt",
+  "notification",
+  "alert",
+  "build",
+  "deployment",
+  "backup",
+  "statement",
+  "verification code",
+  "security code",
+  "login code"
+];
+function normalize(value) {
+  return (value ?? "").toLowerCase();
+}
+function textFor(email) {
+  return `${email.subject ?? ""}
+${email.text ?? ""}
+${email.html ?? ""}`.toLowerCase();
+}
+function firstAddress(email) {
+  return normalize(email.from[0]?.address);
+}
+function header(email, name) {
+  const wanted = name.toLowerCase();
+  for (const [key, value] of email.headers) {
+    if (key.toLowerCase() === wanted) return normalize(value);
+  }
+  return "";
+}
+function localPart(address) {
+  return address.split("@")[0] ?? "";
+}
+function containsAny(text, terms) {
+  return terms.some((term) => text.includes(term));
+}
+function accountPolicy(account) {
+  const metadata = account?.metadata ?? {};
+  const value = metadata.emailRoutePolicy ?? metadata.routePolicy ?? metadata.mailboxPolicy;
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+function isInternalAddress(address) {
+  return address.endsWith("@localhost");
+}
+function isNewsletter(email) {
+  const from = firstAddress(email);
+  const subjectAndBody = textFor(email);
+  return Boolean(
+    header(email, "list-unsubscribe") || header(email, "list-id") || header(email, "x-campaign-id") || header(email, "x-mailchimp-campaign") || header(email, "precedence") === "list" || localPart(from).includes("newsletter") || subjectAndBody.includes("unsubscribe") || subjectAndBody.includes("newsletter") || subjectAndBody.includes("weekly digest")
+  );
+}
+function isAutomated(email) {
+  const from = firstAddress(email);
+  const subject = normalize(email.subject);
+  const precedence = header(email, "precedence");
+  const autoSubmitted = header(email, "auto-submitted");
+  return Boolean(
+    autoSubmitted && autoSubmitted !== "no" || precedence === "bulk" || precedence === "auto" || localPart(from).includes("no-reply") || localPart(from).includes("noreply") || localPart(from).includes("donotreply") || containsAny(subject, AUTOMATION_SUBJECT_TERMS)
+  );
+}
+function classifyEmailRoute(input) {
+  const { email, spam, account } = input;
+  const policy = accountPolicy(account);
+  const from = firstAddress(email);
+  const allText = textFor(email);
+  if (spam?.isSpam) {
+    return {
+      routeClass: "ignore_spam",
+      action: "ignore",
+      gateRequired: false,
+      confidence: "high",
+      reason: `Spam score ${spam.score} exceeded the spam threshold`
+    };
+  }
+  if (policy === "human" || policy === "private") {
+    return {
+      routeClass: "human_private",
+      action: "notify",
+      gateRequired: true,
+      confidence: "high",
+      reason: "Account policy marks this mailbox as human/private"
+    };
+  }
+  if (isNewsletter(email)) {
+    return {
+      routeClass: "ignore_newsletter",
+      action: "ignore",
+      gateRequired: false,
+      confidence: "high",
+      reason: "Newsletter headers or unsubscribe signals were detected"
+    };
+  }
+  if (isAutomated(email) && !containsAny(allText, DEAL_TERMS)) {
+    return {
+      routeClass: "archive_automated",
+      action: "archive",
+      gateRequired: false,
+      confidence: "medium",
+      reason: "Automated sender or notification pattern detected"
+    };
+  }
+  if ((policy === "agent" || isInternalAddress(from)) && containsAny(allText, INSTRUCTION_TERMS)) {
+    return {
+      routeClass: "agent_instruction",
+      action: "create_task",
+      gateRequired: true,
+      confidence: isInternalAddress(from) ? "high" : "medium",
+      reason: "Instruction-like content for an agent mailbox was detected"
+    };
+  }
+  if (containsAny(allText, DEAL_TERMS)) {
+    return {
+      routeClass: "deal_escalation",
+      action: "escalate",
+      gateRequired: true,
+      confidence: "medium",
+      reason: "Commercial, deadline, or negotiation language was detected"
+    };
+  }
+  if (spam?.isWarning) {
+    return {
+      routeClass: "project_update",
+      action: "notify",
+      gateRequired: true,
+      confidence: "low",
+      reason: `Spam warning category ${spam.topCategory ?? "unknown"} requires cautious handling`
+    };
+  }
+  return {
+    routeClass: "project_update",
+    action: "notify",
+    gateRequired: false,
+    confidence: "low",
+    reason: "Default route for non-spam, non-automated email"
+  };
+}
+
 // src/mail/sanitizer.ts
 var RE_TAG_BLOCK = /[\u{E0001}-\u{E007F}]/gu;
 var RE_ZERO_WIDTH = /[\u200B\u200C\u200D\uFEFF]/g;
@@ -3541,9 +3716,9 @@ var RelayGateway = class {
       throw new Error("Relay not configured. Call setup() first.");
     }
     const atIdx = this.config.email.lastIndexOf("@");
-    const localPart = this.config.email.slice(0, atIdx);
+    const localPart2 = this.config.email.slice(0, atIdx);
     const domain = this.config.email.slice(atIdx + 1);
-    const relayFrom = `${localPart}+${agentName}@${domain}`;
+    const relayFrom = `${localPart2}+${agentName}@${domain}`;
     const displayName = mail.fromName || agentName;
     const mailOpts = {
       from: `${displayName} <${relayFrom}>`,
@@ -3555,7 +3730,7 @@ var RelayGateway = class {
       html: mail.html,
       replyTo: relayFrom,
       inReplyTo: mail.inReplyTo,
-      references: mail.references?.join(" "),
+      references: Array.isArray(mail.references) ? mail.references.join(" ") : mail.references,
       headers: mail.headers,
       attachments: mail.attachments?.map((a) => ({
         filename: a.filename,
@@ -3779,9 +3954,9 @@ var RelayGateway = class {
   isOurRelaySender(address) {
     if (!this.config) return false;
     const atIdx = this.config.email.lastIndexOf("@");
-    const localPart = this.config.email.slice(0, atIdx);
+    const localPart2 = this.config.email.slice(0, atIdx);
     const domain = this.config.email.slice(atIdx + 1);
-    const pattern = new RegExp(`^${escapeRegex(localPart)}\\+[^@]+@${escapeRegex(domain)}$`, "i");
+    const pattern = new RegExp(`^${escapeRegex(localPart2)}\\+[^@]+@${escapeRegex(domain)}$`, "i");
     return pattern.test(address);
   }
   /**
@@ -3821,8 +3996,8 @@ var RelayGateway = class {
       const match = addr.match(/^([^+]+)\+([^@]+)@/);
       if (match && this.config) {
         const atIdx = this.config.email.lastIndexOf("@");
-        const localPart = this.config.email.slice(0, atIdx);
-        if (match[1].toLowerCase() === localPart.toLowerCase()) {
+        const localPart2 = this.config.email.slice(0, atIdx);
+        if (match[1].toLowerCase() === localPart2.toLowerCase()) {
           return match[2];
         }
       }
@@ -4363,9 +4538,9 @@ var DNSConfigurator = class {
     const records = [];
     const removed = [];
     const existing = await this.cf.listDnsRecords(zoneId);
-    const normalize = (s) => s.replace(/^["']|["']$/g, "");
+    const normalize2 = (s) => s.replace(/^["']|["']$/g, "");
     const findRecords = (type, name, contentPrefix) => existing.filter(
-      (r) => r.type === type && r.name === name && (!contentPrefix || normalize(r.content ?? "").startsWith(contentPrefix))
+      (r) => r.type === type && r.name === name && (!contentPrefix || normalize2(r.content ?? "").startsWith(contentPrefix))
     );
     const existingMx = findRecords("MX", domain);
     const cfEmailRoutingMx = existingMx.filter((r) => (r.content ?? "").startsWith("_dc-mx."));
@@ -4389,7 +4564,7 @@ var DNSConfigurator = class {
     const ipClause = serverIp ? `ip4:${serverIp} ` : "";
     const ourSpf = `v=spf1 ${ipClause}include:_spf.mx.cloudflare.net mx ~all`;
     const existingSpf = findRecords("TXT", domain, "v=spf1");
-    const alreadyHasOurSpf = existingSpf.some((r) => normalize(r.content) === ourSpf);
+    const alreadyHasOurSpf = existingSpf.some((r) => normalize2(r.content) === ourSpf);
     if (!alreadyHasOurSpf) {
       for (const spf of existingSpf) {
         await this.cf.deleteDnsRecord(zoneId, spf.id);
@@ -4420,7 +4595,7 @@ var DNSConfigurator = class {
       const dkimName = `${options.dkimSelector}._domainkey.${domain}`;
       const ourDkim = `v=DKIM1; k=rsa; p=${options.dkimPublicKey}`;
       const existingDkim = findRecords("TXT", dkimName, "v=DKIM1");
-      const alreadyCorrect = existingDkim.some((r) => normalize(r.content) === ourDkim);
+      const alreadyCorrect = existingDkim.some((r) => normalize2(r.content) === ourDkim);
       if (!alreadyCorrect) {
         for (const rec of existingDkim) {
           await this.cf.deleteDnsRecord(zoneId, rec.id);
@@ -5262,7 +5437,7 @@ var GatewayManager = class {
         html: mail.html || void 0,
         replyTo: mail.from,
         inReplyTo: mail.inReplyTo,
-        references: mail.references?.join(" "),
+        references: Array.isArray(mail.references) ? mail.references.join(" ") : mail.references,
         headers: {
           "X-AgenticMail-Relay": "inbound",
           "X-Original-From": mail.from,
@@ -5744,12 +5919,14 @@ var GatewayManager = class {
     const mailOpts = {
       from,
       to: recipients.join(", "),
+      cc: mail.cc ? Array.isArray(mail.cc) ? mail.cc.join(", ") : mail.cc : void 0,
+      bcc: mail.bcc ? Array.isArray(mail.bcc) ? mail.bcc.join(", ") : mail.bcc : void 0,
       subject: mail.subject,
       text: mail.text || void 0,
       html: mail.html || void 0,
       replyTo: mail.replyTo || from,
       inReplyTo: mail.inReplyTo || void 0,
-      references: mail.references?.join(" ") || void 0,
+      references: Array.isArray(mail.references) ? mail.references.join(" ") : mail.references || void 0,
       headers: {
         "X-Mailer": "AgenticMail/1.0"
       },
@@ -7411,7 +7588,14 @@ IMAP_PORT=143
     const composePath = (0, import_node_path8.join)(dataDir, "docker-compose.yml");
     (0, import_node_fs7.writeFileSync)(composePath, `services:
   stalwart:
-    image: stalwartlabs/stalwart:latest
+    # Pinned to v0.15.5 \u2014 Stalwart 0.16+ moved its config to JSON
+    # at /etc/stalwart/config.json (hardcoded into the container
+    # CMD), runs as UID 2000, and silently ignores our pre-0.10
+    # TOML mount. On those builds Stalwart enters bootstrap mode
+    # and the setup wizard 404s on the admin API. Pinning until
+    # the templates are migrated to the 0.16+ JSON layout.
+    # Tracking: https://github.com/agenticmail/agenticmail/issues/10
+    image: stalwartlabs/stalwart:v0.15.5
     container_name: agenticmail-stalwart
     ports:
       - "127.0.0.1:8080:8080"   # HTTP Admin + JMAP (localhost only)
@@ -7524,6 +7708,7 @@ secret = "${password}"
   TunnelManager,
   WARNING_THRESHOLD,
   buildInboundSecurityAdvisory,
+  classifyEmailRoute,
   closeDatabase,
   createTestDatabase,
   debug,

package/dist/index.d.cts

@@ -507,6 +507,28 @@ declare const WARNING_THRESHOLD = 20;
 declare function isInternalEmail(email: ParsedEmail, localDomains?: string[]): boolean;
 declare function scoreEmail(email: ParsedEmail): SpamResult;
 
+type EmailRouteClass = 'ignore_spam' | 'ignore_newsletter' | 'archive_automated' | 'project_update' | 'deal_escalation' | 'agent_instruction' | 'human_private';
+type EmailRouteAction = 'ignore' | 'archive' | 'notify' | 'escalate' | 'create_task' | 'draft_reply';
+interface EmailRouteAccountContext {
+    name?: string;
+    email?: string;
+    role?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EmailRouteInput {
+    email: ParsedEmail;
+    spam?: Pick<SpamResult, 'score' | 'isSpam' | 'isWarning' | 'topCategory'>;
+    account?: EmailRouteAccountContext;
+}
+interface EmailRouteClassification {
+    routeClass: EmailRouteClass;
+    action: EmailRouteAction;
+    gateRequired: boolean;
+    confidence: 'low' | 'medium' | 'high';
+    reason: string;
+}
+declare function classifyEmailRoute(input: EmailRouteInput): EmailRouteClassification;
+
 interface SanitizeDetection {
     type: string;
     description: string;
@@ -1673,4 +1695,4 @@ declare class SetupManager {
     isInitialized(): boolean;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge };
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge };

package/dist/index.d.ts

@@ -507,6 +507,28 @@ declare const WARNING_THRESHOLD = 20;
 declare function isInternalEmail(email: ParsedEmail, localDomains?: string[]): boolean;
 declare function scoreEmail(email: ParsedEmail): SpamResult;
 
+type EmailRouteClass = 'ignore_spam' | 'ignore_newsletter' | 'archive_automated' | 'project_update' | 'deal_escalation' | 'agent_instruction' | 'human_private';
+type EmailRouteAction = 'ignore' | 'archive' | 'notify' | 'escalate' | 'create_task' | 'draft_reply';
+interface EmailRouteAccountContext {
+    name?: string;
+    email?: string;
+    role?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EmailRouteInput {
+    email: ParsedEmail;
+    spam?: Pick<SpamResult, 'score' | 'isSpam' | 'isWarning' | 'topCategory'>;
+    account?: EmailRouteAccountContext;
+}
+interface EmailRouteClassification {
+    routeClass: EmailRouteClass;
+    action: EmailRouteAction;
+    gateRequired: boolean;
+    confidence: 'low' | 'medium' | 'high';
+    reason: string;
+}
+declare function classifyEmailRoute(input: EmailRouteInput): EmailRouteClassification;
+
 interface SanitizeDetection {
     type: string;
     description: string;
@@ -1673,4 +1695,4 @@ declare class SetupManager {
     isInitialized(): boolean;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge };
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge };

package/dist/index.js

@@ -354,9 +354,11 @@ import { simpleParser } from "mailparser";
 async function parseEmail(raw) {
   const parsed = await simpleParser(raw);
   const xOriginalFrom = parsed.headers?.get("x-original-from");
+  const xAgenticMailRelay = parsed.headers?.get("x-agenticmail-relay");
   const originalFromAddr = typeof xOriginalFrom === "string" ? xOriginalFrom.trim() : void 0;
+  const isAgenticMailInboundRelay = xAgenticMailRelay === "inbound";
   let fromAddrs = parsed.from?.value ?? [];
-  if (originalFromAddr && fromAddrs.length > 0 && fromAddrs[0].address?.endsWith("@localhost")) {
+  if (originalFromAddr && fromAddrs.length > 0 && (isAgenticMailInboundRelay || fromAddrs[0].address?.endsWith("@localhost"))) {
     fromAddrs = [{ name: fromAddrs[0].name || "", address: originalFromAddr }];
   }
   const toAddrs = parsed.to ? Array.isArray(parsed.to) ? parsed.to.flatMap((t) => t.value) : parsed.to.value : [];
@@ -1482,6 +1484,178 @@ var AgentDeletionService = class {
   }
 };
 
+// src/mail/route-classifier.ts
+var DEAL_TERMS = [
+  "contract",
+  "proposal",
+  "quote",
+  "pricing",
+  "price",
+  "budget",
+  "purchase order",
+  "invoice",
+  "deal",
+  "renewal",
+  "msa",
+  "sow",
+  "deadline",
+  "urgent",
+  "asap",
+  "time sensitive"
+];
+var INSTRUCTION_TERMS = [
+  "task",
+  "instruction",
+  "please",
+  "can you",
+  "could you",
+  "follow up",
+  "draft",
+  "reply",
+  "send",
+  "research",
+  "summarize",
+  "investigate",
+  "action item",
+  "todo"
+];
+var AUTOMATION_SUBJECT_TERMS = [
+  "receipt",
+  "notification",
+  "alert",
+  "build",
+  "deployment",
+  "backup",
+  "statement",
+  "verification code",
+  "security code",
+  "login code"
+];
+function normalize(value) {
+  return (value ?? "").toLowerCase();
+}
+function textFor(email) {
+  return `${email.subject ?? ""}
+${email.text ?? ""}
+${email.html ?? ""}`.toLowerCase();
+}
+function firstAddress(email) {
+  return normalize(email.from[0]?.address);
+}
+function header(email, name) {
+  const wanted = name.toLowerCase();
+  for (const [key, value] of email.headers) {
+    if (key.toLowerCase() === wanted) return normalize(value);
+  }
+  return "";
+}
+function localPart(address) {
+  return address.split("@")[0] ?? "";
+}
+function containsAny(text, terms) {
+  return terms.some((term) => text.includes(term));
+}
+function accountPolicy(account) {
+  const metadata = account?.metadata ?? {};
+  const value = metadata.emailRoutePolicy ?? metadata.routePolicy ?? metadata.mailboxPolicy;
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+function isInternalAddress(address) {
+  return address.endsWith("@localhost");
+}
+function isNewsletter(email) {
+  const from = firstAddress(email);
+  const subjectAndBody = textFor(email);
+  return Boolean(
+    header(email, "list-unsubscribe") || header(email, "list-id") || header(email, "x-campaign-id") || header(email, "x-mailchimp-campaign") || header(email, "precedence") === "list" || localPart(from).includes("newsletter") || subjectAndBody.includes("unsubscribe") || subjectAndBody.includes("newsletter") || subjectAndBody.includes("weekly digest")
+  );
+}
+function isAutomated(email) {
+  const from = firstAddress(email);
+  const subject = normalize(email.subject);
+  const precedence = header(email, "precedence");
+  const autoSubmitted = header(email, "auto-submitted");
+  return Boolean(
+    autoSubmitted && autoSubmitted !== "no" || precedence === "bulk" || precedence === "auto" || localPart(from).includes("no-reply") || localPart(from).includes("noreply") || localPart(from).includes("donotreply") || containsAny(subject, AUTOMATION_SUBJECT_TERMS)
+  );
+}
+function classifyEmailRoute(input) {
+  const { email, spam, account } = input;
+  const policy = accountPolicy(account);
+  const from = firstAddress(email);
+  const allText = textFor(email);
+  if (spam?.isSpam) {
+    return {
+      routeClass: "ignore_spam",
+      action: "ignore",
+      gateRequired: false,
+      confidence: "high",
+      reason: `Spam score ${spam.score} exceeded the spam threshold`
+    };
+  }
+  if (policy === "human" || policy === "private") {
+    return {
+      routeClass: "human_private",
+      action: "notify",
+      gateRequired: true,
+      confidence: "high",
+      reason: "Account policy marks this mailbox as human/private"
+    };
+  }
+  if (isNewsletter(email)) {
+    return {
+      routeClass: "ignore_newsletter",
+      action: "ignore",
+      gateRequired: false,
+      confidence: "high",
+      reason: "Newsletter headers or unsubscribe signals were detected"
+    };
+  }
+  if (isAutomated(email) && !containsAny(allText, DEAL_TERMS)) {
+    return {
+      routeClass: "archive_automated",
+      action: "archive",
+      gateRequired: false,
+      confidence: "medium",
+      reason: "Automated sender or notification pattern detected"
+    };
+  }
+  if ((policy === "agent" || isInternalAddress(from)) && containsAny(allText, INSTRUCTION_TERMS)) {
+    return {
+      routeClass: "agent_instruction",
+      action: "create_task",
+      gateRequired: true,
+      confidence: isInternalAddress(from) ? "high" : "medium",
+      reason: "Instruction-like content for an agent mailbox was detected"
+    };
+  }
+  if (containsAny(allText, DEAL_TERMS)) {
+    return {
+      routeClass: "deal_escalation",
+      action: "escalate",
+      gateRequired: true,
+      confidence: "medium",
+      reason: "Commercial, deadline, or negotiation language was detected"
+    };
+  }
+  if (spam?.isWarning) {
+    return {
+      routeClass: "project_update",
+      action: "notify",
+      gateRequired: true,
+      confidence: "low",
+      reason: `Spam warning category ${spam.topCategory ?? "unknown"} requires cautious handling`
+    };
+  }
+  return {
+    routeClass: "project_update",
+    action: "notify",
+    gateRequired: false,
+    confidence: "low",
+    reason: "Default route for non-spam, non-automated email"
+  };
+}
+
 // src/mail/sanitizer.ts
 var RE_TAG_BLOCK = /[\u{E0001}-\u{E007F}]/gu;
 var RE_ZERO_WIDTH = /[\u200B\u200C\u200D\uFEFF]/g;
@@ -2785,9 +2959,9 @@ var RelayGateway = class {
       throw new Error("Relay not configured. Call setup() first.");
     }
     const atIdx = this.config.email.lastIndexOf("@");
-    const localPart = this.config.email.slice(0, atIdx);
+    const localPart2 = this.config.email.slice(0, atIdx);
     const domain = this.config.email.slice(atIdx + 1);
-    const relayFrom = `${localPart}+${agentName}@${domain}`;
+    const relayFrom = `${localPart2}+${agentName}@${domain}`;
     const displayName = mail.fromName || agentName;
     const mailOpts = {
       from: `${displayName} <${relayFrom}>`,
@@ -2799,7 +2973,7 @@ var RelayGateway = class {
       html: mail.html,
       replyTo: relayFrom,
       inReplyTo: mail.inReplyTo,
-      references: mail.references?.join(" "),
+      references: Array.isArray(mail.references) ? mail.references.join(" ") : mail.references,
       headers: mail.headers,
       attachments: mail.attachments?.map((a) => ({
         filename: a.filename,
@@ -3023,9 +3197,9 @@ var RelayGateway = class {
   isOurRelaySender(address) {
     if (!this.config) return false;
     const atIdx = this.config.email.lastIndexOf("@");
-    const localPart = this.config.email.slice(0, atIdx);
+    const localPart2 = this.config.email.slice(0, atIdx);
     const domain = this.config.email.slice(atIdx + 1);
-    const pattern = new RegExp(`^${escapeRegex(localPart)}\\+[^@]+@${escapeRegex(domain)}$`, "i");
+    const pattern = new RegExp(`^${escapeRegex(localPart2)}\\+[^@]+@${escapeRegex(domain)}$`, "i");
     return pattern.test(address);
   }
   /**
@@ -3065,8 +3239,8 @@ var RelayGateway = class {
       const match = addr.match(/^([^+]+)\+([^@]+)@/);
       if (match && this.config) {
         const atIdx = this.config.email.lastIndexOf("@");
-        const localPart = this.config.email.slice(0, atIdx);
-        if (match[1].toLowerCase() === localPart.toLowerCase()) {
+        const localPart2 = this.config.email.slice(0, atIdx);
+        if (match[1].toLowerCase() === localPart2.toLowerCase()) {
           return match[2];
         }
       }
@@ -3607,9 +3781,9 @@ var DNSConfigurator = class {
     const records = [];
     const removed = [];
     const existing = await this.cf.listDnsRecords(zoneId);
-    const normalize = (s) => s.replace(/^["']|["']$/g, "");
+    const normalize2 = (s) => s.replace(/^["']|["']$/g, "");
     const findRecords = (type, name, contentPrefix) => existing.filter(
-      (r) => r.type === type && r.name === name && (!contentPrefix || normalize(r.content ?? "").startsWith(contentPrefix))
+      (r) => r.type === type && r.name === name && (!contentPrefix || normalize2(r.content ?? "").startsWith(contentPrefix))
     );
     const existingMx = findRecords("MX", domain);
     const cfEmailRoutingMx = existingMx.filter((r) => (r.content ?? "").startsWith("_dc-mx."));
@@ -3633,7 +3807,7 @@ var DNSConfigurator = class {
     const ipClause = serverIp ? `ip4:${serverIp} ` : "";
     const ourSpf = `v=spf1 ${ipClause}include:_spf.mx.cloudflare.net mx ~all`;
     const existingSpf = findRecords("TXT", domain, "v=spf1");
-    const alreadyHasOurSpf = existingSpf.some((r) => normalize(r.content) === ourSpf);
+    const alreadyHasOurSpf = existingSpf.some((r) => normalize2(r.content) === ourSpf);
     if (!alreadyHasOurSpf) {
       for (const spf of existingSpf) {
         await this.cf.deleteDnsRecord(zoneId, spf.id);
@@ -3664,7 +3838,7 @@ var DNSConfigurator = class {
       const dkimName = `${options.dkimSelector}._domainkey.${domain}`;
       const ourDkim = `v=DKIM1; k=rsa; p=${options.dkimPublicKey}`;
       const existingDkim = findRecords("TXT", dkimName, "v=DKIM1");
-      const alreadyCorrect = existingDkim.some((r) => normalize(r.content) === ourDkim);
+      const alreadyCorrect = existingDkim.some((r) => normalize2(r.content) === ourDkim);
       if (!alreadyCorrect) {
         for (const rec of existingDkim) {
           await this.cf.deleteDnsRecord(zoneId, rec.id);
@@ -4505,7 +4679,7 @@ var GatewayManager = class {
         html: mail.html || void 0,
         replyTo: mail.from,
         inReplyTo: mail.inReplyTo,
-        references: mail.references?.join(" "),
+        references: Array.isArray(mail.references) ? mail.references.join(" ") : mail.references,
         headers: {
           "X-AgenticMail-Relay": "inbound",
           "X-Original-From": mail.from,
@@ -4987,12 +5161,14 @@ var GatewayManager = class {
     const mailOpts = {
       from,
       to: recipients.join(", "),
+      cc: mail.cc ? Array.isArray(mail.cc) ? mail.cc.join(", ") : mail.cc : void 0,
+      bcc: mail.bcc ? Array.isArray(mail.bcc) ? mail.bcc.join(", ") : mail.bcc : void 0,
       subject: mail.subject,
       text: mail.text || void 0,
       html: mail.html || void 0,
       replyTo: mail.replyTo || from,
       inReplyTo: mail.inReplyTo || void 0,
-      references: mail.references?.join(" ") || void 0,
+      references: Array.isArray(mail.references) ? mail.references.join(" ") : mail.references || void 0,
       headers: {
         "X-Mailer": "AgenticMail/1.0"
       },
@@ -6654,7 +6830,14 @@ IMAP_PORT=143
     const composePath = join9(dataDir, "docker-compose.yml");
     writeFileSync5(composePath, `services:
   stalwart:
-    image: stalwartlabs/stalwart:latest
+    # Pinned to v0.15.5 \u2014 Stalwart 0.16+ moved its config to JSON
+    # at /etc/stalwart/config.json (hardcoded into the container
+    # CMD), runs as UID 2000, and silently ignores our pre-0.10
+    # TOML mount. On those builds Stalwart enters bootstrap mode
+    # and the setup wizard 404s on the admin API. Pinning until
+    # the templates are migrated to the 0.16+ JSON layout.
+    # Tracking: https://github.com/agenticmail/agenticmail/issues/10
+    image: stalwartlabs/stalwart:v0.15.5
     container_name: agenticmail-stalwart
     ports:
       - "127.0.0.1:8080:8080"   # HTTP Admin + JMAP (localhost only)
@@ -6766,6 +6949,7 @@ export {
   TunnelManager,
   WARNING_THRESHOLD,
   buildInboundSecurityAdvisory,
+  classifyEmailRoute,
   closeDatabase,
   createTestDatabase,
   debug,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.5.52",
+  "version": "0.5.56",
   "description": "Core SDK for AgenticMail — email, SMS, and phone number access for AI agents",
   "type": "module",
   "main": "dist/index.js",