Postmark

medusa-plugin-postmark

Notifications plugin for Medusa ecommerce server that sends transactional emails via PostMark.

Features

• Uses the email templating features built into Postmark
• You can import/use tools like stripo.email
• The plugin is in active development. If you have any feature requests, please open an issue.
• Create PDF invoices and credit notes and attach them to the email
• Send out upsell emails to customers that have recently placed an order with certain collections
• Send out automated abandoned cart emails to customers that have abandoned their cart (based on last updated date of cart)

Configuration

Enable in your medusa-config.js file similar to other plugins:

More events? (work in progress within the plugin!) See here

1234567891011121314151617181920
const plugins = [
    // ... other plugins
    {
        resolve: `medusa-plugin-postmark`,
        options: {
            server_api: process.env.POSTMARK_SERVER_API,
            from: process.env.POSTMARK_FROM,
            bcc: process.env.POSTMARK_BCC || null,
            pdf: {
                enabled: process.env.POSTMARK_PDF_ENABLED || false,
                settings: {
                    font: process.env.POSTMARK_PDF_FONT || 'Helvetica', 
                    // [{file: 'yourfont.ttf', name: 'yourfont'},{file: 'yourfont-bold.ttf', name: 'yourfontbold'}]
                    format: process.env.POSTMARK_PDF_FORMAT || 'A4', 
                    // see supported formats here: https://pdfkit.org/docs/paper_sizes.html
                    margin: {
                        top: process.env.POSTMARK_PDF_MARGIN_TOP || '50',
                        right: process.env.POSTMARK_PDF_MARGIN_RIGHT || '50',
                        bottom: process.env.POSTMARK_PDF_MARGIN_BOTTOM || '50',
                        left: process.env.POSTMARK_PDF_MARGIN_LEFT || '50'

Templates

The plugin uses the Postmark template system for emails. For attachments the plugin relies on the pdfkit library.
In your JSON templates you can use several types (and variables):

• Copy to clipboardimage for (local) images
• Copy to clipboardtext for simple words, (long) sentences, paragraphs and links
• Copy to clipboardmoveDown for moving the cursor down one line
• Copy to clipboardhr for a horizontal line
• Copy to clipboardtableRow for a table(-like) row
• Copy to clipboarditemLoop for looping over items in an order
• Copy to clipboarditemLoopEnd for ending the item loop

Example:

1234567891011121314151617181920
[
  {
    "type": "image",
    "image": "image.png",
    "x": 100,
    "y": 100,
    "fit": [200, 50]
  },
  {
    "type": "text",
    "text": "This is a text",
    "size": 20
  },
  {
    "type": "moveDown",
    "lines": 2
  },
  {
    "type": "hr"
  },

image

Images are stored in Copy to clipboard/src/images/ and can be used in the template like this:

1234567
{
    "type": "image",
    "image": "image.png",
    "x": 100,
    "y": 100,
    "fit": [200, 50]
}

Copy to clipboardfit has multiple options, see here for more info.

Optional:

• Copy to clipboardalign horizontally align the image, the possible values are Copy to clipboardleft, Copy to clipboardcenter, or Copy to clipboardright
• Copy to clipboardvalign vertically align the image, the possible values are Copy to clipboardtop, Copy to clipboardcenter, or Copy to clipboardbottom

text

Text can be used for words, sentences, paragraphs and links.

1234
{
    "type": "text",
    "text": "This is a text"
}

If you use Copy to clipboardmoveDown correct you won't need to use Copy to clipboardx and Copy to clipboardy for the text.

Optional:

These options can be used to style the text or to position it.

• Copy to clipboardx the x position of the text
• Copy to clipboardy the y position of the text
• Copy to clipboardfont the font of the text
• Copy to clipboardsize the font size of the text
• Copy to clipboardcolor the color of the text (Hex codes Copy to clipboard#ff0000)
• Copy to clipboardwidth the width of the text
• Copy to clipboardalign the alignment of the text, the possible values are Copy to clipboardleft, Copy to clipboardcenter, Copy to clipboardright, or Copy to clipboardjustify.

For more styling options, see here for more info.

moveDown

This is used to move the cursor down one or more line(s).

1234
{
    "type": "moveDown",
    "lines": 1
}

hr

This is used to draw a horizontal line.

123
{
    "type": "hr"
}

Optional:

• Copy to clipboardcolor the color of the line (Hex codes Copy to clipboard#ff0000)
• Copy to clipboardwidth the width of the line if you don't want it to be the full width of the page
• Copy to clipboardheight the height of the line element, including padding
• Copy to clipboardy the y position of the line if you can not rely on the cursor (affected by Copy to clipboardmoveDown)

tableRow

This is used to draw a table row.

12345678910111213
{
    "type": "tableRow",
    "columns": [
        {
            "text": "Column 1",
            "width": 200
        },
        {
            "text": "Column 2",
            "width": 150
        }
    ]
}

Optional:

You can use the same options as for Copy to clipboardtext to style the text in the table row. If you want a special column styled, you can add the options to the column object.

itemLoop

This is used to start the loop of items in an order.
To access item variables, use the Copy to clipboarditem object, for example Copy to clipboard{{ item.title }}.

123
{
    "type": "itemLoop"
}

itemLoopEnd

This is used to end the loop of items in an order.

123
{
    "type": "itemLoopEnd"
}

Variables

In the template you can use variables. These are replaced by the plugin with the correct value.
To use a variable, use the following syntax: Copy to clipboard{{ variable_name }}, for example Copy to clipboard{{ order.customer.first_name }}.
Order item variables are available inside the Copy to clipboarditemLoop and Copy to clipboarditemLoopEnd elements, for example Copy to clipboard{{ item.title }}.
If you want to include (simple) if statements, use the following syntax: Copy to clipboard{{ if variable_name }}...{{ endif }}, or as a negative Copy to clipboard{{ if not variable_name }}...{{ endif }}.
Possible variables depend on your notification system. You can use the Copy to clipboardoptions object and every template has his own Copy to clipboarddata object.
Depending on the plugin you use, (almost) every plugin that supports attachments based on Copy to clipboardmedusa-plugin-sendgrid has the same variable Copy to clipboardorder after the Copy to clipboardoptions variable which holds all the plugin variables.
More information on the possible values that Copy to clipboardorder can have can be found here.

Variable functions

At the moment the only variable you can use functions with is dates and currency.

• Dates are formatted using the Copy to clipboardtoLocaleDateString function and can be used like this: Copy to clipboard{{ order.placed_at | date('en-US',{'year': 'numeric', 'month': 'long', 'day': 'numeric'}) }}.
• Currency is formatted using the Copy to clipboardnew Intl.NumberFormat() function and can be used like this: Copy to clipboard{{ order.total_price | currency('en-US') }}.
• Country can be formatted from ISO to the full country name and can be used like this: Copy to clipboard{{ order.shipping_address.country_code | country }}.
  Please make sure that the options are wrapped in single quotes.

Localisation

Want separate templates for different languages?
Alter medusa-config.js plugin options:

12345
// medusa config including the postmark plugin
events: {
    order: {
        placed: { nl: 1234, en: 1235 },
// rest of the events...

The api key and templates are pulled from env variables.

123
POSTMARK_SERVER_API=""
POSTMARK_FROM=""
POSTMARK_ORDER_PLACED=1234

The Copy to clipboardPOSTMARK_FROM email address must be a verified sender in your Postmark account.

Default templates

We've created a few default templates (thanks to pdfkit invoice example) which can be altered to your needs: Copy to clipboardheader.json

1234567891011121314151617181920
[
  {
    "type": "text",
    "text": "ACME Inc.",
    "size": 20,
    "color": "#444444"
  },
  {
    "type": "text",
    "text": "ACME Inc.",
    "size": 10,
    "color": "#444444",
    "align": "right",
    "x": 200
  },
  {
    "type": "moveDown"
  },
  {
    "type": "text",

Copy to clipboardcreateInvoice.json

1234567891011121314151617181920
[
  {
    "type": "text",
    "text": "Invoice",
    "size": 20,
    "color": "#444444"
  },
  {
    "type": "moveDown"
  },
  {
    "type": "hr"
  },
  {
    "type": "text",
    "text": "Invoice Number:",
    "size": 10
  },
  {
    "type": "text",

Copy to clipboardfooter.json

12345678910
[
  {
    "type": "text",
    "text": "Thank you for your business!",
    "size": 10,
    "color": "#444444",
    "width": "full",
    "align": "center"
  }
]

Acknowledgement

This plugin is originally based on medusa-plugin-sendgrid by Oliver Juhl.