grunt-postmark

grunt-postmark

Send emails through Postmark using GruntJS. You can use this to test your email templates.

Getting Started

This plugin requires that you have a Postmark account.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-postmark --save-dev

After the plugin is installed, it can be enabled in your Gruntfile:

grunt.loadNpmTasks('grunt-postmark');

You'll need to add a config.json and a secrets.json per the mailmason configuration.

Postmark task

Run this task with the grunt postmark command.

Options

serverToken

Your server token can be found on your server’s credentials page on Postmark’s app.

Type: String

from

This is the from address you are using to send the email. This must be a confirmed address that's set up on Postmark’s sender signatures.

Type: String

to

The address you’re sending to.

Type: String

subject

Type: String

Examples

Options specified through target

grunt.initConfig({
  postmark: {
     email: {
       serverToken: 'POSTMARK_API_TEST',
       from: '[e-mail]',
       to: '[e-mail]',
       subject: 'Yo',
       src: ['test/email.html']
     }
   }
});

Specify options through targets or globally

Options specified through a target will always take precedence over global options.

grunt.initConfig({
  postmark: {
     options: {
       serverToken: 'POSTMARK_API_TEST',
       from: '[e-mail]',
       to: '[e-mail]',
       subject: 'Yo'
     },
     email: {
       to: '[e-mail]',
       src: ['test/email.html']
     },
     digest: {
       subject: 'Yo',
       src: ['test/email.html', 'test/email2.html']
     }
   }
});

Postmark templates task

Run this task with the grunt postmark-templates command.

The postmark-templates task is an alias of the postmark-templates-from-targets task which is itself a two stepped task – postmark-templates-upload followed by postmark-templates-output.

postmark-templates (postmark-templates-from-targets) is intended for programmatic usage from other grunt tasks.

postmark-templates-upload Targets

name

The name of your template.

Type: String

subject

The subject line of your template.

Type: String

htmlSrc

A path to the generated HTML for your template. Not used if htmlBody is specified.

Type: String

textSrc

A path to the generated plain text for your template. Not used if textBody is specified.

Type: String

htmlBody

The generated HTML content of your template. Not required if htmlSrc is specified.

Type: String

textBody

The generated plain text content of your template. Not required if textSrc is specified.

Type: String

postmark-templates-upload Options

serverToken

Your server token can be found on your server’s credentials page on Postmark’s app.

Type: String

ephemeralUploadResultsProperty

This is the name of a temporary grunt task configuration property used to communicate the upload results between postmark-templates-upload and postmark-templates-output without having to write a temporary file. This should be the same value as ephemeralUploadResultsProperty for postmark-templates-output.

Type: String

postmark-templates-output Options

outputFile

The name of a file to output the results of the upload to Postmark.

Type: String

cleanOutput

If true, do not export htmlBody, htmlSrc, textBody or textSrc in the specified outputFile.

Type: Boolean

ephemeralUploadResultsProperty

This is the name of a temporary grunt task configuration property used to communicate the upload results between postmark-templates-upload and postmark-templates-output without having to write a temporary file. This should be the same value as ephemeralUploadResultsProperty for postmark-templates-upload.

Type: String

Example

grunt.initConfig({
  'postmark-templates-upload': {
    options: {
      serverToken: 'POSTMARK_API_TEST',
      ephemeralUploadResultsProperty: 'temp'
    },
    test_email: {
      name: 'testing-postmark-templates-js1',
      subject: 'Testing grunt-postmark-templates',
      htmlSrc: 'test/email.html',
      textSrc: 'test/email.txt'
    },
    test_email_inline_body: {
      name: 'testing-postmark-templates-js3',
      subject: 'Testing grunt-postmark-templates (inline body)',
      htmlBody: '<html><body><h1>Another email test</h1></body></html>',
      textBody: 'Hello from grunt-postmark-templates\n'
    }
  },
  'postmark-templates-output': {
    options: {
        cleanOutput: true,
        outputFile: 'templates.json',
        ephemeralUploadResultsProperty: 'temp'
    }
  }
});

Postmark templates (from file) task

Run this task with the grunt postmark-templates-from-file command.

The postmark-templates-from-file task invokes the postmark-templates task with targets read from a JSON file (via postmark-templates-parse).

This task is intended for standalone, manual usage.

postmark-templates-parse Options

inputFile

The name of a file that specifies templates for uploading to Postmark. These templates take the same shape as defined by postmark-templates-upload. This should usually be the same value as outputFile for postmark-templates-output.

Type: String

Example

In your Gruntfile:

grunt.initConfig({
  'postmark-templates-parse': {
    options: {
      inputFile: 'templates.json'
    }
  },
  'postmark-templates-upload': {
    options: {
      serverToken: 'POSTMARK_API_TEST',
      ephemeralUploadResultsProperty: 'temp'
    }
  },
  'postmark-templates-output': {
    options: {
      cleanOutput: true,
      outputFile: 'templates.json',
      ephemeralUploadResultsProperty: 'temp'
    }
  }
});

In the file specified by inputFile, in this case, templates.json:

{
  "test_email": {
    "name": "testing-postmark-templates-js1",
    "subject": "Testing grunt-postmark-templates",
    "htmlSrc": "test/email.html",
    "textSrc": "test/email.txt"
  },
  "test_email_again": {
    "name": "testing-postmark-templates-js2",
    "subject": "Testing grunt-postmark-templates (again)",
    "htmlSrc": "test/email.html",
    "textSrc": "test/email.txt"
  },
  "test_email_inline_body": {
    "name": "testing-postmark-templates-js3",
    "subject": "Testing grunt-postmark-templates (inline body)",
    "htmlBody": "<html><body><h1>Another email test</h1></body></html>",
    "textBody": "Hello from grunt-postmark-templates\n"
  }
}