Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 138 lines (94 sloc) 5.034 kb
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
1 [PostageApp](http://postageapp.com) for Node.JS
2 ===================================================
3
4 This is a module for Node.JS that allows you to send emails with PostageApp service.
5 Personalized transactional email sending can be offloaded to PostageApp via the JSON based API.
6
7 ### [API Documentation](http://help.postageapp.com/faqs/api) • [PostageApp FAQs](http://help.postageapp.com/faqs) • [PostageApp Help Portal](http://help.postageapp.com)
8
9 Installation
10 ------------
11
88bb763 @JonLim Edited README.md via GitHub
JonLim authored
12 _Node Package Manager_
13
14 In your app directory type
15 `npm install postageapp`
16
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
17 _Manual_
18
cca0203 Fixed the URLs for installation instructions - they were referring to th...
PostageApp authored
19 - Download this: https://github.com/postageapp/postageapp-nodejs/tarball/master
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
20 - Unzip that download.
21 - Copy the resulting folder to `node_modules`
22 - Rename the folder you just copied to `postageapp`
23
24 _GIT Submodule_
25
26 In your app directory type:
cca0203 Fixed the URLs for installation instructions - they were referring to th...
PostageApp authored
27 <pre><code>git submodule add git@github.com:postageapp/postageapp-nodejs.git plugins/postage
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
28 git submodule init
29 git submodule update
30 </code></pre>
31
32 _GIT Clone_
33
34 In your `node_modules` directory type
0bb4131 @JonLim Fixed a small error with the Git Clone installation method.
JonLim authored
35 <pre><code>git clone git@github.com:postageapp/postageapp-nodejs.git postageapp</code></pre>
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
36
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
37 Sending a Message
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
38 -----
93c3422 @visnup updated readme on how to specify api key
visnup authored
39 When you require the library, make sure to specify your API key:
16218f1 @JonLim Update in the README
JonLim authored
40
93c3422 @visnup updated readme on how to specify api key
visnup authored
41 var postageapp = require('postageapp')('YOUR API KEY HERE');
16218f1 @JonLim Update in the README
JonLim authored
42
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
43 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:
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
44
93c3422 @visnup updated readme on how to specify api key
visnup authored
45 var postageapp = require('postageapp')('YOUR API KEY HERE');
56f637f @JonLim Added additional functions to the plugin and updated the readme to refle...
JonLim authored
46 postageapp.sendMessage(options, function callback() {});
7213237 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
47
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
48 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:
49
5948ac8 @JonLim Edited README.md via GitHub
JonLim authored
50 var options = {
51 recipients: "email@address.com",
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
52
5948ac8 @JonLim Edited README.md via GitHub
JonLim authored
53 subject: "Subject Line",
54 from: "sender@example.org",
55
56 content: {
57 'text/html': '<strong>Sample bold content.</strong>',
58 'text/plain': 'Plain text goes here'
59 }
60 }
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
61
62 You can use any of the arguments available to [send_message.json](http://help.postageapp.com/kb/api/send_message) when creating this hash.
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
63
64 Recipients can be passed along as a single string or as an array.
65
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
66 recipients: "email@address.com";
67 recipients: ["email1@address.com", "email2@address.com"];
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
68
4399e12 @JonLim Added support for Message Variables and corresponding documentation
JonLim authored
69 If you wish to set Message Variables for each individual recipient, you just have to pass an array for each recipient.
70
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
71 recipients: {
4399e12 @JonLim Added support for Message Variables and corresponding documentation
JonLim authored
72 "email@example.com": {
73 'variable': 'Value'
74 },
75 "email2@example.com": {
76 'variable': 'Another Value'
fecea4b @JonLim Adding the license
JonLim authored
77 }
1057497 @JonLim Fixing spacing.
JonLim authored
78 };
4399e12 @JonLim Added support for Message Variables and corresponding documentation
JonLim authored
79
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
80 Content will accept an array for HTML and plain text content.
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
81
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
82 content: {
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
83 'text/html': '<strong>Sample bold content.</strong>',
84 'text/plain': 'Plain text goes here'
85 };
86
87 Subject and from can be simple strings.
88
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
89 subject: 'Subject Line';
90 from: 'sender@example.org';
4ca58e5 @JonLim Added section on how to invoke templates with the plugin.
JonLim authored
91
92 Templates can be called by using the template slug from your PostageApp Projects.
93
94 template: 'sample_template';
4399e12 @JonLim Added support for Message Variables and corresponding documentation
JonLim authored
95
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
96 Message Variables needs to have an array passed into it with the global variable names and values.
4399e12 @JonLim Added support for Message Variables and corresponding documentation
JonLim authored
97
f08b690 @JonLim Updated the README.md to reflect new changes to the plugin's methods and...
JonLim authored
98 variables: {
4399e12 @JonLim Added support for Message Variables and corresponding documentation
JonLim authored
99 'variable': 'Variable value',
100 'variable2': 'Another variable'
101 };
56f637f @JonLim Added additional functions to the plugin and updated the readme to refle...
JonLim authored
102
103 Using the Callback Function
104 -----
105 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.
106
107 var postageapp = require('postageapp')('YOUR API KEY HERE');
108 postageapp.sendMessage(options, function callback() {
109 // Additional code to execute after mail is delivered
110 });
111
112 Getting Account Info
113 -----
114 You can get your PostageApp account info through the Node.JS plugin by using the `acountInfo()` function, which can be used as such:
115
116 var postageapp = require('postageapp')('YOUR API KEY HERE');
117 postageapp.accountInfo();
118
119 You can take a look at the documentation for [get_account_info.json](http://help.postageapp.com/kb/api/get_account_info) to learn about the typical response from the API server.
120
121 Getting Message Status
122 -----
123 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()`.
124
125 var postageapp = require('postageapp')('YOUR API KEY HERE');
126 postageapp.messageStatus(options);
127
128 The `options` parameter in the `messageStatus()` function is a hash that contains one thing: the UID of the message you wish you retrieve.
129
130 var options = {
131 desiredUID: 'message UID here',
132 }
133
134 You will receive a JSON string back from the API server that should look something like this:
135
136 {"response":{"status":"ok","uid":"message UID here"},"data":{"message_status":{"completed":1}}}
8be985e @JonLim Added README and updated package.json, more coming.
JonLim authored
137
fecea4b @JonLim Adding the license
JonLim authored
138 For more information about formatting of recipients, templates and variables please see the [PostageApp documentation](http://help.postageapp.com/kb/api/send_message).
Something went wrong with that request. Please try again.