edevil / MIMEText

RFC 2822 compliant email message generator written in node.js

MIMEText

RFC 2822 compliant raw email message generator written in node.js

Install

npm i mimetext

Use

const {createMimeMessage} = require('mimetext')
// or
import {createMimeMessage} from 'mimetext'

Create a simple plain text email:

const msg = createMimeMessage()
msg.setSender({name: 'Lorem Ipsum', addr: '[e-mail]'})
msg.setRecipient('[e-mail]')
msg.setSubject('🚀 Issue 49!')
msg.setMessage('text/plain', `Hi,
I'm a simple text.`)

That's it. Now get the raw email message:

const raw = msg.asRaw()

Output:

Date: Sun, 24 Oct 2021 04:50:32 +0000
From: "Lorem Ipsum" <[e-mail]>
To: <[e-mail]>
Message-ID: <[e-mail]>
Subject: =?utf-8?B?8J+agCBJc3N1ZSA0OSE=?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8

Hi,
I'm a simple text.

More Sophisticated Example

Here is more complex email message which contains html with plaintext version and has an attachment.

const msg = createMimeMessage()
msg.setSender('Lorem Ipsum <[e-mail]>')
msg.setTo({name: 'Foo Bar', addr: '[e-mail]'})
msg.setCc('Abc Def <[e-mail]>')
msg.setBcc(['[e-mail]', '[e-mail]', {name: 'Name', addr: '[e-mail]'}])
msg.setSubject('🚀 Issue 49!')
// add html version
msg.setMessage('text/html', `Hi,
I'm <strong>a bold</strong> text.`)
// add alternative plain text version
msg.setMessage('text/plain', `Hi,
I'm a simple text.`)
// set custom header
msg.setHeader('X-Abc', 'asdildffdişfsdi')
// add an attachment
msg.setAttachment('test.jpg', 'image/jpg', msg.toBase64( fs.readFileSync('./tests/test.jpg') ))

Here is the output of the .asRaw:

Date: Sun, 24 Oct 2021 05:00:03 +0000
From: "Lorem Ipsum" <[e-mail]>
To: "Foo Bar" <[e-mail]>
Cc: "Abc Def" <[e-mail]>
Bcc: <[e-mail]>, <[e-mail]>, "Name" <[e-mail]>
Message-ID: <[e-mail]>
Subject: =?utf-8?B?8J+agCBJc3N1ZSA0OSE=?=
MIME-Version: 1.0
X-Abc: asdildffdişfsdi
Content-Type: multipart/mixed; boundary=tdplbi0e8pj

--tdplbi0e8pj
Content-Type: multipart/alternative; boundary=oagdypniyp

--oagdypniyp
Content-Type: text/plain; charset=UTF-8

Hi,
I'm a simple text.

--oagdypniyp
Content-Type: text/html; charset=UTF-8

Hi,
I'm <strong>a bold</strong> text.

--oagdypniyp--
--tdplbi0e8pj
Content-Type: image/jpg; charset=UTF-8
Content-Transfer-Encoding: base64
Content-Disposition: attachment;filename="test.jpg"

/9j/4AAQSkZJRgABAgAAZABkAAD/7AARR....................Oc2YO5LuFLMxUeBjH5//2Q==

--tdplbi0e8pj--

API

.setSender(value)

Sender can be specified in multiple ways:

message.setSender('[e-mail]')
message.setSender('"Sender Fullname" <[e-mail]>')
message.setSender({name: 'Sender Name', addr: '[e-mail]'})
message.setSender(['[e-mail]', '[e-mail]'])

Returns Mailbox instance.

.getSender()

Returns Mailbox instance.

.setTo(value), .setCc(value), .setBcc(value), .setRecipient(value, opts)

All of the .setTo, .setCc and .setBcc methods maps their input to .setRecipient. Returns array of Mailbox instances.

message.setTo('[e-mail]')
message.setTo('"Person Fullname" <[e-mail]>')
message.setTo({name: 'Person Name', addr: '[e-mail]'})
message.setTo([
  '[e-mail]',
  {name: 'Person Name', addr: '[e-mail]'}
])

message.setRecipient('[e-mail]', {type: 'to'}) // to is default

