# 📧 eml-parser [![npm version](https://img.shields.io/npm/v/eml-parser.svg)](https://www.npmjs.com/package/eml-parser) [![license](https://img.shields.io/npm/l/eml-parser.svg)](https://github.com/ankit1329/Eml-Parser/blob/master/LICENSE) [![CI](https://github.com/ankit1329/Eml-Parser/actions/workflows/ci.yml/badge.svg)](https://github.com/ankit1329/Eml-Parser/actions/workflows/ci.yml) > Parse `.eml` and `.msg` files, extract headers and attachments, or convert messages to PDF / HTML / image formats. ## ✨ Features - 📨 **Parse** `.eml` and `.msg` email files - 📋 **Extract** headers, body, attachments, and embedded files - 🎨 **Render** emails as complete HTML documents with an Outlook-style header (avatar, recipients, date) - 🔗 **Expand / collapse** long recipient lists with a CSS-only toggle — no JavaScript - 🔍 **Highlight** keywords in email body with `` tags - 📄 **Convert** emails to PDF, PNG, or JPEG (stream or buffer) - 🔤 **TypeScript** declarations included out of the box - ⚡ Requires **Node.js 18+** --- ## 📖 Table of Contents - [Installation](#-installation) - [Quick Start](#-quick-start) - [TypeScript](#-typescript) - [API Reference](#-api-reference) - [Constructor](#constructor) - [Shared Options](#shared-options) - [.eml Methods](#eml-methods) - [.msg Methods](#msg-methods) - [HTML Output](#-html-output) - [Keyword Highlighting](#-keyword-highlighting) - [License](#-license) --- ## 📦 Installation ```bash npm install eml-parser ``` Requires **Node.js 18 or later**. --- ## 🚀 Quick Start ### .eml file ```js const fs = require('fs'); const EmlParser = require('eml-parser'); const parser = new EmlParser(fs.createReadStream('./email.eml')); // Get headers const headers = await parser.getEmailHeaders(); console.log(headers.subject, headers.from, headers.to); // Get full HTML (with styled header) const html = await parser.getEmailAsHtml(); fs.writeFileSync('email.html', html); // Extract attachments const attachments = await parser.getEmailAttachments(); for (const att of attachments) { fs.writeFileSync(att.filename, att.content); } ``` ### .msg file ```js const parser = new EmlParser(fs.createReadStream('./email.msg')); const headers = await parser.getMessageHeaders(); console.log(headers.subject, headers.from, headers.to); const html = await parser.getMessageAsHtml(); fs.writeFileSync('email.html', html); ``` ### Convert to PDF ```js const parser = new EmlParser(fs.createReadStream('./email.eml')); const stream = await parser.convertEmailToStream('pdf'); stream.pipe(fs.createWriteStream('email.pdf')); ``` > All methods return Promises — use `async/await` (shown above) or `.then()/.catch()`. --- ## 🔤 TypeScript This package ships with `index.d.ts` — no extra `@types` package needed. ```ts import fs from 'fs'; import EmlParser, { EmailHeaders, HighlightOptions } from 'eml-parser'; const parser = new EmlParser(fs.createReadStream('./email.eml')); const headers: EmailHeaders = await parser.getEmailHeaders(); const html: string = await parser.getEmailAsHtml({ highlightKeywords: ['invoice'], includeSubject: false, }); ``` ### Available Types | Type | Description | |------|-------------| | `Address` | `{ name: string, address: string }` | | `EmailHeaders` | Parsed `.eml` headers (subject, from, to, cc, date, messageId, inReplyTo) | | `MessageHeaders` | Parsed `.msg` headers (subject, from, to, cc, date) | | `HighlightOptions` | `{ highlightKeywords?: string[], highlightCaseSensitive?: boolean }` | | `ParseEmlOptions` | `HighlightOptions & { ignoreEmbedded?: boolean }` | | `ParseMsgOptions` | `HighlightOptions` | --- ## 📋 API Reference ### Constructor ```js const parser = new EmlParser(readableStream); ``` | Param | Type | Description | |-------|------|-------------| | `readableStream` | `Readable` | A Node.js [readable stream](https://nodejs.org/api/fs.html#fs_fs_createreadstream_path_options) pointing to an `.eml` or `.msg` file | > **One parser per file.** Create a new `EmlParser` instance for each file you want to process. --- ### Shared Options These options are accepted by multiple methods. They are documented here once and referenced below. #### HighlightOptions | Option | Type | Default | Description | |--------|------|---------|-------------| | `highlightKeywords` | `string[]` | — | Keywords to wrap with `` tags in the email HTML | | `highlightCaseSensitive` | `boolean` | `false` | When `true`, matches keywords case-sensitively | See [Keyword Highlighting](#-keyword-highlighting) for details and examples. #### Conversion Parameters These apply to `convertEmailToStream`, `convertEmailToBuffer`, `convertMessageToStream`, and `convertMessageToBuffer`. | Param | Type | Default | Description | |-------|------|---------|-------------| | `type` | `'pdf' \| 'jpeg' \| 'png'` | `'pdf'` | Output format | | `orientation` | `'potrait' \| 'landscape'` | `'landscape'` | Page orientation | | `format` | `'A3' \| 'A4' \| 'A5' \| 'Legal' \| 'Letter' \| 'Tabloid'` | — | Page size | | `options` | `HighlightOptions` | — | Keyword highlighting options | --- ### .eml Methods #### `parseEml(options?)` Parse the full `.eml` file. Returns the complete parsed email object. | Param | Type | Description | |-------|------|-------------| | `options.ignoreEmbedded` | `boolean` | When `true`, excludes embedded files from the attachments array | | `options.highlightKeywords` | `string[]` | Keywords to highlight — see [HighlightOptions](#highlightoptions) | | `options.highlightCaseSensitive` | `boolean` | Case-sensitive matching — see [HighlightOptions](#highlightoptions) | **Returns:** `Promise` — the full parsed email with these key properties: ```ts { subject: string; from: { value: Address[] }; to: { value: Address[] }; cc: { value: Address[] }; date: Date; messageId: string; inReplyTo: string; html: string; // HTML body (with highlights applied if requested) text: string; // Plain text body textAsHtml: string; // Plain text converted to HTML attachments: Attachment[]; headers: Map; headerLines: object[]; references: string; } ``` ```js const result = await parser.parseEml({ ignoreEmbedded: true }); console.log(result.subject, result.html); ``` --- #### `getEmailHeaders()` Extract a simplified headers object from the `.eml` file. **Returns:** `Promise` ```ts { subject: string; from: Address[]; // [{ name: 'John', address: 'john@example.com' }] to: Address[]; cc?: Address[]; date: Date; inReplyTo?: string; messageId: string; } ``` ```js const headers = await parser.getEmailHeaders(); console.log(headers.subject); console.log(headers.from[0].name, headers.from[0].address); ``` --- #### `getEmailBodyHtml(options?)` Get the email body as an HTML string — **without** headers (subject, from, to, etc.). | Param | Type | Description | |-------|------|-------------| | `options` | `HighlightOptions` | Keyword highlighting — see [HighlightOptions](#highlightoptions) | **Returns:** `Promise` ```js const bodyHtml = await parser.getEmailBodyHtml(); fs.writeFileSync('body.html', bodyHtml); ``` --- #### `getEmailAsHtml(options?)` Get the **complete email** as a full HTML document (``) with an Outlook-style header section and the email body. See [HTML Output](#-html-output) for details on the rendered layout. | Param | Type | Default | Description | |-------|------|---------|-------------| | `options.includeSubject` | `boolean` | `true` | Set to `false` to hide the subject line | | `options.highlightKeywords` | `string[]` | — | See [HighlightOptions](#highlightoptions) | | `options.highlightCaseSensitive` | `boolean` | `false` | See [HighlightOptions](#highlightoptions) | **Returns:** `Promise` — a complete HTML5 document string ```js const html = await parser.getEmailAsHtml({ includeSubject: false }); fs.writeFileSync('email.html', html); ``` --- #### `convertEmailToStream(type?, orientation?, format?, options?)` Convert the email to a readable stream in PDF, PNG, or JPEG format. Pipe the result to a writable stream to save to a file. See [Conversion Parameters](#conversion-parameters) for the parameter details. **Returns:** `Promise` ```js const stream = await parser.convertEmailToStream('pdf', 'landscape', 'A4'); stream.pipe(fs.createWriteStream('email.pdf')); ``` --- #### `convertEmailToBuffer(type?, orientation?, format?, options?)` Convert the email to a Buffer in PDF, PNG, or JPEG format. See [Conversion Parameters](#conversion-parameters) for the parameter details. **Returns:** `Promise` ```js const buffer = await parser.convertEmailToBuffer('png'); fs.writeFileSync('email.png', buffer); ``` --- #### `getEmailAttachments(options?)` Extract attachments from the `.eml` file. | Param | Type | Default | Description | |-------|------|---------|-------------| | `options.ignoreEmbedded` | `boolean` | `false` | When `true`, excludes embedded files (e.g. inline images) | **Returns:** `Promise` — each attachment has `filename`, `content` (Buffer), `contentType`, etc. ```js const attachments = await parser.getEmailAttachments({ ignoreEmbedded: true }); for (const att of attachments) { fs.writeFileSync(att.filename, att.content); } ``` --- #### `getEmailEmbeddedFiles()` Extract only embedded files (e.g. inline images) — excludes regular attachments. **Returns:** `Promise` ```js const embedded = await parser.getEmailEmbeddedFiles(); for (const file of embedded) { fs.writeFileSync(file.filename, file.content); } ``` --- ### .msg Methods #### `parseMsg(options?)` Parse the full `.msg` file. Returns the complete parsed message object. | Param | Type | Description | |-------|------|-------------| | `options.highlightKeywords` | `string[]` | Keywords to highlight — see [HighlightOptions](#highlightoptions) | | `options.highlightCaseSensitive` | `boolean` | Case-sensitive matching — see [HighlightOptions](#highlightoptions) | **Returns:** `Promise` — the parsed message with these key properties: ```ts { subject: string; senderName: string; senderEmail: string; recipients: [{ name: string; email: string; recipType: 'to' | 'cc'; }]; body: string; html: string; attachments: Attachment[]; messageDeliveryTime: string; creationTime: string; headers: string; // ...and more (messageClass, internetCodepage, etc.) } ``` ```js const parser = new EmlParser(fs.createReadStream('./email.msg')); const result = await parser.parseMsg(); console.log(result.subject, result.senderName); ``` --- #### `getMessageHeaders()` Extract a simplified headers object from the `.msg` file. **Returns:** `Promise` ```ts { subject: string; from: Address[]; // [{ name: 'John', address: 'john@example.com' }] to: Address[]; cc: Address[]; date: string | Date; } ``` ```js const headers = await parser.getMessageHeaders(); console.log(headers.subject, headers.from[0].name); ``` --- #### `getMessageBodyHtml(options?)` Get the message body as an HTML string — **without** headers (subject, from, to, etc.). | Param | Type | Description | |-------|------|-------------| | `options` | `HighlightOptions` | Keyword highlighting — see [HighlightOptions](#highlightoptions) | **Returns:** `Promise` ```js const bodyHtml = await parser.getMessageBodyHtml(); fs.writeFileSync('body.html', bodyHtml); ``` --- #### `getMessageAsHtml(options?)` Get the **complete message** as a full HTML document (``) with an Outlook-style header section and the message body. See [HTML Output](#-html-output) for details. | Param | Type | Default | Description | |-------|------|---------|-------------| | `options.includeSubject` | `boolean` | `true` | Set to `false` to hide the subject line | | `options.highlightKeywords` | `string[]` | — | See [HighlightOptions](#highlightoptions) | | `options.highlightCaseSensitive` | `boolean` | `false` | See [HighlightOptions](#highlightoptions) | **Returns:** `Promise` ```js const parser = new EmlParser(fs.createReadStream('./email.msg')); const html = await parser.getMessageAsHtml({ includeSubject: true }); fs.writeFileSync('message.html', html); ``` --- #### `convertMessageToStream(type?, orientation?, format?, options?)` Convert the message to a readable stream in PDF, PNG, or JPEG format. See [Conversion Parameters](#conversion-parameters) for the parameter details. **Returns:** `Promise` ```js const parser = new EmlParser(fs.createReadStream('./email.msg')); const stream = await parser.convertMessageToStream('pdf'); stream.pipe(fs.createWriteStream('message.pdf')); ``` --- #### `convertMessageToBuffer(type?, orientation?, format?, options?)` Convert the message to a Buffer in PDF, PNG, or JPEG format. See [Conversion Parameters](#conversion-parameters) for the parameter details. **Returns:** `Promise` ```js const parser = new EmlParser(fs.createReadStream('./email.msg')); const buffer = await parser.convertMessageToBuffer('jpeg'); fs.writeFileSync('message.jpeg', buffer); ``` --- #### `getMessageAttachments()` Extract attachments from the `.msg` file. **Returns:** `Promise` — each attachment has `filename`, `content` (Buffer), `contentType`, etc. ```js const parser = new EmlParser(fs.createReadStream('./email.msg')); const attachments = await parser.getMessageAttachments(); for (const att of attachments) { fs.writeFileSync(att.filename, att.content); } ``` --- ## 🎨 HTML Output `getEmailAsHtml()` and `getMessageAsHtml()` return a complete HTML5 document with an **Outlook-style header**: ``` ┌─────────────────────────────────────────────────────┐ │ [J] John Doe │ │ To: alice@...; bob@...; charlie@... 17 Mar 2026 │ │ Cc: dave@...; +4 more │ │─────────────────────────────────────────────────────│ │ │ │ (email body) │ │ │ └─────────────────────────────────────────────────────┘ ``` **Layout details:** - **Circular avatar** with the sender's initial (color: teal) - **From** name and email address on the first row - **To** recipients and formatted date on the second row - **Cc** recipients on the third row - **Long recipient lists** (more than 3) are automatically truncated with a **"+N more"** toggle that expands on click — pure CSS, no JavaScript **Options:** | Option | Type | Default | Description | |--------|------|---------|-------------| | `includeSubject` | `boolean` | `true` | Show or hide the `

` subject heading above the header | --- ## 🔍 Keyword Highlighting Any method that accepts `HighlightOptions` can highlight keywords in the email's HTML body by wrapping matches in `` tags. ```js const html = await parser.getEmailAsHtml({ highlightKeywords: ['invoice', 'payment due'], highlightCaseSensitive: false, // default }); // Matches are wrapped: invoice ``` - Regex special characters in keywords are automatically escaped — safe to pass user input - When `highlightCaseSensitive` is `false` (default), matching is case-insensitive - Highlighting is applied to `html` content first; falls back to `textAsHtml` for plain-text emails - Works with `parseEml`, `parseMsg`, `getEmailBodyHtml`, `getMessageBodyHtml`, `getEmailAsHtml`, `getMessageAsHtml`, and all conversion methods --- ## 📄 License [MIT](LICENSE) © [Ankit Prakash](https://www.linkedin.com/in/ankit1329)