Skip to content
Kumiko

inbound-mail-foundation

Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the inboundMailProvider extension point with verify/fetch and optional oauth/watch (live push) and send. sendMailFromAccount(ctx, { accountId, message }) sends from a connected mailbox through its provider (From = the mailbox address, no fallback to the app sender) and answers typed failures (not configured, login rejected, server unreachable, rejected, invalid message); app write handlers call it, it is no endpoint of its own. The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections read_mail_accounts/read_inbound_messages/read_mail_threads; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire createInboundMailConnectRoutes (OAuth connect + anonymous callback outside /api) and createInboundMailSupervisor (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume inbound-mail-foundation:event:inbound-message-received from app features to attach business processes.

How it fits

Section titled “How it fits”

What this feature needs to run (Requires, top) and the write commands this feature provides (Provides, bottom).

flowchart TB
  n_inbound_mail_foundation["inbound-mail-foundation"]
  subgraph how_reqs["Requires"]
    n_tenant_lifecycle["tenant-lifecycle"]
  end
  subgraph how_provides["Provides"]
    n_cmd_inbound_mail_foundation_write_acknowledge_quarantine(["acknowledge-quarantine"])
    n_cmd_inbound_mail_foundation_write_attach_message_content(["attach-message-content"])
    n_cmd_inbound_mail_foundation_write_connect_account(["connect-account"])
    n_cmd_inbound_mail_foundation_write_disconnect_account(["disconnect-account"])
    n_cmd_inbound_mail_foundation_write_ingest_message(["ingest-message"])
    n_cmd_inbound_mail_foundation_write_mark_credential_stored(["mark-credential-stored"])
    n_cmd_more(["+4 more"])
  end
  n_tenant_lifecycle --> n_inbound_mail_foundation
  n_inbound_mail_foundation --> n_cmd_inbound_mail_foundation_write_acknowledge_quarantine
  n_inbound_mail_foundation --> n_cmd_inbound_mail_foundation_write_attach_message_content
  n_inbound_mail_foundation --> n_cmd_inbound_mail_foundation_write_connect_account
  n_inbound_mail_foundation --> n_cmd_inbound_mail_foundation_write_disconnect_account
  n_inbound_mail_foundation --> n_cmd_inbound_mail_foundation_write_ingest_message
  n_inbound_mail_foundation --> n_cmd_inbound_mail_foundation_write_mark_credential_stored
  n_inbound_mail_foundation --> n_cmd_more

Provides — write commands this feature registers (dispatch them through the command bus):

Dependencies

Section titled “Dependencies”

Extensions & cross-feature APIs

Section titled “Extensions & cross-feature APIs”
  • Registers extension: tenantData → mail-account, tenantData → inbound-message, tenantData → mail-thread