Email Parsing API

Parse EML and MBOX files to structured JSON. Headers, body, attachments and MIME parts (the sections of a multi-part email) come out as typed blocks. Deterministic, no AI needed.

Raw Email Is Noise

A typical email from Gmail or Outlook is 2,000+ lines in the raw RFC 5322 mail format: MIME boundaries, base64-encoded attachments, headers folded over several lines, quoted-printable escape sequences. Give that to an LLM and it spends tokens on ARC-Seal: i=1; a=rsa-sha256; t=1775136695; cv=none; instead of the message.

AILANG Parse reads the RFC 5322 structure directly and returns clean typed blocks, in the same format as DOCX, XLSX and HTML parsing. Your code handles email the same way as every other format.

A 125 KB Google Cloud invoice email is 2,076 lines raw and 4 structured blocks once parsed. The parser extracts the message, reads the text of the PDF attachment (with --deep) and turns Subject, From and Date into metadata, in under 2 seconds and without AI.

Raw .eml vs Structured Output

Raw .eml file (2,076 lines)
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)
Structured output (4 blocks)
{
  "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

Headers → Structured Metadata

Subject becomes title, From becomes author, Date becomes created. Headers folded over several lines (RFC 5322 §2.2.3) are joined back into single values.

Body Text

A plain text body becomes a text block. For multipart/alternative emails (the same message as text and as HTML), both parts come out as separate blocks.

MIME Multipart

Multipart/mixed (body + attachments), multipart/alternative (text + HTML) and multipart messages nested inside each other are all split into their parts.

Attachments — Parsed Inline

Text-based attachments (CSV, HTML, Markdown, nested EML) are decoded and parsed in place, each as a section block with kind attachment. With --deep, PDF and Office attachments are parsed too, and scanned PDFs are read with OCR automatically. Images are listed by filename and MIME type. See details below.

Encoding Support

Email uses three kinds of encoding. AILANG Parse decodes all of them:

EncodingRFCWhat It DoesExample
Base64 RFC 2045 §6.8 Body or attachment encoded as ASCII VGhpcyBpcyBiYXNlNjQ= → "This is base64"
Quoted-Printable RFC 2045 §6.7 Non-ASCII chars as =XX hex pairs =C3=A9 → é   =C3=BC → ü
Encoded-Words RFC 2047 Non-ASCII in headers (Subject, From) =?UTF-8?B?5Lya6K2w?= → 会議の議事録

A UTF-8 character spread over several =XX pairs is decoded as one character, so accented characters (café, résumé, Zürich), CJK and emoji all come out right.

MBOX Archives

An MBOX file (RFC 4155) holds many emails, separated by lines beginning From . AILANG Parse splits it into individual messages, each in a section block with kind mbox-message. Headers, body and attachments are parsed for every message.

This makes MBOX a good fit for processing email in bulk: 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 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 in place, so one API call returns the email and the content of its attachments.

Parsed automatically: CSV, TSV, HTML, Markdown, plain text, and nested EML (message/rfc822). With the --deep flag, PDF, DOCX, PPTX, and XLSX attachments are parsed too. Image attachments are listed by filename and MIME type.

PDF attachments are read, not just listed. In a real 65,000-message archive, 2,455 of 8,323 attachments were PDF and none were DOCX, XLSX or PPTX. PDF is the attachment type that matters most in mail, so its text is parsed along with the message.
{
  "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 are handled the same way. A DOCX attachment is decoded and parsed into paragraphs and tables:

# Parse email + resolve Office attachments
docparse 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 are read in two steps, and the second runs only when needed. pdftotext runs first: it is free, close to instant, and right for any PDF that was created digitally and so has a text layer. If it returns nothing, which is what a scanned or photographed document looks like, the parser switches to docling, which runs OCR on your own machine.

BackendCostSpeedHandlesAutomatic?
pdftotextFree~0sPDFs with a text layerYes — default
doclingFree~9sScans, photos (local OCR)Yes — when pdftotext finds no text
aiPaidVariesHardest layoutsNever — only when you choose it

Both automatic steps are free, so the parser moves from one to the other without asking. The ai backend costs money, so it is never used unless you choose it. If you set --pdf-backend yourself, that choice is always used.

Example: an email carrying the same contract twice, once as a digital PDF and once as a scan. Both return "The Seller shall indemnify the Buyer against all claims", the second through OCR alone. Note that liteparse does not do OCR: it works out headings from font sizes in the existing text layer, so it cannot read scans any more than pdftotext can.

An attachment that cannot be read never stops the run. The rest of the message is still parsed and, in batch mode, so are the remaining files.

Forwarded emails (message/rfc822 attachments) are parsed too: the inner email's headers and body appear nested inside the attachment block.

Thread Reconstruction

A single email often makes no sense without the rest of its thread. AILANG Parse rebuilds conversation threads from MBOX archives using the Message-ID, In-Reply-To and References headers.

# Threaded mode: groups messages into conversations
docparse archive.mbox --threaded

Each thread becomes a section block with kind thread. It holds the cleaned-up subject, the list of participants, and the messages in date order with quoted text removed.

{
  "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": [...]}
  ]
}

