@designsystemsinternational/email

A collection of utilities to make working with email a bit more enjoyable.

CLI

When installed into a project (or globally) the email-cli can be used.

# Turns an HTML file into a standalone ZIP file, with all images downloaded and
# added to that ZIP file
#
# --force let's you overwrite the output file if it's already present
# --skip-preparation skips the HTML preparation and just bundles things into a ZIP
email-cli zip input.html output.zip --force --skip-preparation

# Turns an HTML file into a package and pushes everything to s3. Writes the
# updated HTML with all images pointing to s3 to output file for further use.
#
# The AWS credentials are stored in email-cli.config.js, which can be generated
# using the scaffold command below.
#
# --force overwrite the output file if it's already present
# --skip-preparation skips HTML preparation and just bundles
email-cli s3 input.html output.html --force --skip-preparation

# Packages HTML file and pushes to Mailchimp
# Mailchimp API credentials should be stored in email-cli.config.js in the
# root directory of your project.
#
# --id the mailchimp ID you want to publish at
# --skip-preparation skips the HTML preparation and just bundles things into a ZIP
email-cli mailchimp input.html --id 12345678 --skip-preparation

# Sends the content of an HTML file as a preview email
# does not perform any preparation or packaging, so make sure to run
# any packaging before
#
# The credentials for sending email (either through SMTP or SES) are stored
# in email-cli.config.js, which can be generated using the scaffold command.
#
# --method either 'smtp' or 'ses' (defaults to smtp)
email-cli send input.html --to [email protected] --from [email protected] --subject "Test email" --method smtp

# To create a basic configuration file in the current directory you can use the
# provided scaffold command
email-cli scaffold

Utilities

Alternatively you can also import the utilities into your projects. Use different entry points depending on if your in a Node or Browser environment.

// Server/Node
import {
  prapareHtml,
  packageToZip,
  packageToMailchimp,
  packageToS3,
} from '@designsystemsinternational/email';

// Browser
//
// Heads up: The browser version does not have all the packagers and does
// currently not allow for sending test emails from the client, use the server
// package in a server-less function to make your own endpoint to handle this
import {
  prapareHtml,
  packageToZip,
} from '@designsystemsinternational/email/src/browser.js';

Make your own packager

Packagers are build from a modular setup. The package exposes preparePackageFactory to allow you build your own packager. The factory sets up a method that first runs your input through the image extraction step. Processed HTML and Images are next passed to a custom packaging script to e.g. zip it, or publish it. See the following example.

import { preparePackageFactory } from '@designsystemsinternational/email';

const myPackager = preparePackageFactory({
  handlePackage: async ({ html, images }, options) => {
    // HTML is a plain string of the optimized HTML
    console.log(html);

    // Images is an array of image object of this shape
    // {
    //   filename: 'image-name.png',
    //   buffer: // node: Buffer, browser: base64 string
    // }
    console.log(images.length);

    // Options are passed in when calling the packager
    console.log(options);
  },
});

// Next, call your packager
myPackager(htmlString, { optionA: true, optionB: false });