Quickly generate or send styled email notifications from your NodeJS applications.
Table of Contents
- Install Package
- Getting Started
- Options
- Create styled email HTML & Text
- Sanitizing your input
- Using Content Blocks
- How do I send my email?
Install Package
NPM:
npm install --save @sendfern/mail
Yarn:
yarn add @sendfern/mail
Getting started
Use this example, and modify the name
field to be your company/team/sender name:
import { emailHtml } from '@sendfern/mail';
const html = emailHtml({
content: [
'This is a live preview of your emails! Customize my appearance using <a target="_blank" href="https://sendfern.com">Sendfern</a>.',
{
type: 'button',
link: 'https://example.com',
label: 'Example Button',
},
],
name: "* Sender name *",
});
// Use nodemailer or a similar solution to send this html to your recipient, or consider checking out our service https://sendfern.com if you don't want to send your own emails.
Becomes:
Options
Type: object
content
Required
Type: array | string
The contents of your email, this can a basic string of text, or an array of content blocks. Examples of content blocks provided below.
name
Required
Type: string
The name of your company, team, or sender. This will show in the email footer, and at the top of the email if no logo is provided.
disableDarkMode
optional
Type: boolean
Default: false
If set to true, the dark-mode specific styling will be disabled.
footerContent
optional
Type: string
Add text or HTML to the email footer.
preview
optional
Type: string
If provided, we will include this as the email preheader.
logo
optional
Type: string
The https URL to your logo image. Will show at the top of the email.
website
optional
Type: string
The https URL to your website. If provided. The email header will be wrapped in a link to this URL.
brandColor
optional
Type: string
Default: #3b82f6
The hex color used for styled elements such as buttons and links.
logoWidth
optional
Type: number
Default: 200
The width of the logo in pixels.
theme
optional
Type: string
Possible Values: plain | modern | minimal | basic
Default: basic
The theme determines how your email is styled:
basic
modern
minimal
plain
More themes will be added over time :)
hasMarketing
optional
Type: boolean
Default: false
If set to true, your business address and unsubscribe link will be shown in the email footer. We recommend enabling this if you intend to send marketing/promotional emails.
streetAddress1
optional
Type: string
First line street address. Will be used if hasMarketing = true.
streetAddress2
optional
Type: string
First line street address. Will be used if hasMarketing = true.
city
optional
Type: string
City. Will be used if hasMarketing = true.
region
optional
Type: string
Region. Will be used if hasMarketing = true.
zip
optional
Type: string
Zip/postal code. Will be used if hasMarketing = true.
country
optional
Type: string
Country. Will be used if hasMarketing = true.
unsubscribeLink
optional
Type: string
The URL to direct users to if they opt to unsubscribe from your mailing. Will be used if hasMarketing = true.
showReferrer
optional
Type: string
Default: false
Adds "Powered by Sendfern" to your email footer.
Create styled email HTML & Text
You can generate the text version of your email as well
import { emailHtml, emailText } from '@sendfern/mail';
const html = emailHtml({
content: "This is an example email notification!",
name: "* Sender name *",
});
const text = emailText({
content: "This is an example email notification!",
name: "* Sender name *",
});
Sanitizing your input
Use formatEmailData
to sanitize your options:
import { emailHtml, formatEmailData } from '@sendfern/mail';
const html = emailHtml(formatEmailData({
content: "This is an example email notification!",
name: "* Sender name *",
}));
Using Content Blocks
To use content blocks, pass an array instead of a string into the content
field. This array can either include objects representing content blocks or a string (shorthand for a text block)
import { emailHtml, formatEmailData } from '@sendfern/mail';
const html = emailHtml(formatEmailData({
content: [
'This is a live preview of your emails! Customize my appearance using <a target="_blank" href="https://sendfern.com">Sendfern</a>.',
{
type: 'button',
link: 'https://example.com',
label: 'Example Button',
},
],
name: "14all",
}));
Becomes:
Text block
Displays basic text.
type
required
Value: text
content
required
Type: string
The text to display
subdued
optional
Type: boolean
Default: false
If set to true, the text block will be a smaller font size and slightly lighter color.
{
type: 'text',
content: 'Example text block',
}
or
"Shorthand text block"
Button block
Displays a button. Will use the brandColor as the background color for the button.
type
required
Value: button
label
optional
Type: string
Default: Learn More
The button text.
link
optional
Type: string
Default: #
The https URL for the button link.
{
type: 'button',
label: 'Click Me',
link: 'https://example.com'
}
Image block
Displays an image.
type
required
Value: image
width
optional
Type: number
The width of the image in pixels. If not set, will default to 100%.
link
optional
Type: string
If the provided, the image will be wrapped in the provided https URL.
source
required
Type: string
The https URL link to the image.
alt
optional
Type: string
The alternative text for the image.
{
type: 'image',
source: 'https://example.com/image.png',
width: 280,
alt: 'My image alternative text',
link: 'https://example.com'
}
Divider block
Displays a divider (hr element).
type
required
Value: divider
{
type: 'divider'
}
Spacer block
Adds empty space
type
required
Value: spacer
{
type: 'spacer'
}
Code block
Adds a highlighted code block for pin codes, secret phrases, etc.
type
required
Value: code
content
required
Type: string
The text to display
{
type: 'code',
content: 'my-magic-code'
}
Heading block
Adds a text heading
type
required
Value: heading
content
required
Type: string
The text to display
headingType
optional
Type: string
Default: h2
Possible Values: h1 | h2 | h3 | h4 | h5 | h6
The heading type/size to use.
{
type: 'heading',
content: 'My Heading',
headingType: 'h4'
}
List block
Adds a list.
type
required
Value: list
ordered
optional
Type: boolean
Default: false
Whether or not to show the list as ordered or unordered.
items
required
Type: array
An array of string
values for each bullet point.
{
type: 'list',
ordered: true,
items: [
'List item 1',
'List item 2',
'List item 3'
]
}
How do I send my email?
If you don't want to handle sending your emails with nodemailer or similar solutions, consider checking out our email service at Sendfern.