Skip to content

RFC 822 EML file format parser and builder

License

Notifications You must be signed in to change notification settings

arkaydeus/eml-format

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

13 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

EML file format

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

File extension: .eml
Mime type: message/rfc822

What 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

Read EML file

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

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, ... ]
      }
    }
  ]
}

Command Line

A command line tool to extract an .eml file into a folder. The 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 returns 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');

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 a 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 read instead of 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');

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

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!");
});

Multiple e-mail addresses

var data = {
  from: "[email protected]",
  to: [ 
    { name: "Foo", email: "[email protected]" },
    { name: "Bar", email: "[email protected]" }
  ],
  cc: [
    { name: "Foo Bar", email: "[email protected]" },
    { email: "[email protected]" }
  ],
  subject: "Winter promotions",
  ...
};

Register a new mime type file extension

var emlformat = require('eml-format');
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');
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');
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]";

Multiple e-mail addresses

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

Build e-mail address

var emlformat = require('eml-format');
var string = emlformat.toEmailAddress({
  name: "Foo Bar",
  email: "[email protected]"
});
//string = "Foo Bar" <[email protected]>

Decode "quoted-printable"

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

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

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

Decode other character set

var emlformat = require('eml-format');
var message = emlformat.unquoteString("=?ISO-8859-2?Q?Po=B9ta?=");

About

RFC 822 EML file format parser and builder

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 95.5%
  • HTML 4.5%