Email Parsing API

Raw Email Is Noise

A typical email from Gmail or Outlook is 2,000+ lines of wire-format RFC 5322. MIME boundaries, base64-encoded attachments, folded headers across multiple lines, quoted-printable escape sequences. Feed that to an LLM and you're burning tokens on ARC-Seal: i=1; a=rsa-sha256; t=1775136695; cv=none; instead of the actual message.

AILANG Parse reads the RFC 5322 structure directly and outputs clean, typed blocks — the same format as DOCX, XLSX, and HTML parsing. Your pipeline handles email identically to every other format.

Raw .eml vs Structured Output

Delivered-To: user@company.com
Received: by 2002:ad4:5d67:0:b0:89c...
X-Received: by 2002:a53:c084:0:b0:650...
ARC-Seal: i=1; a=rsa-sha256; t=17751...
        d=google.com; s=arc-20240605;
        b=Htpf2+pNpdk7kEWo2yzUieUhVe...
         GUGJNZ20uHE4rPvnq0UW+8R1+v4...
ARC-Message-Signature: i=1; a=rsa-sha...
DKIM-Signature: v=1; a=rsa-sha256; ...
Content-Type: multipart/mixed;
  boundary="000000000000c91f7f064e77bbd9"

--000000000000c91f7f064e77bbd9
Content-Type: text/plain; charset="UTF-8"

Your monthly invoice is available.
...
--000000000000c91f7f064e77bbd9
Content-Type: application/pdf;
  name="5539333924.pdf"
Content-Transfer-Encoding: base64

JVBERi0xLjcKCjEgMCBvYmoKPDwgL1R5cG
UgL0NhdGFsb2cgL1BhZ2VzIDIgMCBSIC9N
YXJrSW5mbyA8PCAvTWFya2VkIHRydWUgPj
4gL1N0cnVjdFRyZWVSb290IDMgMCBSID4+
... (1,800+ more lines of base64)

{
  "metadata": {
    "title": "Your invoice is available",
    "author": "Google Payments",
    "created": "Thu, 02 Apr 2026 03:33:38 -0700"
  },
  "blocks": [
    {
      "type": "section",
      "kind": "email-headers",
      "blocks": [
        {"type": "text", "style": "email-header",
         "text": "From: Google Payments <payments-noreply@google.com>"},
        {"type": "text", "style": "email-header",
         "text": "To: user@company.com"},
        {"type": "text", "style": "email-header",
         "text": "Subject: Your invoice is available"}
      ]
    },
    {
      "type": "text",
      "style": "Normal",
      "text": "Your monthly invoice is available.
        Please find the PDF attached..."
    },
    {
      "type": "text",
      "style": "attachment",
      "text": "[attachment: 5539333924.pdf,
        application/pdf]"
    }
  ]
}

What Gets Extracted

Encoding Support

Real-world email uses three encoding layers. AILANG Parse handles all of them:

Multi-byte UTF-8 sequences spanning consecutive =XX pairs are accumulated and decoded together — accented characters (café, résumé, Zürich), CJK, and emoji all work correctly.

MBOX Archives

MBOX files (RFC 4155) contain multiple emails separated by From  envelope lines. AILANG Parse splits them into individual messages, each wrapped in a SectionBlock with kind mbox-message. Every message gets full header/body/attachment parsing.

This makes MBOX ideal for bulk email processing: export a Gmail label or Thunderbird folder as MBOX, parse it in one call, and get structured JSON for every message in the archive.

Attachment Chain Parsing

Emails are documents that contain other documents. A budget email has a CSV; a contract email has HTML or a forwarded .eml. AILANG Parse decodes and parses text-based attachments inline — one API call extracts the email and its attachment content.

Supported inline formats: CSV, TSV, HTML, Markdown, plain text, and nested EML (message/rfc822). With the --deep flag, PDF, DOCX, PPTX, and XLSX attachments are also extracted and parsed. Image attachments are identified by filename and MIME type.

{
  "type": "section",
  "kind": "attachment",
  "blocks": [
    {"type": "text", "style": "attachment-meta",
     "text": "revenue_q1.csv (text/csv)"},
    {"type": "table",
     "headers": [{"text": "Region"}, {"text": "Revenue"}, {"text": "Target"}],
     "rows": [
       [{"text": "EMEA"}, {"text": "125000"}, {"text": "110000"}],
       [{"text": "APAC"}, {"text": "143000"}, {"text": "130000"}]
     ]}
  ]
}

With --deep, PDF and Office attachments get the same treatment — a DOCX attachment is decoded, extracted, and parsed into paragraphs and tables:

# Parse email + resolve Office attachments
ailang run --entry main --caps IO,FS,Env \
  docparse/main.ail invoice-email.eml --deep

