README.md

Postmark API

This is a full REST API wrapper for Postmark

To use the module, run npm install postmarkapi

Using the module

First you must make a instance of the module, with your Postmark Server token.

var PostmarkAPI = require('postmarkapi');
var pmk = new PostmarkAPI('[your server token]');

Sending an email

You always need to define a to for an email, and subject. You can send text or html, or both, but you need to define one or ther other.

If you don't define a from, it will use the address you created the Sender Signature with.

You can send multiple ccs or bccs by passing an array.

You don't need to pass a callback.

// simple example
pmk.email({
  to: 'someaddress@somewhere.com',
  subject: 'Test Email',
  text: 'Hello World'
});

// more specific
pmk.email({
  to: 'someaddress@somewhere.com',
  from: 'fromaddress@somewhere.com',
  fromName: 'John Doe',
  cc: ['carbon-copy@somewhere.com', 'carbon-copy-2@somewhere.com'],
  bcc: 'blind-carbon-copy@somewhere.com',
  reply: 'reply-to@somewhere.com',
  tag: 'MyTag',
  headers: {
    EmailedUsing: 'Node PostmarkAPI Module'
  },
  subject: 'Test Email',
  text: 'Hello World',
  html: '<strong>Hello World</strong>'
}, function(err, response) {
  // ...
});

You can also send an email with attachments

var path = require('path');

pmk.email({
  to: 'someaddress@somewhere.com',
  from: 'fromaddress@somewhere.com',
  subject: 'Test Email',
  text: 'Hello World',
  html: '<strong>Hello World</strong>',
  attachments: [
    path.resolve(__dirname, 'cats.gif'),
    path.resolve(__dirname, 'notes.txt')
  ]
}, function(err, response) {
  // ...
});

// or

pmk.email({
  to: 'someaddress@somewhere.com',
  from: 'fromaddress@somewhere.com',
  subject: 'Test Email',
  text: 'Hello World',
  html: '<strong>Hello World</strong>',
  attachments: [{
    name: 'orders.csv',
    content: ordersContent.toString('base64'),
    contentType: 'text/csv'
  }]
}, function(err, response) {
  // ...
});

Bounces

Getting a summary of bounces for the server

pmk.deliverystats(function(err, response) {});

Retrieving bounces

You can retrieve bounces associated with your server.

// simple example
pmk.bounces({
  count: 10,
  offset: 0
}, function(err, response) {});

// with messageId
pmk.bounces({
  messageId: '[messageIDHere]'
}, function(err, response) {});

// more sepcific
pmk.bounces({
  count: 10,
  offset: 0,
  type: 'HardBounce',
  inactive: 0,
  emailFilter: 'somewhere.com'
}, function(err, response) {});

Getting a list of tags for bounces on server

pmk.bounceTags(function(err, response) {});

Getting a single bounce

pmk.bounce(bouncId, function(err, response) {});

Getting a single bounce's dump

pmk.bounceDump(bouncId, function(err, response) {});

Activating a deactivated bounce

Callback optional

pmk.bounceActivate(bounceId, function(err, response) {});

Outbound messages

Retrieving sent messages

// simple example
pmk.outbound({
  count: 10,
  offset: 0
}, function(err, response) {});

// more specific
pmk.outbound({
  count: 10,
  offset: 0,
  recipient: 'someone@somewhere.com',
  fromemail: 'fromemail@somewhere.com',
  tag: 'MyTag',
  subject: 'Welcome Email'
}, function(err, response) {});

Getting details for a single sent message

pmk.outboundMessage(messageId, function(err, response) {});

Getting message dump

pmk.outboundMessageDump(messageId, function(err, response) {});

Inbound messages

Retrieving recieved messages

// simple example
pmk.inbound({
  count: 10,
  offset: 0
}, function(err, response) {});

// more specific
pmk.inbound({
  count: 10,
  offset: 0,
  recipient: 'someone@somewhere.com',
  fromemail: 'fromemail@somewhere.com',
  tag: 'MyTag',
  subject: 'Welcome Email',
  mailboxhash: 'mailboxhashvalue'
}, function(err, response) {});

Gettings details for a single recieved message

pmk.inboundMessage(messageId, function(err, response) {});

Sender Signatures

Getting a list of Sender Signatures

pmk.senders({
  count: 10,
  offset: 0
}, function(err, response) {});

Fetching details for a single sender

pmk.sender(senderId, function(err, response) {});

Creating a Sender Signature

The reply and callback are optional

pmk.createSender({
  name: 'Sender Name',
  from: 'senderemail@somewhere.com',
  reply: 'replyto@somewhere.com'
}, function(err, response) {});

Updating a Sender Signature

The reply and callback are optional

You cannot update the from address

pmk.updateSender(senderId, {
  name: 'Sender Name',
  reply: 'replyto@somewhere.com'
}, function(err, response) {});

Resending a Sender Signature confirmation email

The callback is optional

pmk.resendSender(senderId, function(err, response) {});

Deleting a Sender Signature

The callback is optional

pmk.deleteSender(senderId, function(err, response) {});

Verifying a SPF record

The callback is optional

pmk.verifySPF(senderId, function(err, response) {});

Requesting a new DKIM

The callback is optional

pmk.requestDKIM(senderId, function(err, response) {});

Servers

Getting a list of servers

pmk.servers({
  count: 10,
  offset: 0,
  name: 'Production'
}, function(err, response) {});

Getting a single server's details

pmk.server(serverId, function(err, response) {});

Creating a new server

// simple example
pmk.createServer({
  name: 'Server Name'
});

// more specific
pmk.createServer({
  name: 'Server Name',
  color: 'red',
  smtp: true,
  raw: true,
  inboundHook: 'https://...',
  bounceHook: 'https://...',
  inboundDomain: 'myDomain'
}, function(err, response) {});

Updating a server

// simple example
pmk.updateServer(serverId, {
  name: 'Server Name'
});

// more specific
pmk.updateServer(serverId, {
  name: 'Server Name',
  color: 'red',
  smtp: true,
  raw: true,
  inboundHook: 'https://...',
  bounceHook: 'https://...',
  inboundDomain: 'myDomain'
}, function(err, response) {});

Deleting a server

The callback is optional

pmk.deleteServer(serverId, function(err, response) {});