Quickly generate or send styled email notifications from your NodeJS applications.

Table of Contents

1. Install Package
2. Getting Started
3. Options
4. Create styled email HTML & Text
5. Sanitizing your input
6. Using Content Blocks
7. 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.