{
  "type": "section",
  "kind": "attachment",
  "blocks": [
    {"type": "text", "style": "attachment-meta",
     "text": "q1_revenue.docx (application/vnd...wordprocessingml.document)"},
    {"type": "text", "text": "Q1 Revenue Analysis", "style": "Normal"},
    {"type": "table",
     "headers": ["Region", "Revenue"],
     "rows": [["EMEA", "$125,000"], ["APAC", "$143,000"], ["Americas", "$157,000"]]}
  ]
}

PDF Attachments — With Automatic OCR

PDF attachments resolve through a backend ladder that escalates only when it has to. pdftotext runs first: free, roughly instant, and correct for any born-digital PDF. If it comes back empty — the signature of a scanned or photographed document — the parser escalates to docling, a local OCR pass.

Both automatic tiers are free, which is why escalation needs no permission. The ai backend costs money, so it is never entered on your behalf — a parser that silently spends is the wrong default. An explicit --pdf-backend choice is always respected rather than overridden.

An unreadable attachment never aborts the run. One bad file in a mailbox is not a reason to abandon the message — or, in batch mode, the remaining files.

Forwarded emails (message/rfc822 attachments) are parsed recursively — the inner email gets full header and body extraction, nested inside the attachment block.

Thread Reconstruction

Individual emails are often unintelligible without their thread. AILANG Parse reconstructs conversation threads from MBOX archives using Message-ID, In-Reply-To, and References headers.

# Threaded mode: groups messages into conversations
ailang run --entry main --caps IO,FS,Env \
  docparse/main.ail archive.mbox --threaded

Output: each thread becomes a SectionBlock with kind thread, containing the normalized subject, participant list, and chronologically-ordered messages with quoted text stripped.

{
  "type": "section",
  "kind": "thread",
  "blocks": [
    {"type": "text", "style": "thread-subject", "text": "Q2 Budget Planning"},
    {"type": "text", "style": "thread-participants", "text": "Alice, Bob, Carol"},
    {"type": "section", "kind": "thread-message", "blocks": [...]},
    {"type": "section", "kind": "thread-message", "blocks": [...]},
    {"type": "section", "kind": "thread-message", "blocks": [...]}
  ]
}

Thread reconstruction gives LLMs the full conversation context for summarization, triage, or automated response — without the noise of repeated quoted text.

Use Cases

Emails are documents that contain other documents. Structured parsing makes them composable with the rest of your data pipeline.

Example: GitHub Notification

A real GitHub Actions notification email (48 KB, multipart/alternative with DKIM/ARC/SPF headers):

{
  "metadata": {
    "title": "[sunholo-data/ailang] Run failed: Build and Release - dev",
    "author": "\"Voight-Kampff (bot)\"",
    "created": "Thu, 02 Apr 2026 06:31:33 -0700"
  },
  "blocks": [
    {
      "type": "section",
      "kind": "email-headers",
      "blocks": [
        {"type": "text", "style": "email-header",
         "text": "From: \"Voight-Kampff (bot)\" <notifications@github.com>"},
        {"type": "text", "style": "email-header",
         "text": "Subject: [sunholo-data/ailang] Run failed: Build and Release - dev"},
        {"type": "text", "style": "email-header",
         "text": "X-Github-Reason: ci_activity"}
      ]
    },
    {
      "type": "text",
      "style": "Normal",
      "text": "Repository: sunholo-data/ailang\nWorkflow: Build and Release\nDuration: 5 minutes and 50.0 seconds\n\nJobs:\n  * Build ubuntu-latest succeeded\n  * Build windows-latest failed (2 annotations)\n  * Create Release Bundle skipped"
    }
  ]
}

28 raw headers (DKIM chains, ARC seals, SPF results) reduced to the headers that matter. The body is clean text, ready for an LLM to reason about build failures.

Try It

CLI

# Parse an EML email file
ailang run --entry main --caps IO,FS,Env \
  ~/.ailang/cache/registry/sunholo/ailang_parse/*/docparse/main.ail inbox.eml

# Parse an MBOX archive (multiple messages)
ailang run --entry main --caps IO,FS,Env \
  ~/.ailang/cache/registry/sunholo/ailang_parse/*/docparse/main.ail archive.mbox

API

curl -X POST https://docparse.ailang.sunholo.com/api/v1/parse \
  -H "Content-Type: application/json" \
  -d '{"filepath":"sample_eml_welcome","outputFormat":"markdown","apiKey":"YOUR_API_KEY"}'

Python SDK

from ailang_parse import DocParse

client = DocParse(api_key="YOUR_API_KEY")
result = client.parse("inbox.eml", output_format="json")

# Metadata extracted from headers
print(result.metadata.title)   # Subject line
print(result.metadata.author)  # From display name

# Iterate blocks like any other format
for block in result.blocks:
    if block.style == "attachment":
        print(f"Attachment: {block.text}")

Parse in Browser    API Reference