@u22n/mailtools

Parse and extract the main message content from an HTML email.
Also runs several transformations to the email so that it can be displayed safely and correctly inside a browser.

Features

- Extract quotations (replies), signatures
- Remove scripts, trackers
- Convert text links into anchor tags
- Remove trailing whitespaces
- Block remote content

Usage

``ts
import { parseMessage } from '@u22n/mailtools';
import type { ParseMessageOptions } from '@u22n/mailtools';

const emailHtml =

const parsedEmail = parseMessage(emailHtml);
`

$3

`ts
// All options default to false.
const parseOptions: ParseMessageOptions = {
/* Remove quotations. Only affects the result messageHtml /
cleanQuotations: false,
/* Remove and return signatures. Only affects the result messageHtml /
cleanSignatures: false,
/* Automatically convert text links to anchor tags /
autolink: false,
/* Fix broken links and add the href to the title tag /
enhanceLinks: false,
/* Specific viewport to enforce. For example "" /
forceViewport: false,
/* Replace remote images with a transparent image, and replace other remote URLs with '#' /
noRemoteContent: false,
/* Replace remote content with custom URLs /
remoteContentReplacements: {} as ReplacementOptions,
/* Append the given style to the HTML /
includeStyle: false,
/* Remove specific styles that could affect the rendering of the html /
/* true = remove 'background-color', 'font-family', 'font-size'. /
/* otherwise pass in an string array of styles to remove /
cleanStyles: false
};
`

$3

`ts
const {
/* The original complete message. /
completeHtml: string;
/* The body of the message, stripped from secondary information /
parsedMessageHtml: string;
/* True if a quote was found and stripped /
didFindQuotation: boolean | null;
/* True if a signature was found and stripped /
didFindSignature: boolean | null;
/* The signature in plain text /
foundSignaturePlainText: string | null;
/* The signature in HTML /
foundSignatureHtml: string | null;
} = parseMessage(emailHtml, parseOptions);
`

$3

Autolinking and remote-content blocking are available as separate functions as well.

`js
const withLinks = linkify(messageHtml);

const noRemoteContent = blockRemoteContent(
messageHtml,
remoteContentReplacements
);
`

Development

$3

We have included a playground for local testing of functionality and features.

Edit the email html in playground/index.ts and run with pnpm run start.

The output will be logged to the console.

$3

`
pnpm run test
`

The main function parseMessage has a list of fixtures used for tests. The input HTML are files named xxx.input.html. The expected outputs are named xxx.output-complete.html and xxx.output-message.html.

$3

This script generates the respective outputs files for any .input.html file found without corresponding outputs.

To easily add a fixture from a real-world email, you can put the input HTML at /src/tests/prepareMessage/my-test.input.html, and then run pnpm run generate:fixtures to generate the output files based on what prepareMessage produced. You now only have to check that the outputs look good and make adjustments if necessary.

History

@u22n/mailtools is a modified and more feature filled version of tempo-email-parser.

We picked up on tempo-email-parser` which was not being maintained any more and updated it to modern tooling and dependencies. We are using this package at uninbox.com, everyone is free to use as they want and need.

Limitations

Its nearly impossible to parse every kind of outlook emails. We have implemented some measures to be able to parse them but we are not able to parse certain kind of signatures from them. Its totally impossible for us to parse them with out using some kind of LLM. Thats also might not be accurate.

We have covered major providers like gmail, newer outlook clients, proton mail and a few others.

You can help us improve this package by testing your email clients and signatures at and report in the built-in feedback system.

License

This package is licensed under the MIT License. Please see the LICENSE file for more information.