@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
import { parseMessage } from '@u22n/mailtools';
import type { ParseMessageOptions } from '@u22n/mailtools';
const emailHtml = `
<div>Hello there</div>
`;
const parsedEmail = parseMessage(emailHtml);
Options
const parseOptions: ParseMessageOptions = {
cleanQuotations: false,
cleanSignatures: false,
autolink: false,
enhanceLinks: false,
forceViewport: false,
noRemoteContent: false,
remoteContentReplacements: {} as ReplacementOptions,
includeStyle: false,
cleanStyles: false
};
Outputs
const {
completeHtml: string;
parsedMessageHtml: string;
didFindQuotation: boolean | null;
didFindSignature: boolean | null;
foundSignaturePlainText: string | null;
foundSignatureHtml: string | null;
} = parseMessage(emailHtml, parseOptions);
Other
Autolinking and remote-content blocking are available as separate functions as well.
const withLinks = linkify(messageHtml);
const noRemoteContent = blockRemoteContent(
messageHtml,
remoteContentReplacements
);
Development
Playground
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.
Tests
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
.
pnpm run generate:fixtures
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 https://tools.unin.sh 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.