@pdftron/ses-email-builder

A utility SDK for generating and sending emails via Amazon SES

Usage no npm install needed!

<script type="module">
  import pdftronSesEmailBuilder from 'https://cdn.skypack.dev/@pdftron/ses-email-builder';
</script>

README

AWS SES Email template builder

An isomorphic utility SDK to build and send emails via SES.

Installation

yarn add @pdftron/ses-email-builder

fetch is also required to be available as a global. If using node, you can use the isomorphic-fetch package.

Usage

The default export of this package is a factory function that returns a Class you can use throughout your app to send emails. The factory function allows you to set global styles that will be applied to all emails, and the returned class lets you set more specific details per email.

Example usage:

const factory = require('@pdftron/ses-email-builder');

const EmailBuilder = factory({
  ...defaults // see documentation below for options
})

const builder = new EmailBuilder();

builder
  .setSource('PDFTron <noreply@pdftron.com>')
  .setTo('person@gmail.com')
  .setSubject('PDFTron - Contact Sales Form Confirmation')
  .setHeader({ text: "PDFTron Systems" })
  .addText({ text: "Thank you for filling out our form! We will get back to you soon" })
  .addButtons({
    buttons: [
      {
        text: "See more info",
        to: "https://pdftron.com/webviewer"
      },
      {
        text: "Documentation",
        to: "https://pdftron.com/documentation"
      }
    ]
  })
  .send(); // send the email!

API

Any options that include a style should come in the form of a style object, similar to React

factory(defaults: Object) => EmailBuilderClass

Defaults object can contain:

  • appName The name of your application. The text in the header is defaulted to this
  • endpoint The endpoint of your AWS SES endpoint. Requests will be sent here. Required.
  • defaultEmailSource The default source of all emails
  • defaultHeaderImage A link to an image that will be included in all headers
  • defaultHeaderTextStyle The default style for the text in the header
  • defaultHeaderStyle The default style for the header div
  • defaultSubHeaderStyle The default style for the subheader dic
  • defaultSubHeaderTextStyle The default style for the subheader text
  • defaultFont The default font to use for all text
  • defaultFontColor The default font color to use for all text
  • defaultHeaderImageStyle The default style for the image in the header
  • defaultBodyStyle The default style for the overall wrapper div
  • defaultContentStyle The default style for the div wrapping the main email content (not including the headers or footer)
  • defaultLabelStyle The default style for info labels
  • defaultValueStyle The default style for info label values
  • defaultLinkStyle The default style for any links
  • defaultFooterStyle The default style for the footer div
  • defaultFooterText The default text to be displayed in the footer
  • defaultFooterTextStyle The default style for the text in the footer
  • defaultButtonStyle The default style for all buttons

Returns a reference to a EmailBuilder class

new EmailBuilderClass() => builder

Methods

Any methods that accept styles will override the defaults set in the factory.

  • builder.setDefaultFont(font: string) => this Sets the default font for this specific email

  • builder.setDefaultFontColor(color: string) => this Sets the default font color for this specific email

  • builder.setContentStyle(style: StyleObject) => this Sets the style for the content of this email

  • builder.setBodyStyle(style) => this Sets the style for the entire wrapper div

  • builder.setSource(source: string) => this Sets the source/sender of this email

  • builder.setTo(to: string|string[]) => this Sets who the email is sent to

  • builder.setSubject(subject: string) => this Sets the subject of the email

  • builder.setTextStyle(tags: string|string[], style: StyleObject) => this Sets the style for specific text tags.

Example:

// sets all the p's and h5's to red
builder.setTextStyle(['p', 'h5'], { color: 'red' })

  • builder.setHeader(options: Object) => this Sets the header of the email

    • options.text The text to be in the header
    • options.imageSource The source of the image for the header
    • options.style Style for the header div
    • options.imgStyle Style for the image in the header
    • options.textStyle Style for the text in the header

  • builder.setSubheader(options: Object) => this Sets the contents and style of the subheader

    • options.text The text to appear in the subheader
    • options.style The style to apply to the subheader div
    • options.textStyle The style to apply to the text in the subheader

  • builder.addText(options: Object) => this Adds text to the body of the email

    • options.text The text to add
    • options.tag The type of text. For example, 'p' or 'h3'
    • options.textStyle The style of the text

  • builder.addCustom(html: string) => this Adds a custom HTML string to the body

  • builder.addLineBreak() => this Adds a line break to the body

  • builder.addInfoItem(options: Object) => this Adds a nicely diaplayed key value pair to the email body

    • options.label The label of the data
    • options.value The value of the data
    • options.labelTag The tag to use for the label
    • options.valueTag The tag to use for the value
    • options.labelStyle Style for the label
    • options.valueStyle Style for the value

  • builder.addButtons(options: Object) => this Adds a row of buttons to the email body

    • options.buttons An array of buttons to add. Each button can have a text, to, and style property.
    • options.wrapperStyle Style to apply to the whole wrapper div

  • builder.addJSON(options: Object) => this Renders a bunch of info label corrosponding to a JSON object. Loops over the addInfoItem API.

    • options.data A non-nested object containing key value pairs to render.
    • options.labelTag The tag to use for the labels
    • options.valueTag The tag to use for the values
    • options.labelStyle Style for the labels
    • options.valueStyle Style for the values

  • builder.setFooter(options: Object) => this Sets the footer of the email

    • options.text The text to render in the footer
    • options.style The style to apply to the footer div
    • options.textStyle Style to apply to the footer text

  • builder.getHTML() => string Returns the HTML contents of the email. Used mostly for debugging.

  • builder.get() => Object Returns the entire SES data structure of the email. Used mostly for debugging.

  • builder.send() => Promise<Response> Sends the email

Statics

EmailBuilderClass.link(options: Object) => string Creates an inline link element that can inserted into other text

  • options.text The text of the link
  • options.to Where the link points to
  • options.style Style for the link

Example

builder.addText({
  text: `View documentation ${EmailBuilder.link({
    text: 'here',
    to: 'http://pdftron.com/documentation',
  })}`
})