eml-format-goon

v0.5.5

Published

3 years ago

RFC 822 EML file format parser and builder

Downloads

284

0High
0Medium
0Low

sunsoft

Relation with eml-format

The eml-format stops update since 2017.

But we need to use better tool.

So I build this package on top of it.

EML file format

A pure Node.js library for parsing and building EML files, i.e. e-mail message format described in RFC 822. EML is returned by the POP3 protocol and handled by many e-mail agents like Mozilla Thunderbird or Micfosot Outlook. An EML file consists of headers and body similar to the HTTP structure.

File extension: .eml
Mime type: message/rfc822

How does EML look like?

Date: Wed, 29 Jan 2014 11:10:06 +0100
To: "Foo Bar" <[email protected]>
From: Online Shop <[email protected]>
Subject: Winter promotions
Content-Type: text/plain; charset=utf-8

Lorem ipsum...

Getting Started

Setup

npm install -g eml-format-goon

Read EML file

var fs = require('fs');
var emlformat = require('eml-format-goon');

var eml = fs.readFileSync("sample.eml", "utf-8");
emlformat.read(eml, function(error, data) {
  if (error) return console.log(error);
  fs.writeFileSync("sample.json", JSON.stringify(data, " ", 2));
  console.log(data);
});

Output structure

{
  "subject": "Winter promotions",
  "from": "Online Shop <[email protected]>",
  "to": "\"Foo Bar\" <[email protected]>",
  "headers": {
    "Date": "Wed, 29 Jan 2014 11:10:06 +0100",
    "To": "\"Foo Bar\" <[email protected]>",
    "From": "Online Shop <[email protected]>",
    "Subject": "Winter promotions",
    "Content-Type": "multipart/related; type=\"text/html\";\r\nboundary=\"b1_4afb675bba4c412783638afbee8e8c71\"",
    "MIME-Version": "1.0"
  },
  "html": "<!DOCTYPE html>\r\n<html lang=\"en\">\r\n<head>\r\n<title>Lorem ipsum</title>\r\n=09<meta name=\"description\" ...",
  "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit....",
  "attachments": [
    {
      "name": "nodejs.png",
      "mimeType": "image/png",
      "data": {
        "type": "Buffer",
        "data": [ 137, 80, 78, 71, ... ]
      }
    }
  ]
}

[NEW] Read EML file with gb2312 html content

var fs = require('fs');
var emlformat = require('eml-format-goon');
var iconv = require('iconv-lite'); //decoder lib

var eml = fs.readFileSync("sample.eml", "utf-8");
emlformat.useEncodingPlugin({
  version: '1.0',
  encoding: 'gb2312',
  encoder: (content) => Buffer.from(iconv.decode(Buffer.from(content, 'base64'), 'gb2312'), 'utf8'),
});
emlformat.read(eml, function(error, data) {
  if (error) return console.log(error);
  fs.writeFileSync("sample.json", JSON.stringify(data, " ", 2));
  console.log(data);
});

Command Line

A command line tool to extract .eml file into a folder. Output directory will be populated with .txt and .html message and attachment files.

Usage:
  eml-unpack [options] [message.eml] [directory]

Options:
  --help       Print this message
  --verbose    Enable detailed logging
  --version    Print version number
  --json       Create parsed.json and manifest.json
  --no-unpack  Used with --json to skip unpacking

Examples:
  eml-unpack message.eml .
  eml-unpack --verbose sample.eml folder
  eml-unpack --json --no-unpack ./sample.eml ./folder

Reference

read(eml, [options], callback)

Parses EML file content and return user-friendly object.

| Argument | Type | Description | |----------|------|-------------| | eml | string or object | EML file content or object from 'parse' | | options | object | Optional parameter, { headersOnly: true } (false by default) | | callback | function(error, data) | Callback function to be invoked when read is complete |

parse(eml, [options], callback)

Parses EML file content and returns object-oriented representation of the content.

| Argument | Type | Description | |----------|------|-------------| | eml | string | EML file content | | options | object | Optional parameter, { headersOnly: true } (false by default) | | callback | function(error, data) | Callback function to be invoked when parse is complete |

build(eml, callback)

Builds an EML message.

