Building an Email Parser That LLMs Actually Understand

The Problem with Raw Email

Email is one of the oldest internet protocols, and it shows. A single message can contain:

• Nested MIME parts with different encodings

• HTML with inline CSS, tracking pixels, and scripts

• Quoted-printable and Base64 content

• Threading headers that reference deleted messages

Feeding this directly to an LLM is like asking someone to read a novel printed on a circuit board.

Our Approach

We built SpiderMail's parser with one principle: output should be as predictable as a database row.

Every email becomes a typed YAML document:

message:
  from: {name: "Alice Chen", email: "alice@example.com"}
  to: [{name: "Bob Smith", email: "bob@example.com"}]
  subject: "Q3 Budget Review"
  date: "2026-04-15T09:30:00Z"
  body: "Clean plaintext content here..."
  attachments:
    - name: "budget.xlsx"
      type: "application/vnd.ms-excel"
      size_bytes: 45231

Key Design Decisions

1. Flatten, Don't Nest

LLMs struggle with deeply nested structures. We flatten multipart messages into a single body with metadata.

2. Explicit Types

Every field has a predictable type. No guessing whether "date" is an ISO string or a Unix timestamp.

3. Lossy by Design

We intentionally discard HTML formatting, tracking pixels, and invisible content. What the agent sees is what a human would read.

Results

After switching to our parser, agent accuracy on email classification tasks improved by 34%, and prompt injection attempts dropped to near zero.