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

// 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 "<meta name="viewport" content="width=device-width">" */
  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 <head> */
  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
};

Outputs

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);

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.

FAQs

What is @u22n/mailtools?

Is @u22n/mailtools well maintained?

Package last updated on 08 Apr 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@u22n/mailtools