Skip to content

Commit cb81a45

Browse files
aydrianaydrian
committed
Merge pull request #47 from aydrian/ISSUE-44
ISSUE 44: Create docs and examples for new APIs
2 parents bc93efb + 7d88f3c commit cb81a45

39 files changed

+965
-106
lines changed

‎README.md

Lines changed: 88 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,113 @@
11
[![Travis CI](https://travis-ci.org/SparkPost/node-sparkpost.svg?branch=master)](https://travis-ci.org/SparkPost/node-sparkpost)
22

3-
# SparkPost Node.js SDK
3+
![SparkPost Build by MessageSystems](/docs/sparkpost_logo.png)
4+
# Node.js SDK
45

5-
The official node.js binding for your favorite SparkPost APIs!
6+
The official Node.js binding for your favorite [SparkPost APIs](https://www.sparkpost.com/api)!
67

7-
Before using this library, you must have a valid API Key.
8+
## Prerequisites
89

9-
To get an API Key, please log in to your SparkPost account and generate one in the Settings page.
10+
Before using this library, you must have:
11+
12+
* A shiny new SparkPost Account, [sign up for a new account](https://app.sparkpost.com/#/sign-up) or [login to SparkPost](https://app.sparkpost.com/)
13+
* A valid SparkPost API Key. Check out our [Support Center](https://support.sparkpost.com/) for information on how to [create API keys](https://support.sparkpost.com/customer/portal/articles/1933377-create-api-keys)
1014

1115
## Installation
1216

1317
```
1418
npm install sparkpost
1519
```
1620

17-
## Getting Started: Your First Mailing
18-
19-
```javascript
20-
var SparkPost = require('sparkpost')
21-
, client = new SparkPost('YOUR API KEY');
21+
## Initialization
22+
**new SparkPost(apiKey, options)** - Initialization
23+
24+
* `apiKey`
25+
* Required: yes (unless key is stored in `SPARKPOST_API_KEY` environment variable)
26+
* Type: `String`
27+
* a passed in apiKey will take precedence over an environment variable
28+
* `options.origin` or `options.endpoint`
29+
* Required: no
30+
* Type: `String`
31+
* Default: `https://api.sparkpost.com:443`
32+
* `options.apiVersion`
33+
* Required: no
34+
* Type: `String`
35+
* Default: `v1`
36+
* `options.headers`
37+
* Required: no
38+
* Type: `Object`
39+
* set headers that apply to all requests
40+
41+
## Methods
42+
* **request(options, callback)**
43+
* `options` - [see request modules options](https://github.com/mikeal/request#requestoptions-callback)
44+
* `options.uri` - can either be a full url or a path that is appended to `options.origin` used at initialization ([url.resolve](http://nodejs.org/api/url.html#url_url_resolve_from_to))
45+
* `callback` - executed after task is completed. **required**
46+
* standard `callback(err, data)`
47+
* `err` - any error that occurred
48+
* `data.res` - full response from request client
49+
* `data.body` - payload from response
50+
* **get | post | put | delete(options, callback)**
51+
* `options` - see request options
52+
* `callback` - see request options
53+
* Request method will be overwritten and set to the same value as the name of these methods.
54+
55+
## Creating a SparkPost Client
56+
57+
Passing in an API key
58+
```js
59+
var SparkPost = require('sparkpost');
60+
var client = new SparkPost('YOUR_API_KEY');
61+
```
2262

23-
var trans = {};
63+
Using an API key stored in an environment variable
64+
```js
65+
process.env.SPARKPOST_API_KEY = 'YOUR_API_KEY';
66+
var SparkPost = require('sparkpost');
67+
var client = new SparkPost();
68+
```
2469

25-
// Set some metadata for your email
26-
trans.campaign = 'first-mailing';
27-
trans.from = '[email protected]';
28-
trans.subject = 'First SDK Mailing';
70+
Specifying non-default options
71+
```js
72+
var SparkPost = require('sparkpost');
73+
var options = {
74+
endpoint: 'https://dev.sparkpost.com:443'
75+
};
76+
var client = new SparkPost('YOUR_API_KEY', options);
77+
```
2978

30-
// Add some content to your email
31-
trans.html = '<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>';
32-
trans.text = 'Congratulations, {{name}}!! You just sent your very first mailing!';
33-
trans.substitutionData = {name: 'YOUR FIRST NAME'};
79+
## Using the Node SDK Base Object
80+
We may not wrap every resource available in the SparkPost SDK, for example the Node SDK does not wrap the Metrics resource,
81+
but you can use the Node SDK Base Object to form requests to these unwrapped resources. Here is an example request using the
82+
base object to make requests to the Metrics resource. Here is an example request using the base object to make requests to
83+
the Metrics resource.
3484

35-
// Pick someone to receive your email
36-
trans.recipients = [{ address: { name: 'YOUR FULL NAME', email: 'YOUR EMAIL ADDRESS' } }];
85+
```js
86+
// Get a list of domains that the Metrics API contains data on.
87+
var options = {
88+
uri: 'metrics/domains'
89+
};
3790

38-
// Send it off into the world!
39-
client.transmission.send(trans, function(err, res) {
40-
if (err) {
41-
console.log('Whoops! Something went wrong');
91+
client.get(options, function(err, data) {
92+
if(err) {
4293
console.log(err);
43-
} else {
44-
console.log('Woohoo! You just sent your first mailing!');
94+
return;
4595
}
96+
97+
console.log(data.body);
4698
});
4799
```
48100

49-
## Learn More
50-
* For more detailed examples, check our examples:
51-
* [Transmissions](https://github.com/MessageSystems/node-sdk/blob/master/examples/transmission/)
52-
* Read our REST API documentation - <http://www.sparkpost.com/docs>
53-
54-
## Field Descriptions
55-
### Transmissions
56-
| Field Name | Required? | Description | Data Type |
57-
| ------------ | ----------- | ------------- | ----------- |
58-
| description | no | Field for describing what this transmission is for the user | String |
59-
| campaign | no | Field for assigning a given transmission to a specific campaign, which is a logical container for similar transmissions | String |
60-
| metadata | no | Field for adding arbitrary key/value pairs which will be included in open/click tracking | Object (Simple) |
61-
| substitutionData | no | Field for adding transmission level substitution data, which can be used in a variety of fields and in content | Object (Complex) |
62-
| trackOpens | no | Field for enabling/disabling transmission level open tracking, if not set will use settings from Template | Boolean |
63-
| trackClicks | no | Field for enabling/disabling transmission level click tracking, if not set will use settings from Template | Boolean |
64-
| useSandbox | no | Field for enabling/disabling using sandbox domain to send transmission(You are limited to 50 messages ever with sandbox) | Boolean |
65-
| useDraftTemplate | no | Field for allowing the sending of a transmission using a draft of a stored template (default: false) | Boolean |
66-
| replyTo | no | Field for specifying the email address that should be used when a recipient hits the reply button | String |
67-
| subject | yes | Field for setting the subject line of a given transmission | String |
68-
| from | yes | Field for setting the from line of a given transmission | String or Object |
69-
| html | yes** | Field for setting the HTML content of a given transmission | String |
70-
| text | yes** | Field for setting the Plain Text content of a given transmission | String |
71-
| rfc822 | no** | Field for setting the RFC-822 encoded content of a given transmission | String |
72-
| template | no** | Field for specifying the Template ID of a stored template to be used when sending a given transmission | String |
73-
| customHeaders | no | Field for specifying additional headers to be applied to a given transmission (other than Subject, From, To, and Reply-To) | Object (Simple) |
74-
| recipients | yes** | Field for specifying who a given transmission should be sent to | Array of Objects |
75-
| recipientList | no** | Field for specifying a stored recipient list ID to be used for a given transmission | String |
76-
77-
** - If using inline content then html or text are required. If using RFC-822 Inline Content, then rfc822 is required. If using a stored recipient list, then recipientList is required. If using a stored template, then template is required.
78-
79-
### Sending Domains
80-
| Field Name | Required? | Description | Data Type |
81-
| ------------ | ----------- | ------------- | ----------- |
82-
| domainName | yes | Name of the sending domain | String |
83-
| privateKey | yes** | Private key used to create the DKIM Signature. | String |
84-
| publicKey | yes** | Public key to be retrieved from the DNS of the sending domain. | String |
85-
| selector | yes** | DomainKey selector that indicates the DKIM public key location. | String |
86-
| headers | no | Header fields to be included in the DKIM signature | String |
87-
88-
** - If specifying a privateKey, publicKey, or selector, all three fields are required.
89-
90-
## Tips and Tricks
91-
### General
92-
* You _must_ provide at least an API key when instantiating the SparkPost Library - `{ key: '184ac5480cfdd2bb2859e4476d2e5b1d2bad079bf' }`
93-
* The SDK's features are namespaced under the various SparkPost API names.
94-
95-
### Transmissions
96-
* If you specify a stored recipient list and inline recipients in a Transmission, you will receive an error.
97-
* If you specify HTML and/or Plain Text content and then provide RFC-822 encoded content, you will receive an error.
98-
* RFC-822 content is not valid with any other content type.
99-
* If you specify a stored template and also provide inline content, you will receive an error.
100-
* By default, open and click tracking are enabled for a transmission.
101-
* By default, a transmission will use the published version of a stored template.
101+
## SparkPost API Resources Supported in Node SDK
102+
Click on the desired API to see usage and more information
103+
104+
* [Recipient Lists](/docs/resources/recipientLists.md) - `client.recipientLists` ([examples](/examples/recipientLists))
105+
* [Sending Domains](/docs/resources/sendingDomains.md) - `client.sendingDomains` ([examples](/examples/sendingDomains))
106+
* [Suppression List](/docs/resources/suppressionList.md) - `client.suppressionList` ([examples](/examples/suppressionList))
107+
* [Templates](/docs/resources/templates.md) - `client.templates` ([examples](/examples/templates))
108+
* [Transmissions](/docs/apis/transmission.md) - `client.transmission` ([examples](/examples/transmission))
109+
* [Webhooks](/docs/resources/webhooks.md) - `client.webhooks` ([examples](/examples/webhooks))
110+
102111

103112
## Development
104113

‎docs/resources/recipientLists.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Recipient Lists
2+
3+
This library provides easy access to the [Recipient Lists](https://www.sparkpost.com/api#/reference/recipient-lists/) Resource.
4+
5+
## Methods
6+
* **all(callback)**
7+
List a summary of all recipient lists.
8+
* `callback` - executed after task is completed. **required**
9+
* standard `callback(err, data)`
10+
* `err` - any error that occurred
11+
* `data.res` - full response from request client
12+
* `data.body` - payload from response
13+
* **find(options, callback)**
14+
Retrieve details about a specified recipient list by its id
15+
* `options.id` - the id of the recipient list you want to look up **required**
16+
* `options.show_recipients` - specifies whether to retrieve the recipients Default: `false`
17+
* `callback` - see all function
18+
* **create(options, callback)**
19+
Create a new recipient list
20+
* `options.recipients` - an array of recipients to add to the list **required**
21+
* `options.num_rcpt_errors` - limit the number of recipient errors returned
22+
* `callback` - see all function
23+
* **delete(id, callback)**
24+
Delete an existing recipient list
25+
* `id` - the id of the recipient list you want to delete **required**
26+
* `callback` - see all function
27+
28+
## Examples
29+
30+
```js
31+
var SparkPost = require('sparkpost');
32+
var client = new SparkPost('YOUR_API_KEY');
33+
34+
client.recipientLists.all(function(err, data) {
35+
if(err) {
36+
console.log(err);
37+
return;
38+
}
39+
40+
console.log(data.body);
41+
});
42+
43+
```
44+
45+
Check out all the examples provided [here](/examples/recipientLists).

‎docs/resources/sendingDomains.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Sending Domains
2+
3+
This library provides easy access to the [Sending Domains](https://www.sparkpost.com/api#/reference/sending-domains/) Resource.
4+
5+
## Methods
6+
* **all(callback)**
7+
List an overview of all sending domains in the account.
8+
* `callback` - executed after task is completed. **required**
9+
* standard `callback(err, data)`
10+
* `err` - any error that occurred
11+
* `data.res` - full response from request client
12+
* `data.body` - payload from response
13+
* **find(domainName, callback)**
14+
Retrieve a sending domain by its domain name
15+
* `domainName` - the name of the domain you want to look up **required**
16+
* `callback` - see all function
17+
* **create(domainBody, callback)**
18+
Create a new sending domain
19+
* `domainBody` - see object description below **required**
20+
* `callback` - see all function
21+
* **update(domainBody, callback)**
22+
Update an existing sending domain
23+
* `domainBody` - see object description below **required**
24+
* `callback` - see all function
25+
* **verify(options, callback)**
26+
Validate the specified verification field types for a sending domain
27+
* `options.domainName` - the name of the domain you want to verify **required**
28+
* `options.verifyDKIM` - initiates a check against the DKIM record default: `true`
29+
* `options.verifySPF` - initiates a check against the SPF record default: `true`
30+
31+
32+
### domainBody
33+
| Field Name | Required? | Description | Data Type |
34+
| ---------- | --------- | --------------------------------------------------------------- | --------- |
35+
| domainName | yes | Name of the sending domain | String |
36+
| privateKey | yes** | Private key used to create the DKIM Signature. | String |
37+
| publicKey | yes** | Public key to be retrieved from the DNS of the sending domain. | String |
38+
| selector | yes** | DomainKey selector that indicates the DKIM public key location. | String |
39+
| headers | no | Header fields to be included in the DKIM signature | String |
40+
41+
** - If specifying a privateKey, publicKey, or selector, all three fields are required.
42+
43+
## Examples
44+
45+
```js
46+
var SparkPost = require('sparkpost');
47+
var client = new SparkPost('YOUR_API_KEY');
48+
49+
client.sendingDomains.all(function(err, data) {
50+
if(err) {
51+
console.log(err);
52+
return;
53+
}
54+
55+
console.log(data.body);
56+
});
57+
58+
```
59+
60+
Check out all the examples provided [here](/examples/sendingDomains).

‎docs/resources/suppressionList.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Suppression List
2+
3+
This library provides easy access to the [Suppression List](https://www.sparkpost.com/api#/reference/suppression-list/) Resource.
4+
5+
## Methods
6+
* **search(parameters, callback)**
7+
Perform a filtered search for entries in your suppression list.
8+
* `parameters` - Object of [search parameters](https://www.sparkpost.com/api#/reference/suppression-list/search/search-for-suppression-list-entries)
9+
* `callback` - executed after task is completed. **required**
10+
* standard `callback(err, data)`
11+
* `err` - any error that occurred
12+
* `data.res` - full response from request client
13+
* `data.body` - payload from response
14+
* **checkStatus(email, callback)**
15+
* `email` - `String` email address to check **required**
16+
* `callback` - see search function
17+
* **removeStatus(email, callback)**
18+
* `email` - `String` email address to remove **required**
19+
* `callback` - see search function
20+
* **upsert(recipient, callback)**
21+
* `recipient` - [Recipient Object](https://www.sparkpost.com/api#/reference/recipient-lists) or `Array` of Recipient Objects
22+
* `callback` - see search function
23+
24+
## Examples
25+
26+
```js
27+
var SparkPost = require('sparkpost');
28+
var client = new SparkPost('YOUR_API_KEY');
29+
var parameters = {
30+
from: '2015-05-07T00:00:00+0000'
31+
, to: '2015-05-07T23:59:59+0000'
32+
, limit: 5
33+
};
34+
35+
client.suppressionList.search(parameters, function(err, data) {
36+
if(err) {
37+
console.log(err);
38+
return;
39+
}
40+
41+
console.log(data.body);
42+
});
43+
44+
```
45+
46+
Check out all the examples provided [here](/examples/suppressionList).

‎docs/resources/templates.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Templates
2+
3+
This library provides easy access to the [Templates](https://www.sparkpost.com/api#/reference/templates/) Resource.
4+
5+
## Methods
6+
* **all(callback)**
7+
List a summary of all templates.
8+
* `callback` - executed after task is completed. **required**
9+
* standard `callback(err, data)`
10+
* `err` - any error that occurred
11+
* `data.res` - full response from request client
12+
* `data.body` - payload from response
13+
* **find(options, callback)**
14+
Retrieve details about a specified template by its id
15+
* `options.id` - the id of the template you want to look up **required**
16+
* `options.draft` - specifies a draft or published template
17+
* `callback` - see all function
18+
* **create(options, callback)**
19+
Create a new recipient list
20+
* `options.template` - a template object **required**
21+
* `callback` - see all function
22+
* **delete(id, callback)**
23+
Delete an existing template
24+
* `id` - the id of the template you want to delete **required**
25+
* `callback` - see all function
26+
* **preview(options, callback)**
27+
Preview the most recent version of an existing template by id
28+
* `options.id` - the id of the template you want to look up **required**
29+
* `options.data` - Object of substitution data
30+
* `options.draft` - specifies a draft or published template
31+
* `callback` - see all function
32+
33+
## Examples
34+
35+
```js
36+
var SparkPost = require('sparkpost');
37+
var client = new SparkPost('YOUR_API_KEY');
38+
39+
client.templates.all(function(err, data) {
40+
if(err) {
41+
console.log(err);
42+
return;
43+
}
44+
45+
console.log(data.body);
46+
});
47+
48+
```
49+
50+
Check out all the examples provided [here](/examples/templates).

0 commit comments

Comments
 (0)