.getRecipients(opts={type: 'to'})

Returns array of Mailbox instances.

.setSubject(value)

Returns the value.

const value = 'Weekly Newsletter 49 Ready 🚀'
message.setSubject(value)

.getSubject()

Returns the value.

.setHeader()

Inserts a header to the message.

message.setHeader('X-Custom-Header', 'value')

.getHeader(name)

Returns the value of the header.

.setMessage(type, data, moreHeaders={})

Adds a content to the email. Valid values for type are text/plain and text/html. data is the content. Headers for this content can be specified with moreHeaders. Returns MIMEMessageContent instance.

// plain text
message.setMessage('text/plain', 'This is plain text.')

// or/and html
message.setMessage('text/html', 'This is <strong>html</strong>.')

// or in base64 encoded format
const encoded = message.toBase64('This is <strong>html</strong>.')
const headers = {'Content-Transfer-Encoding': 'base64'}
message.setMessage('text/html', encoded, headers)

.getMessageByType(type)

Returns MIMEMessageContent instance.

.setAttachment(filename, type, data, moreHeaders={})

Adds an attachment to the email. type is the mime type of the file. data should be base64 encoded content of the file. Headers for this attachment can be specified with moreHeaders. Returns MIMEMessageContent instance.

const encoded = message.toBase64( fs.readFileSync('./tests/test.jpg') )
message.setAttachment('test.jpg', 'image/jpg', encoded)

// add content id header to use the attachment inside email body
// <img src="cid:abc123">
message.setAttachment('test.jpg', 'image/jpg', encoded, {
  'Content-ID': 'abc123'
})

.getAttachments()

Returns an array of MIMEMessageContent instances.

.asRaw()

Generates and returns the RFC-2822 compliant email message. This message can be used to send an email.

.asEncoded()

Generates and returns the base64 encoded RFC-2822 compliant email message. This message also can be used to send an email.

Use Cases

Some of email services such as Amazon SES or Google Gmail may require you to create the mime message to send an email programmatically. This library built for those kind of services but mime messages already has a wide range of use cases in general.

Amazon SES with AWS-SDK

// init aws sdk
const AWS = require('aws-sdk')
const ses = new AWS.SES({region: ''})

// init mimetext
const {createMimeMessage} = require('mimetext')
const message = createMimeMessage()

// create email message
message.setSender('[e-mail]')
message.setTo('[e-mail]')
message.setSubject('Weekly Newsletter 49 Ready 🚀')
message.setAttachment('bill.pdf', 'application/pdf', data)
message.setMessage('text/html', 'Hello <b>John</b>.')

// send email with aws sdk
const params = {
  Destinations: message.getRecipients({type: 'to'}).map(mailbox => mailbox.addr),
  RawMessage: {
    Data: message.asRaw() // aws-sdk does the base64 encoding
  },
  Source: message.getSender().addr
}

ses.sendRawEmail(params, function(err, result) {
  // err or result.MessageId
})

Google Gmail with googleapis-sdk

// init google api sdk
const {google} = require('googleapis')

// create email message
const {createMimeMessage} = require('mimetext')
const message = createMimeMessage()
message.setSender('[e-mail]')
message.setTo('[e-mail]')
message.setSubject('Weekly Newsletter 49 Ready 🚀')
message.setAttachment('bill.pdf', 'application/pdf', data)
message.setMessage('text/html', 'Hello <b>John</b>.')

// send email
google.auth
  .getClient({scopes: ['https://www.googleapis.com/auth/gmail.send']})
  .then(function(client) {
    client.subject = '[e-mail]'

    const gmail = google.gmail({ version: 'v1', auth: client })

    gmail.users.messages
      .send({
        userId: 'me',
        requestBody: {
          raw: message.asEncoded()
        }
      })
      .then(function(result) {
        // result.id
      })
      .catch(function(err) {

      })
  })

Error Handling

Setter methods raise an instance MIMETextError on bad input.

try {
  message.setTo({prop: 'invalid'})
} catch (e) {
  e instanceof MIMETextError === true
  e.name === 'MIMETextError'
  e.description === 'The input should have an "addr" property that specifies ...'
}

---

Version management of this repository done by releaser 🚀

---

Thanks for watching 🐬