mimetext
v3.0.28TypeScript
RFC-5322 compliant, fully typed and documented email message generator for javascript runtimes
0/weekUpdated 1 weeks agoMITUnpacked: 729.1 KB
Published by Murat Gözel
npm install mimetextMIMEText
RFC-5322 compliant, fully typed and documented email message generator for javascript runtimes.
> Earlier specification RFC-2822 obsoleted by RFC-5322, therefore this library aims to be fully compliant with RFC-5322 and it's decendant specifications.
Installation
$3
It's published on npm. Any package manager compatible with it, should work:
``
sh
npm i mimetext
or
pnpm add mimetext
or
yarn add mimetext
`$3
There is an iife version (immediatly invoked function). This file includes polyfills and transforms that is neccessary to work on almost all browsers. Use it in your html documents but be aware of its size (~50kb).
html
`$3
There is a special export that is compatible with Google Apps Script environment. Use gas.cjs as necessary.Usage
The code is optimized for different environments such as node, browser and gas (Google Apps Script). Therefore, the library has three corresponding exports:
ts
import { createMimeMessage } from 'mimetext/node'
import { createMimeMessage } from 'mimetext/browser'
import { createMimeMessage } from 'mimetext/gas'
// defaults to node export
import { createMimeMessage } from 'mimetext'
`
They all have the same API but minor internal differences. Apart from environment, it can be imported as commonjs module too:
ts
const { createMimeMessage } = require('mimetext')
const { createMimeMessage } = require('mimetext')
const { createMimeMessage } = require('mimetext')
// defaults to node export
const { createMimeMessage } = require('mimetext')
`$3
Here is a simple plain text email message:
js
import { createMimeMessage } from 'mimetext'const msg = createMimeMessage()
msg.setSender({name: 'Lorem Ipsum', addr: 'lorem@ipsum.com'})
msg.setRecipient('foobor@test.com')
msg.setSubject('🚀 Issue 49!')
msg.addMessage({
contentType: 'text/plain',
data:
Hi,I'm a simple text.
})
const raw = msg.asRaw()/*
Date: Sun, 24 Oct 2021 04:50:32 +0000
From: "Lorem Ipsum"
To:
Message-ID:
Subject: =?utf-8?B?8J+agCBJc3N1ZSA0OSE=?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Hi,
I'm a simple text.
*/
$3
js
msg.setTo('first@last.com')
msg.setCc('first@last.com')
msg.setBcc('first@last.com')// "To" by default
msg.setRecipient('Firstname Lastname ')
// but you can still specify other kinds
msg.setRecipient('Firstname Lastname ', {type: 'Cc'})
// all as object
msg.setRecipient({
addr: 'first@last.com',
name: 'Firstname Lastname',
type: 'Bcc'
})
// multiple recipients, each as argument
msg.setRecipients(
'test@mail.com',
'Firstname Lastname ',
{addr: 'multiple@mail.com'}
)
`$3
Both html and plain text version of a message can be set and attachments can be added. Here is a more complex example:
js
const msg = createMimeMessage()msg.setSender('sender@mail.com')
msg.setRecipients('recipient@mail.com')
msg.setSubject('Testing MimeText 🐬 (Plain Text + HTML With Mixed Attachments)')
msg.addMessage({
contentType: 'text/plain',
data: 'Hello there,' + EOL + EOL +
'This is a test email sent by MimeText test suite.'
})
msg.addMessage({
contentType: 'text/html',
data: 'Hello there,
' +
'This is a test email sent by MimeText test suite.
' +
'The term MimeText above supposed to be bold. Are you able to see it?
' +
'Below, there should be a small image that contains little black dots:
' +
// using an inline attachment id here:
'
' +
'Best regards.'
})
// and the inline attachment:
msg.addAttachment({
inline: true,
filename: 'dots.jpg',
contentType: 'image/jpg',
data: '...base64 encoded data...',
headers: {'Content-ID': 'dots123456'}
})
// two more attachments but they aren't inlined, they are attached
msg.addAttachment({
filename: 'sample.jpg',
contentType: 'image/jpg',
data: '...base64 encoded data...'
})
msg.addAttachment({
filename: 'sample.txt',
contentType: 'text/plain',
data: '...base64 encoded data...'
})
const raw = msg.asRaw()
/*
Date: Sun, 26 Mar 2023 13:27:15 +0000
From:
To:
Message-ID:
Subject: =?utf-8?B?VGVzdGluZyBNaW1lVGV4dCDwn5CsIChQbGFpbiBUZXh0ICsgSFRNTCBXaXRoIE1peGVkIEF0dGFjaG1lbnRzKQ==?=
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary=giev1zqo579
--giev1zqo579
Content-Type: multipart/related; boundary=hl6rtnn5jq
--hl6rtnn5jq
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 7bit
Hello there,
This is a test email sent by MimeText test suite.
The term MimeText above supposed to be bold. Are you able to see it?
Below, there should be a small image that contains little black dots:
Best regards.
--hl6rtnn5jq
Content-ID:
Content-Type: image/jpg; name="dots.jpg"
Content-Transfer-Encoding: base64
Content-Disposition: inline; filename="dots.jpg"
/9j/4AAQSkZJRgABAgEASABIAAD/2wCEAAEBAQEBAQEBAQEBAQEBAQ...........BPwAp/9k=
--hl6rtnn5jq--
--giev1zqo579
Content-Type: image/jpg; name="sample.jpg"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="sample.jpg"
/9j/4AAQSkZJRgABAg...........befPb4N8Hn4A/9k=
--giev1zqo579
Content-Type: text/plain; name="sample.txt"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="sample.txt"
SGVsbG8gdGhlcmUu
--giev1zqo579--
*/
`$3
Service providers may ask for the encoded version of a message. In that case use the call instead of .asRaw():
`ts
// base64-websafe encoded message
// it first gets the raw version and then encodes it.
msg.asEncoded()
`Use Cases
- Email delivery services might ask you to prepare an email message in raw format before sending it with their email client.
- When email message testing or parsing needed.
- Preference.Here are two examples that uses Amazon SES and Google Gmail for email sending.
$3
js
// install with npm i @aws-sdk/client-sesconst { SESClient, SendRawEmailCommand } = require('@aws-sdk/client-ses')
const ses = new SESClient({ region: 'YOUR_REGION' })
const { Buffer } = require('node:buffer')
const { createMimeMessage } = require('mimetext')
const message = createMimeMessage()
message.setSender('sender@email.com')
message.setTo('person1@email.com')
message.setSubject('Weekly Newsletter 49 Ready 🚀')
message.addAttachment({
filename: 'bill.pdf',
contentType: 'application/pdf',
data: '...base64 encoded data...'
})
message.addMessage({
contentType: 'text/html',
data: 'Hello John.'
})
// send
const params = {
Destinations: message.getRecipients({type: 'to'})
.map(mailbox => mailbox.addr),
RawMessage: {
// the raw message data needs to be sent as uint8array
Data: Buffer.from(message.asRaw(), 'utf8')
},
Source: message.getSender().addr
}
const result = await ses.send(new SendRawEmailCommand(params))
// expect result.MessageId
`$3
js
// install with npm i @aws-sdk/client-sesv2const { SESv2Client, SendEmailCommand } = require('@aws-sdk/client-ses')
const ses = new SESv2Client({ region: 'YOUR_REGION' })
const { Buffer } = require('node:buffer')
const { createMimeMessage } = require('mimetext')
const message = createMimeMessage()
message.setSender('sender@email.com')
message.setTo('person1@email.com')
message.setSubject('Weekly Newsletter 49 Ready 🚀')
message.addAttachment({
filename: 'bill.pdf',
contentType: 'application/pdf',
data: '...base64 encoded data...'
})
message.addMessage({
contentType: 'text/html',
data: 'Hello John.'
})
const params = {
FromEmailAddress: message.getSender().addr,
Destination: {
ToAddresses: message.getRecipients()
.map((box) => box.addr)
},
Content: {
Raw: {
Data: Buffer.from(message.asRaw(), 'utf8')
}
}
}
const result = await ses.send(new SendEmailCommand(params))
// result.MessageId
`$3
js
// init google api sdk
const {google} = require('googleapis')
const {createMimeMessage} = require('mimetext')const message = createMimeMessage()
message.setSender('sender@email.com')
message.setTo('person1@email.com')
message.setSubject('Weekly Newsletter 49 Ready 🚀')
message.addAttachment({
filename: 'bill.pdf',
contentType: 'application/pdf',
data: '...base64 encoded data...'
})
message.addMessage({
contentType: 'text/html',
data: 'Hello John.'
})
// send
google.auth
.getClient({scopes: ['https://www.googleapis.com/auth/gmail.send']})
.then(function(client) {
client.subject = 'sender@email.com'
const gmail = google.gmail({ version: 'v1', auth: client })
gmail.users.messages
.send({
userId: 'me',
requestBody: {
raw: message.asEncoded()
}
})
.then(function(result) {
// expect result.id
})
.catch(function(err) {
})
})
`Error Handling
Most of the methods raises in case of invalid input. You can catch and handle them accordingly.
`js
try {
message.setTo({prop: 'invalid'})
} catch (e) {
e instanceof MIMETextError === true
}
``Relevant Specifications
- RFC-5322
- RFC-2045
- RFC-2046
- RFC-2047
- RFC-2048
- RFC-2049
Contributing
If you're interested in contributing, read the CONTRIBUTING.md first, please.
---
Thanks for the attention 💙 Any amount of support on patreon or github will return you back as bug fixes, new features and bits and bytes.