This gives an LLM the whole conversation for summarization, triage or automated replies, without the same quoted text repeated in every message.

Use Cases

Once parsed, emails can be processed like any other document in your data pipeline.

AI Email Triage & Routing

Give an LLM structured email JSON for classification, routing or automatic replies. A 2,000-line raw email becomes 4 typed blocks, so the model works on the message and not on DKIM signatures and delivery headers.

Inbox Monitoring Agents

An AI agent watching a mailbox (IMAP, local .eml files, or Gmail API exports) parses each email to structured JSON, gets the message and a list of its attachments, and acts on it. The agent sees [attachment: invoice.pdf, application/pdf], not 1,500 lines of base64.

Email-to-Knowledge-Base

Parse MBOX exports from Gmail labels or Thunderbird folders into structured blocks and embed them in a vector database. You can filter on metadata (author, date, subject) as well as search the body text. One ailang run --batch call processes a whole archive.

Multi-Format Document Pipelines

CSV, HTML and Markdown attachments are parsed automatically. One API call returns the email body and the table data from the attached spreadsheet, with no second parse step. With --deep, PDF and Office attachments are parsed in the same pass, including scanned PDFs through local OCR.

Compliance & E-Discovery

Process MBOX archives in bulk. The delivery headers (Received, DKIM, SPF results) are kept for forensic analysis, and the body text is separate for legal review. The attachment list gives a complete inventory without extracting the binary data.

Customer Support Automation

Parse inbound support emails to extract the customer's question, the thread context and any attached screenshots or documents. The output can go straight into ticket creation, sentiment analysis or automated replies, and the email's metadata is kept for routing.

Batch mode: docparse *.eml parses many files in one run, so the startup time is spent once per batch and not once per file. Useful for processing a whole mailbox directory in one command.

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"
    }
  ]
}

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

Try It

CLI

# Parse an EML email file
docparse inbox.eml

# Parse an MBOX archive (multiple messages)
docparse 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_file("inbox.eml")

# 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

Frequently Asked Questions

How do I parse an EML file to JSON?

Send the .eml file to the AILANG Parse API or use the Python/JS/Go SDK. The parser returns structured JSON with typed blocks for headers, body text, HTML content, and attachments.

Does email parsing require AI or an API key?

No. Email is parsed by following the RFC 5322 and MIME standards, not with AI, so the same file always gives the same result. It runs in your browser (using WebAssembly) or on a server, with nothing else to install.

What email encodings are supported?

Base64 body decoding, quoted-printable (including multi-byte UTF-8), and RFC 2047 encoded-words for international headers (both B and Q encoding).

Can I parse MBOX archives with multiple messages?

Yes. An MBOX file is split into its individual messages, following RFC 4155. Each message becomes a separate section block with its headers and body parsed.

What is the output format for parsed emails?

The same block format as for DOCX, XLSX and HTML parsing: typed blocks plus metadata. Your code handles every format the same way. See the docs for the full schema.

Are email attachments parsed automatically?

Text-based attachments (CSV, HTML, Markdown, nested EML) are parsed automatically. With the --deep flag, PDF, DOCX, PPTX, and XLSX attachments are parsed too. PDF attachments are read with pdftotext first. If the PDF has no text layer, as with a scanned contract, the parser switches automatically to local OCR (docling). Both are free.

Can I reconstruct email threads from an MBOX file?

Yes. Use the --threaded flag. Messages are grouped into conversation threads using Message-ID/In-Reply-To/References headers, with quoted text stripped from replies.