PostageApp for Node.JS

This is a module for Node.JS that allows you to send emails with PostageApp service. Personalized transactional email sending can be offloaded to PostageApp via the JSON based API.

API Documentation • PostageApp FAQs • PostageApp Help Portal

Installation

Node Package Manager

In your app directory type npm install postageapp

Manual

• Download this: https://github.com/postageapp/postageapp-nodejs/tarball/master
• Unzip that download.
• Copy the resulting folder to node_modules
• Rename the folder you just copied to postageapp

GIT Submodule

In your app directory type:

git submodule add git@github.com:postageapp/postageapp-nodejs.git plugins/postage
git submodule init
git submodule update

GIT Clone

In your node_modules directory type

git clone git@github.com:postageapp/postageapp-nodejs.git postageapp

Sending a Message

When you require the library, make sure to specify your API key:

var postageapp = require('postageapp')('YOUR API KEY HERE');

After that, you should be good to go. Load the module in your app and call the sendMessage function. Here is a sample of how to use it:

var postageapp = require('postageapp')('YOUR API KEY HERE');
postageapp.sendMessage(options, function callback() {});

The options parameter on the sendMessage() function is a hash that contains all of the arguments that you will be using in your API call. Here is an example API call:

var options = { 
	recipients: "email@address.com",

	subject: "Subject Line",
	from: "sender@example.org",

	content: {
		'text/html': '<strong>Sample bold content.</strong>',
		'text/plain': 'Plain text goes here'
	}
}

You can use any of the arguments available to send_message.json when creating this hash.

Recipients can be passed along as a single string or as an array.

recipients: "email@address.com";
recipients: ["email1@address.com", "email2@address.com"];

If you wish to set Message Variables for each individual recipient, you just have to pass an array for each recipient.

recipients: {
    "email@example.com": {
	    'variable': 'Value'
    }, 
    "email2@example.com": {
	    'variable': 'Another Value'
    }
};

Content will accept an array for HTML and plain text content.

content: {
	'text/html': '<strong>Sample bold content.</strong>',
	'text/plain': 'Plain text goes here'
};

Subject and from can be simple strings.

subject: 'Subject Line';
from: 'sender@example.org';

Templates can be called by using the template slug from your PostageApp Projects.

template: 'sample_template';

Message Variables needs to have an array passed into it with the global variable names and values.

variables: {
	'variable': 'Variable value',
	'variable2': 'Another variable'
};

Using the Callback Function

The sendMessage() function in the PostageApp Node.JS plugin includes a callback argument. Callbacks are used to tell the PostageApp Node.JS plugin to execute some other code as soon as it is finished with sending your emails to PostageApp.

var postageapp = require('postageapp')('YOUR API KEY HERE');
postageapp.sendMessage(options, function callback() {
  // Additional code to execute after mail is delivered
});

Getting Account Info

You can get your PostageApp account info through the Node.JS plugin by using the acountInfo() function, which can be used as such:

var postageapp = require('postageapp')('YOUR API KEY HERE');
postageapp.accountInfo();

You can take a look at the documentation for get_account_info.json to learn about the typical response from the API server.

Getting Message Status

You can the status of an individual message sent through PostageApp using the UID that your API call provides. The PostageApp Node.JS plugin creates a unique UID for each message sent through by using Date.getTime(). You then use that UID in messageStatus().

var postageapp = require('postageapp')('YOUR API KEY HERE');
postageapp.messageStatus(options);

The options parameter in the messageStatus() function is a hash that contains one thing: the UID of the message you wish you retrieve.

var options = { 
  	desiredUID: 'message UID here',
}

You will receive a JSON string back from the API server that should look something like this:

{"response":{"status":"ok","uid":"message UID here"},"data":{"message_status":{"completed":1}}}

For more information about formatting of recipients, templates and variables please see the PostageApp documentation.