# letterparser
> Raw e-mail parsing with MIME and plaintext support (isomorphic)
Latest version **0.1.8** (published 2024-09-19) · BSD-3-Clause-Clear license · 0 weekly downloads
## Install
```sh
npm install letterparser
pnpm add letterparser
yarn add letterparser
bun add letterparser
```
## Health
**Score 30/100 (F)** — status: abandoned.
Positive: has types; esm support; no vulnerabilities; high quality score.
Warnings: low downloads; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.1.8 |
| Published | 2024-09-19 |
| First published | 2020-04-01 |
| Weekly downloads | 0 |
| License | BSD-3-Clause-Clear |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 40.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 51 |
| Author | Mat Sz |
| Maintainers | mat-sz |
| Keywords | email, e-mail, mail, mime, mailparser, emailparser, mail-parser, email-parser, e-mail-parser, mime-parser, mime-message, mime-message-parser, parser, typescript, isomorphic |
## Links
- npm: https://www.npmjs.com/package/letterparser
- Repository: https://github.com/mat-sz/letterparser
- Issues: https://github.com/mat-sz/letterparser/issues
- npm.io page: https://npm.io/package/letterparser
## Dependencies (2)
- [base64-js](https://npm.io/package/base64-js.md) ^1.5.1
- [lettercoder](https://npm.io/package/lettercoder.md) ^0.0.7
## Alternatives
- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads
## Recent versions
- 0.1.8 (latest) — 2024-09-19
- 0.1.7 — 2024-06-26
- 0.1.6 — 2024-05-12
- 0.1.5 — 2024-04-21
- 0.1.4 — 2024-01-11
- 0.1.3 — 2023-12-19
- 0.1.2 — 2023-09-26
- 0.1.1 — 2023-08-30
- 0.1.0 — 2023-08-17
- 0.0.12 — 2023-03-28
- 0.0.11 — 2023-03-28
- 0.0.10 — 2022-09-12
- 0.0.9 — 2022-08-31
- 0.0.8 — 2021-05-24
- 0.0.7 — 2021-03-16
- … 6 more at https://npm.io/package/letterparser/versions
## README
**letterparser** is a parser library created for parsing e-mail messages. The library is written in TypeScript, fully supports both browser and server environments. The performance may not be the best at the current stage of development, parsing large messages is not recommended.
This library was created as an isomorphic alternative for [mailparser](https://github.com/nodemailer/mailparser).
The following RFCs are supported (or will be) by letterparser:
- [RFC 5322](https://tools.ietf.org/html/rfc5322.html)
- [RFC 6532](https://tools.ietf.org/html/rfc6532.html)
- [RFC 2046](https://tools.ietf.org/html/rfc2046.html)
Parsing multipart and plain text messages is currently working, although the output is raw. A function for extracting the most commonly used data will be added in a future release.
| Builder | SMTP client/server |
| -------------------------------------------------------- | -------------------------------------------------- |
| [letterbuilder](https://github.com/mat-sz/letterbuilder) | [@typemail/smtp](https://github.com/typemail/smtp) |
## Usage
> **WARNING!** [node.js built with full ICU is required](https://nodejs.org/api/intl.html). (full-icu NPM package may work as a substitute, although this is not recommended.)
>
> By default, recent node.js versions ship full ICU binaries. Incomplete ICU will result in bad encoding errors.
### General information
To get information about the message, use `extract`:
```js
import { extract } from 'letterparser';
let res = extract(`Date: Wed, 01 Apr 2020 00:00:00 -0000
From: A
To: B
Subject: Hello world!
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Some message.`);
```
The function returns `LetterparserMail`:
```ts
export interface LetterparserMailbox {
name?: string;
address: string;
raw: string;
}
export interface LetterparserAttachment {
contentType: LetterparserContentType;
body: string | Uint8Array;
contentId?: string;
filename?: string;
}
export interface LetterparserMail {
subject?: string;
to?: LetterparserMailbox[];
cc?: LetterparserMailbox[];
bcc?: LetterparserMailbox[];
from?: LetterparserMailbox;
attachments?: LetterparserAttachment[];
html?: string;
text?: string;
amp?: string;
}
```
### Message structure
The library also exports a `parse` function that outputs the raw structure of the message.
```js
import { parse } from 'letterparser';
let node = parse(`Date: Wed, 01 Apr 2020 00:00:00 -0000
From: A
To: B
Subject: Hello world!
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Some message.`);
```
The return value of that function is `LetterparserNode`, as defined below:
```ts
interface LetterparserContentType {
type: string;
encoding?: string;
parameters: Headers;
}
interface LetterparserNode {
contentType: LetterparserContentType;
headers: Headers;
body: LetterparserNode | LetterparserNode[] | string | Uint8Array;
}
```
Headers names are normalized to be camel case with dashes.
E.g.
`Content-ID` becomes `Content-Id`
`content-type` becomes `Content-Type`
---
_Source: https://npm.io/package/letterparser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._