| Argument | Type | Description | |----------|------|-------------| | data | object | E-mail data, see example | | callback | function(error, eml) | Callback function to be invoked when build is complete |

unpack(eml, directory, callback)

Unpacks EML message and attachments to a directory.

| Argument | Type | Description | |----------|------|-------------| | eml | string or object | EML file content or object from 'parse' | | directory | string | Folder name or directory path where to unpack | | callback | function(error, data) | Callback function to be invoked when read is complete |

Examples

Read headers only

var fs = require('fs');
var emlformat = require('eml-format-goon');

var eml = fs.readFileSync("sample.eml", "utf-8");
emlformat.read(eml, { headersOnly: true }, function(error, data) {
  if (error) return console.log(error);
  fs.writeFileSync("headers.json", JSON.stringify(data, " ", 2));
  console.log(data);
  console.log("Done!");
});

Read the complete EML file

The parse function parses raw EML content into JavaScript object for further processing.

var fs = require('fs');
var emlformat = require('eml-format');

var eml = fs.readFileSync("sample.eml", "utf-8");
emlformat.parse(eml, function(error, data) {
  if (error) return console.log(error);
  fs.writeFileSync("sample.json", JSON.stringify(data, " ", 2));
  console.log(data);
  console.log("Done!");
});

Or use the read instead of parse parse. The read function decodes the base64, quote-printable, =?UTF-8?...?= encoded content and extracts plain text, html content and attachments. So this method is a little slower but more user friendly.

emlformat.read(eml, function(error, data) {
  if (error) return console.log(error);
  fs.writeFileSync("user-friendly.json", JSON.stringify(data, " ", 2));
  console.log(data);
  console.log("Done!");
});

Unpack files from an EML file

Extracts plain text, html content and attachments to a directory

var fs = require('fs');
var emlformat = require('eml-format-goon');

var dir = "unpacked"; //Output directory
var eml = fs.readFileSync("sample.eml", "utf-8");
emlformat.unpack(eml, dir, function(error, data) {
  if (error) return console.log(error);
  console.log(data); //List of files
  console.log("Done!");
});

Create an EML file

var fs = require('fs');
var emlformat = require('eml-format-goon');

var data = {
  from: "[email protected]",
  to: {
    name: "Foo Bar",
    email: "[email protected]"
  },
  subject: "Winter promotions",
  text: "Lorem ipsum...",
  html: '<html><head></head><body>Lorem ipsum...<br /><img src="nodejs.png" alt="" /></body></html>',
  attachments: [
    {
      name: "sample.txt",
      contentType: "text/plain; charset=utf-8",
      data: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi eget elit turpis. Aliquam lorem nunc, dignissim in risus at, tempus aliquet justo..."
    },
    {
      name: "nodejs.png",
      contentType: "image/png",
      data: fs.readFileSync("nodejs.png"),
      inline: true
    }
  ]
};

var eml = fs.readFileSync("sample.eml", "utf-8");
emlformat.build(data, function(error, eml) {
  if (error) return console.log(error);
  fs.writeFileSync("build.eml", eml);
  console.log("Done!");
});

Register a new mime type file extension

var emlformat = require('eml-format-goon');
emlformat.fileExtensions["application/zip"] = ".zip";
emlformat.fileExtensions["application/octet-stream"] = ".bin";

Extract e-mail address and name

Plain text name

var emlformat = require('eml-format-goon');
var data = emlformat.getEmailAddress('"Foo Bar" <[email protected]>');
//data.name == "Foo Bar";
//data.email == "[email protected]";

UTF-8 encoded name

var emlformat = require('eml-format-goon');
var data = emlformat.getEmailAddress('=?UTF-8?Q?You=E2=80=99re=20Foo=20Bar?= <[email protected]>');
//data.name == "You’re Foo Bar";
//data.email == "[email protected]";

Decode "quoted-printable"

var emlformat = require('eml-format-goon');
var message = emlformat.unquotePrintable("Join line 1=\r\n=20with line 2=0D=0A");

Decode "=?UTF-8?...?=" string

var emlformat = require('eml-format-goon');
var message = emlformat.unquoteUTF8("=?UTF-8?B?V2hhdOKAmXMgeW91ciBvbmxpbmUgc2hvcHBpbmcgc3R5bGU/?=");