Gathering detailed insights and metrics for markdown-email
Gathering detailed insights and metrics for markdown-email
Installations
npm install markdown-emailDeveloper Guide
BETA
Typescript
No
Module System
ESM
Node Version
18.17.1
NPM Version
9.8.1
Releases
Unable to fetch releases
Languages
2
TypeScript
JavaScript
TypeScript (88.52%)
JavaScript (11.48%)
Developer
joeskeen
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
2 Commits
1 Watchers
1 Branches
1 Contributors
Updated on Feb 24, 2024
Maintainers
1
Package Meta Information
Latest Version
1.0.1
Package Id
markdown-email@1.0.1
Unpacked Size
27.03 kB
Size
7.04 kB
File Count
22
NPM Version
9.8.1
Node Version
18.17.1
Published on
Feb 24, 2024
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
markdown-email
markdown-email is an opinionated library to transform a markdown file as an EJS
template into an HTML email, ready to send.
It is designed to be used with nodemailer to send emails, but it can be adapted to be
used with any email sending library.
I wrote this because I have had to send a lot of automated emails in my career, and I have found that it is very easy to make mistakes which make each email inconsistent with the next, flag your email as spam or, don't work well with your recipient's email client.
This library is designed to make it easier to send emails that look good, are consistent, and are less likely to be flagged as spam.
This library has been tested against mailtrap.io's email testing feature, and it passes both the HTML check and spam analysis. Of course, how well your email does depends on your template content. Check https://www.caniemail.com/ to see what HTML and CSS features you can use in your email.
Installation
1npm install markdown-email
Usage
1import {renderEmail} from 'markdown-email'; 2import {readFileSync} from 'fs'; 3import { createTransport } from 'nodemailer'; 4 5// You want to make all your messages have a consistent look. 6// Create a template for your email messages. The message-specific content will 7// be inserted into the start of the <body> tag. This string can contain EJS 8// expressions. 9const html = readFileSync('path/to/html-template.html', 'utf8').toString(); 10 11// You can also include CSS in your template. 12// Make sure you check that the CSS properties you use are supported by the email 13// clients you are targeting. 14const css = readFileSync('path/to/css.css', 'utf8').toString(); 15 16// Read the message template from a Markdown file. This file can contain EJS 17// expressions. 18const messageTemplate = readFileSync('path/to/template.md', 'utf8').toString(); 19 20// this contains all the variables that are needed to render the template. 21// Make sure you populate this object with every value needed for the EJS templates, 22// or the rendering will fail (better fail here than send out a bad email). 23const messageContext = { 24 recipientName: 'John Doe', 25 message: 'Hello, world!', 26 alertDate: new Date(), 27 productName: 'Acme Widget' 28}; 29 30// Render the EJS templates, transform the Markdown to HTML, insert 31// it into the HTML template, and inline the CSS. 32const {subject, message, attachments} = await renderEmail(messageTemplate, messageContext{ 33 surroundingHtml: html, 34 styles: css 35}); 36 37const transport = createTransport({ 38 host: 'smtp.example.com', 39 port: 587 40 // ... 41}); 42await transport.sendMail({ 43 from: 'your-send-address@example.com', 44 to: 'your-recipient-address@example.com', 45 subject: subject, 46 html: message, 47 attachments: attachments 48});
See src/test/e2e.mjs for a complete example.
Creating templates
You can use EJS expressions in your templates, including the message template as
well as the email HTML. When referencing variables from the provided context, prefix them with $..
For example:
1const markdown = `Hello <%= $.name %>, this is a message for you!`; 2const context = {name: 'John Doe'};
Template validation at runtime
It is also important that the context object contains every variable that is used in the templates. If a referenced value is not found in the context, the rendering will fail with an error. For example:
1const markdown = `Hello <%= $.name %>, this is a message for you!`; 2const context = {}; 3const output = await renderEmail(markdown, context);
Will result in the following error:
1 throw new Error(`Missing required property ${name}`); 2 ^ 3 4Error: ejs:1 5 >> 1| Hello <%= $.name %>, this is a message for you! 6 7Missing required property name
Subject
You can also include the message subject in your template. If you do, it will be templated, extracted, removed from the message, and returned as part of the result. For example:
1const markdown = ` 2% subject Hello <%= $.name %> 3 4This is a message for you! 5`; 6const context = {name: 'John Doe'}; 7const output = await renderEmail(markdown, context); 8console.log(output.subject); // "Hello John Doe" 9console.log(output.message); // "This is a message for you!"
Images
If you include images anywhere in your message (Markdown or HTML), they will be
base64-encoded and included as attachments in the result. The img tags will
automatically be updated to reference the attachment. For example:
1const markdown = ` 2 3`; 4const output = await renderEmail(markdown, {}); 5console.log(output.message); // "<img src='cid:(some generated id)' alt='My Image'>" 6console.log(output.attachments); // [{filename: 'image.png', path: '(some base64 string)', cid: '(some generated id)'}]
No vulnerabilities found.
No security vulnerabilities found.