https://github.com/muratgozel/mimetext
RFC-5322 compliant, fully typed and documented email message generator for javascript runtimes.
https://github.com/muratgozel/mimetext
amazon-ses attachment email email-attachments email-message-header email-parsing mime-message mimetext nodejs-library rfc-2045 rfc-2049 rfc-2822
Last synced: 5 days ago
JSON representation
RFC-5322 compliant, fully typed and documented email message generator for javascript runtimes.
- Host: GitHub
- URL: https://github.com/muratgozel/mimetext
- Owner: muratgozel
- License: mit
- Created: 2019-06-26T20:58:22.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2025-01-02T13:27:12.000Z (5 months ago)
- Last Synced: 2025-03-31T20:11:17.863Z (about 2 months ago)
- Topics: amazon-ses, attachment, email, email-attachments, email-message-header, email-parsing, mime-message, mimetext, nodejs-library, rfc-2045, rfc-2049, rfc-2822
- Language: TypeScript
- Homepage:
- Size: 3.04 MB
- Stars: 94
- Watchers: 2
- Forks: 36
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# MIMEText
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
### npm
It's published on [npm](https://www.npmjs.com/package/mimetext). Any package manager compatible with it, should work:
```sh
npm i mimetext
# or
pnpm add mimetext
# or
yarn add mimetext
```
### Standalone Browser Script
There is an [iife version](dist/mimetext.iife.js) (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
console.log(window.MimeText)
```
### Google Apps Script
There is a special export that is compatible with Google Apps Script environment. Use [gas.cjs](https://github.com/muratgozel/MIMEText/blob/master/dist/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')
```
### Simple Email Message
Here is a simple plain text email message:
```js
import { createMimeMessage } from 'mimetext'
const msg = createMimeMessage()
msg.setSender({name: 'Lorem Ipsum', addr: '[email protected]'})
msg.setRecipient('[email protected]')
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.
*/
```
### APIs for Adding Different Kind and Way of Recipients
```js
msg.setTo('[email protected]')
msg.setCc('[email protected]')
msg.setBcc('[email protected]')
// "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: '[email protected]',
name: 'Firstname Lastname',
type: 'Bcc'
})
// multiple recipients, each as argument
msg.setRecipients(
'[email protected]',
'Firstname Lastname ',
{addr: '[email protected]'}
)
```
### HTML Message With Plain Text Fallback And Attachments
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('[email protected]')
msg.setRecipients('[email protected]')
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--
*/
```
### Encoding The Output
Service providers may ask for the encoded version of a message. In that case use the `.asEncoded()` 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.
### Amazon SES with AWS-SDK Client V1
```js
// install with npm i @aws-sdk/client-ses
const { 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('[email protected]')
message.setTo('[email protected]')
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
```
### Amazon SES with AWS-SDK Client V2
```js
// install with npm i @aws-sdk/client-sesv2
const { 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('[email protected]')
message.setTo('[email protected]')
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
```
### Google Gmail with googleapis-sdk
```js
// init google api sdk
const {google} = require('googleapis')
const {createMimeMessage} = require('mimetext')
const message = createMimeMessage()
message.setSender('[email protected]')
message.setTo('[email protected]')
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 = '[email protected]'
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 `MIMETextError` 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](https://datatracker.ietf.org/doc/html/rfc5322)
- [RFC-2045](https://datatracker.ietf.org/doc/html/rfc2045)
- [RFC-2046](https://datatracker.ietf.org/doc/html/rfc2046)
- [RFC-2047](https://datatracker.ietf.org/doc/html/rfc2047)
- [RFC-2048](https://datatracker.ietf.org/doc/html/rfc2048)
- [RFC-2049](https://datatracker.ietf.org/doc/html/rfc2049)
## Contributing
If you're interested in contributing, read the [CONTRIBUTING.md](https://github.com/muratgozel/muratgozel/blob/main/CONTRIBUTING.md) first, please.
---
Thanks for the attention 💙 Any amount of support on [patreon](https://patreon.com/muratgozel?utm_medium=organic&utm_source=github_repo&utm_campaign=github&utm_content=join_link) or [github](https://github.com/sponsors/muratgozel) will return you back as bug fixes, new features and bits and bytes.