---
name: eml
displayName: EML Email Reader & Converter
description: Reads and converts RFC 822 email files (.eml) to plain text, JSON,
  or CSV. Use when opening .eml files, extracting email content, headers, or
  attachments metadata.
tags:
  - eml
  - email
  - rfc822
  - document
  - converter
  - mime
capabilities:
  - ReadEml
  - ConvertToJson
  - ConvertToCsv
  - ConvertToText
  - ExtractHeaders
  - ExtractAttachmentMetadata
representativeQueries:
  - Read a .eml file and show me the email content
  - Convert an eml email to JSON or CSV
  - Extract headers from an .eml file
  - What attachments are in this email file?
  - Parse an RFC 822 email message
version: 0.1.0
tier: curated
---

# EML Email Reader & Converter

Reads `.eml` email files (RFC 822 / MIME format) and converts their content to plain text, JSON, or CSV. An EML file encodes email headers, body parts, and attachments using MIME structure. This skill extracts human-readable body text, surfaces all headers, and lists attachment metadata without requiring any third-party libraries.

## When to use

- Opening or previewing a `.eml` file in a readable format.
- Extracting structured email data for downstream processing (search, archival, summarization).
- Pulling header fields (From, To, Subject, Date, Message-ID, CC) from an email file.
- Inventorying attachments (filename, content type, size) without extracting binary content.
- Converting a batch of email files into JSON or CSV for analysis.

## Steps

1. **Detect format** — confirm the file has a `.eml` extension or is a plain-text file starting with RFC 822 headers (e.g., `From:`, `Date:`, `MIME-Version:`).
2. **Route by task** — choose output mode: `text` (default, human-readable body), `json` (headers + body + attachments list), or `csv` (one row per email with key header columns).
3. **Run the bundled script** — `python3 scripts/eml_converter.py <file.eml> [--format text|json|csv]`. The script handles parsing and prints to stdout.
4. **Present output** — for `text`, display or summarize the email body; for `json`/`csv`, pass the structured data to the next step in the workflow.

## Operations

| Capability | CRUD | Resource | Tool |
|---|---|---|---|
| `ReadEml` | READ | EML file (headers + body) | `scripts/eml_converter.py` |
| `ConvertToText` | READ | Plain-text email body | `scripts/eml_converter.py --format text` |
| `ConvertToJson` | READ | JSON with headers, body, attachments | `scripts/eml_converter.py --format json` |
| `ConvertToCsv` | READ | CSV row with key header fields + body | `scripts/eml_converter.py --format csv` |
| `ExtractHeaders` | READ | All header fields decoded | `scripts/eml_converter.py --format json` (headers block) |
| `ExtractAttachmentMetadata` | READ | Attachment filename, content-type, size | `scripts/eml_converter.py --format json` (attachments block) |

## Output

- **text** — Decoded email body (prefers text/plain; falls back to text/html stripped of tags), preceded by a summary header block (From, To, Subject, Date).
- **json** — `{ "headers": { from, to, subject, date, message_id, cc, bcc, ... }, "body_text": "...", "body_html": "...", "attachments": [ { "filename", "content_type", "size_bytes", "content_id" } ] }`.
- **csv** — Columns: `from`, `to`, `cc`, `subject`, `date`, `message_id`, `body_text`, `attachment_count` (one row per file).

## Notes

- Uses only the Python standard library (`email`, `email.header`, `email.utils`, `html.parser`, `csv`, `json`) — no pip installs required. Requires Python 3.10 or later.
- RFC 2047 encoded header values (e.g., non-ASCII subjects) are decoded automatically.
- HTML bodies are stripped of tags to produce readable plain text when no text/plain part is present.
- Attachment binary content is NOT extracted or saved; only metadata (filename, type, size) is reported. To extract files use the `--extract-attachments` flag (writes to a `./attachments/` directory alongside the script call).
- Nested MIME structures (multipart/mixed containing multipart/alternative) are handled recursively.
- For mbox files (multiple emails separated by `From ` lines), split on `\nFrom ` first and run each segment through the script individually.

<!-- runner-fallback -->
## Remote runner (MCP)
Can't run this locally (no setup, missing dependency)? The StealthStack runner exposes the **same code** as server-side MCP tools — no local install needed: `eml_read`, `eml_to_json`, `eml_to_csv`, `eml_extract_attachments`. Call the `application/mcp` catalog twin of this skill (its `runnerTwin`).