Introduction
AECS — the AI Email Consumption Specification — defines NormalizedEmail: a
standard structure for representing a parsed email message in a form suitable for
AI/LLM consumption, database storage, and conversation threading. It focuses
exclusively on how a single message should be structured after normalization;
transport, authentication, mailbox management, and platform integration are out of
scope.
Raw email is noisy: quoted reply chains, HTML markup, MIME multipart boundaries,
base64-encoded content, and legacy header formats. AECS-1 turns that into a
predictable JSON shape with six content levels — from byte-faithful rawFull down
to forAI, a cleaned, bounded string meant to go straight into an LLM prompt.
The two open specifications
| Spec | Status | Scope |
|---|---|---|
| AECS-1 | 1.0.0 Final | The NormalizedEmail schema, the threading algorithm, and the timestamp rules. |
| AECS-SDK-1 | 0.3.0-draft | The full target TypeScript SDK surface — parsing, storage, sending, AI tools, compose, rules. Only part of it is built today; see below. |
Both specs are published as CC0 1.0 (public domain) — implement them in any language, no license required, no attribution needed.
The packages
| Package | License | What it does |
|---|---|---|
@mvrx/mail |
AGPL-3.0-only | The AECS-1 reference implementation: parse(), deterministic threading, content levels, EmailThread, and prompt wrappers. |
@mvrx/wbxml |
MIT | A zero-dependency WBXML parser/encoder for Exchange ActiveSync 14.1 — unrelated to AECS-1 itself, but part of the same monorepo. |
What’s implemented today
@mvrx/mail’s core parser is implemented and conformance-tested: parse(),
the full NormalizedEmail schema, AECS-1 deterministic threadId resolution, UTC
timestamp normalization, all six content levels, lazy attachment metadata,
EmailThread.from(), and the three built-in forAI wrappers (xml, markdown,
block).
The AECS-SDK-1 specification also describes a much larger roadmap — D1/R2 storage helpers, outbound sending, AI provider connectors, AI-powered analysis and compose tools, attachment processors, a rules engine, and a real-time hub. None of that is implemented yet. Every roadmap page in these docs is labeled Roadmap so it’s never confused with shipped API surface.
Where to go next
- New to the SDK? Start with Getting started.
- Want the exact shape of
content.*? Read Content levels. - Need to understand
threadId? Read Threading. - Evaluating for a closed-source product? Read Licensing.