@protontech/mimemessage

mimemessage.js

MIME messages for JavaScript (RFC 2045 & 2046).

Suitable for parsing and generating MIME messages, allowing access to headers and body, including multipart messages such as:

From: Nathaniel Borenstein <[e-mail]>
To: Ned Freed <[e-mail]>
Date: Sun, 21 Mar 1993 23:56:48 -0800 (PST)
Subject: Sample message
MIME-Version: 1.0
Content-type: multipart/mixed; boundary="simple boundary"

--simple boundary

This is implicitly typed plain US-ASCII text.
It does NOT end with a linebreak.
--simple boundary
Content-type: text/plain; charset=us-ascii

This is explicitly typed plain US-ASCII text.
It DOES end with a linebreak.

--simple boundary--

NOTE: This library is not intended for mail parsing (there are tons of MIME related Node libraries for that). In fact, it does not deal with encodings different that UTF-8. The purpose of this library is to be used in pure browser/Node environments in which MIME messages are useful to transmit data.

Installation

npm:

$ npm install mimemessage --save

And then:

var mimemessage = require('mimemessage');

Browserified library

The browserified version of the library at dist/mimemessage.js exposes the global window.mimemessage module.

<script type='text/javascript' src='js/mimemessage.js'></script>

Usage Example

Let's build a complex multipart MIME message with the following content:

• An HTML body.
• An alternate plain text for those non HTML capable clients.
• An attached PNG image named "mypicture.png" encoded in Base64.

var mimemessage = require('mimemessage');
var msg, alternateEntity, htmlEntity, plainEntity, pngEntity;

// Build the top-level multipart MIME message.
msg = mimemessage.factory({
    contentType: 'multipart/mixed',
    body: []
});
msg.header('Message-ID', '<1234qwerty>');

// Build the multipart/alternate MIME entity containing both the HTML and plain text entities.
alternateEntity = mimemessage.factory({
    contentType: 'multipart/alternate',
    body: []
});

// Build the HTML MIME entity.
htmlEntity = mimemessage.factory({
    contentType: 'text/html;charset=utf-8',
    body: '<p>This is the <strong>HTML</strong> version of the message.</p>'
});

// Build the plain text MIME entity.
plainEntity = mimemessage.factory({
    body: 'This is the plain text version of the message.'
});

// Build the PNG MIME entity.
pngEntity = mimemessage.factory({
    contentType: 'image/png',
    contentTransferEncoding: 'base64',
    body: 'fVkVvYassFAAAABQAAAAIAAAAbWltZXR5cG=='
});
pngEntity.header('Content-Disposition', 'attachment ;filename="mypicture.png"');

// Add both the HTML and plain text entities to the multipart/alternate entity.
alternateEntity.body.push(htmlEntity);
alternateEntity.body.push(plainEntity);

// Add the multipart/alternate entity to the top-level MIME message.
msg.body.push(alternateEntity);

// Add the PNG entity to the top-level MIME message.
msg.body.push(pngEntity);

By calling msg.toString() it produces the following MIME formatted string:

Content-Type: multipart/mixed;boundary=92ckNGfS
Message-Id: <1234qwerty>

--92ckNGfS
Content-Type: multipart/alternate;boundary=EVGuDPPT

--EVGuDPPT
Content-Type: text/html;charset=utf-8

<p>This is the <strong>HTML</strong> version of the message.</p>
--EVGuDPPT
Content-Type: text/plain;charset=utf-8

This is the plain text version of the message.
--EVGuDPPT--
--92ckNGfS
Content-Type: image/png
Content-Transfer-Encoding: base64
Content-Disposition: attachment ;filename="mypicture.png"

fVkVvYassFAAAABQAAAAIAAAAbWltZXR5cG==
--92ckNGfS--

Documentation

You can read the full API documentation in the docs folder.

Tests

Run once,

$ npm test

Watch mode:

$ npm run test -- -w

Debugging

The library includes the Node debug module. In order to enable debugging:

In Node set the DEBUG=mimemessage* environment variable before running the application, or set it at the top of the script:

process.env.DEBUG = 'mimemessage*';

In the browser run mimemessage.debug.enable('mimemessage*'); and reload the page. Note that the debugging settings are stored into the browser LocalStorage. To disable it run mimemessage.debug.disable('mimemessage*');.

You can also set the envia the console, ex:

DEBUG=mimemessage:* npm run test -- -w

Author

Iñaki Baz Castillo Kay Lukas ProtonMail team

License

MIT :)