Skip to content

Commit

Permalink
Add README
Browse files Browse the repository at this point in the history
  • Loading branch information
baltpeter committed Mar 24, 2021
1 parent 3bc5624 commit 1476e18
Showing 1 changed file with 66 additions and 1 deletion.
67 changes: 66 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1 +1,66 @@
TODO
# mail2pdf

> Node.js library to render emails stored as .eml files to PDF.
![An example email converted using mail2pdf. On the left, the .eml file is opened in Thunderbird, on the right, the result PDF is opened. The test email was created using Microsoft Outlook and contains complex formatting like tables and images. The conversion was successful.](https://cdn.baltpeter.io/img/mail2pdf-screenshot.png)

With mail2pdf, you can convert emails stored as .eml files (as exported by Thunderbird, for example) to PDF files from Node.js. The goal is to produce an output that closely matches what an actual email program would export when using the "Print to PDF" feature. This can be useful for archival purposes, for example.

To produce the best possible output, mail2pdf deliberately relies on the rather heavy Puppeteer library which spawns an entire headless Chromium instance, instead of choosing another HTML to PDF solution implemented natively in JS.

The actual implementation is rather simple, it is mostly a thin wrapper around [Puppeteer](https://github.com/puppeteer/puppeteer/) and Nodemailer's [Mailparser](https://nodemailer.com/extras/mailparser/). The library supports internationalization and using different output templates. Currently, one template is provided that imitates Thunderbird's PDF output.

## Installation

You can install mail2pdf using yarn or npm:

```sh
yarn add mail2pdf
# or `npm i mail2pdf`
```

## Example usage

To demonstrate how to use mail2pdf, this code shows how to convert a [sample .eml file](https://cdn.baltpeter.io/other/mail2pdf/sample.eml) to PDF. The email was sent using Microsoft Outlook and contains complex formatting like tables and images.

```js
import mail2pdf from 'mail2pdf';
import { promises as fs } from 'fs';

(async () => {
// Simply call the `mail2pdf()` function with the email (or
// emails as an array) you want to convert. You can also
// pass additional options, see below for details.
const pdf = await mail2pdf('sample.eml', { language: 'en' });
// The resulting PDF is returned as a `Buffer` that you can
// save to disk for example.
await fs.writeFile('sample.pdf', pdf);
})();
```

You can view the conversion result [here](https://cdn.baltpeter.io/other/mail2pdf/sample.pdf).

## API

Only a single function is provided with the following interface:

### `mail2pdf(eml, options?)`

**Parameters:**

- `eml` - The email(s) in .eml format to process. You can provide a single email or multiple ones as an array. For
each one, either provide a file path as a string, which will then be read from the filesystem, or the
content of the .eml file as a `Buffer` or `Stream`.
- `options` - An optional object with the following properties:
- `language` - The language to be used for the labels in the generated PDF (optional, defaults to `en`).
Currently, English (`en`) and German (`de`) are supported.
- `template_name` - The template to use (optional, defaults to `thunderbird`). Currently, only `thunderbird`
is supported which will generate output similar to Thunderbird’s “Print to PDF” feature.

**returns:** `Promise<Buffer | Buffer[]>` - The generated PDF(s) contained in a `Buffer`. A single `Buffer` if you provided a single email for the `eml` parameter, or an array of `Buffer`s if you provided multiple ones.

## License

mail2pdf is licensed under the MIT license, see the [`LICENSE`](/LICENSE) file for details.

Issues and pull requests are welcome! If you find an email that doesn't render correctly, please let me know. To help reproduce the problem, it would be great if you could attach the .eml file in question to the issue.

0 comments on commit 1476e18

Please sign in to comment.