Skip to content

Commit

Permalink
Merge pull request #47 from aydrian/ISSUE-44
Browse files Browse the repository at this point in the history 
ISSUE 44: Create docs and examples for new APIs
  • Loading branch information
@aydrian
aydrian committed May 8, 2015
2 parents bc93efb + 7d88f3c commit cb81a45
Show file tree
Hide file tree
Showing 39 changed files with 965 additions and 106 deletions.
167 changes: 88 additions & 79 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,104 +1,113 @@
[![Travis CI](https://travis-ci.org/SparkPost/node-sparkpost.svg?branch=master)](https://travis-ci.org/SparkPost/node-sparkpost)

# SparkPost Node.js SDK
![SparkPost Build by MessageSystems](/docs/sparkpost_logo.png)
# Node.js SDK

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

Before using this library, you must have a valid API Key.
## Prerequisites

To get an API Key, please log in to your SparkPost account and generate one in the Settings page.
Before using this library, you must have:

* 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/)
* 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)

## Installation

```
npm install sparkpost
```

## Getting Started: Your First Mailing

```javascript
var SparkPost = require('sparkpost')
, client = new SparkPost('YOUR API KEY');
## Initialization
**new SparkPost(apiKey, options)** - Initialization

* `apiKey`
* Required: yes (unless key is stored in `SPARKPOST_API_KEY` environment variable)
* Type: `String`
* a passed in apiKey will take precedence over an environment variable
* `options.origin` or `options.endpoint`
* Required: no
* Type: `String`
* Default: `https://api.sparkpost.com:443`
* `options.apiVersion`
* Required: no
* Type: `String`
* Default: `v1`
* `options.headers`
* Required: no
* Type: `Object`
* set headers that apply to all requests

## Methods
* **request(options, callback)**
* `options` - [see request modules options](https://github.com/mikeal/request#requestoptions-callback)
* `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))
* `callback` - executed after task is completed. **required**
* standard `callback(err, data)`
* `err` - any error that occurred
* `data.res` - full response from request client
* `data.body` - payload from response
* **get | post | put | delete(options, callback)**
* `options` - see request options
* `callback` - see request options
* Request method will be overwritten and set to the same value as the name of these methods.

## Creating a SparkPost Client

Passing in an API key
```js
var SparkPost = require('sparkpost');
var client = new SparkPost('YOUR_API_KEY');
```

var trans = {};
Using an API key stored in an environment variable
```js
process.env.SPARKPOST_API_KEY = 'YOUR_API_KEY';
var SparkPost = require('sparkpost');
var client = new SparkPost();
```

// Set some metadata for your email
trans.campaign = 'first-mailing';
trans.from = '[email protected]';
trans.subject = 'First SDK Mailing';
Specifying non-default options
```js
var SparkPost = require('sparkpost');
var options = {
endpoint: 'https://dev.sparkpost.com:443'
};
var client = new SparkPost('YOUR_API_KEY', options);
```

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

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

// Send it off into the world!
client.transmission.send(trans, function(err, res) {
if (err) {
console.log('Whoops! Something went wrong');
client.get(options, function(err, data) {
if(err) {
console.log(err);
} else {
console.log('Woohoo! You just sent your first mailing!');
return;
}

console.log(data.body);
});
```

## Learn More
* For more detailed examples, check our examples:
* [Transmissions](https://github.com/MessageSystems/node-sdk/blob/master/examples/transmission/)
* Read our REST API documentation - <http://www.sparkpost.com/docs>

## Field Descriptions
### Transmissions
| Field Name | Required? | Description | Data Type |
| ------------ | ----------- | ------------- | ----------- |
| description | no | Field for describing what this transmission is for the user | String |
| campaign | no | Field for assigning a given transmission to a specific campaign, which is a logical container for similar transmissions | String |
| metadata | no | Field for adding arbitrary key/value pairs which will be included in open/click tracking | Object (Simple) |
| substitutionData | no | Field for adding transmission level substitution data, which can be used in a variety of fields and in content | Object (Complex) |
| trackOpens | no | Field for enabling/disabling transmission level open tracking, if not set will use settings from Template | Boolean |
| trackClicks | no | Field for enabling/disabling transmission level click tracking, if not set will use settings from Template | Boolean |
| useSandbox | no | Field for enabling/disabling using sandbox domain to send transmission(You are limited to 50 messages ever with sandbox) | Boolean |
| useDraftTemplate | no | Field for allowing the sending of a transmission using a draft of a stored template (default: false) | Boolean |
| replyTo | no | Field for specifying the email address that should be used when a recipient hits the reply button | String |
| subject | yes | Field for setting the subject line of a given transmission | String |
| from | yes | Field for setting the from line of a given transmission | String or Object |
| html | yes** | Field for setting the HTML content of a given transmission | String |
| text | yes** | Field for setting the Plain Text content of a given transmission | String |
| rfc822 | no** | Field for setting the RFC-822 encoded content of a given transmission | String |
| template | no** | Field for specifying the Template ID of a stored template to be used when sending a given transmission | String |
| customHeaders | no | Field for specifying additional headers to be applied to a given transmission (other than Subject, From, To, and Reply-To) | Object (Simple) |
| recipients | yes** | Field for specifying who a given transmission should be sent to | Array of Objects |
| recipientList | no** | Field for specifying a stored recipient list ID to be used for a given transmission | String |

** - 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.

### Sending Domains
| Field Name | Required? | Description | Data Type |
| ------------ | ----------- | ------------- | ----------- |
| domainName | yes | Name of the sending domain | String |
| privateKey | yes** | Private key used to create the DKIM Signature. | String |
| publicKey | yes** | Public key to be retrieved from the DNS of the sending domain. | String |
| selector | yes** | DomainKey selector that indicates the DKIM public key location. | String |
| headers | no | Header fields to be included in the DKIM signature | String |

** - If specifying a privateKey, publicKey, or selector, all three fields are required.

## Tips and Tricks
### General
* You _must_ provide at least an API key when instantiating the SparkPost Library - `{ key: '184ac5480cfdd2bb2859e4476d2e5b1d2bad079bf' }`
* The SDK's features are namespaced under the various SparkPost API names.

### Transmissions
* If you specify a stored recipient list and inline recipients in a Transmission, you will receive an error.
* If you specify HTML and/or Plain Text content and then provide RFC-822 encoded content, you will receive an error.
* RFC-822 content is not valid with any other content type.
* If you specify a stored template and also provide inline content, you will receive an error.
* By default, open and click tracking are enabled for a transmission.
* By default, a transmission will use the published version of a stored template.
## SparkPost API Resources Supported in Node SDK
Click on the desired API to see usage and more information

* [Recipient Lists](/docs/resources/recipientLists.md) - `client.recipientLists` ([examples](/examples/recipientLists))
* [Sending Domains](/docs/resources/sendingDomains.md) - `client.sendingDomains` ([examples](/examples/sendingDomains))
* [Suppression List](/docs/resources/suppressionList.md) - `client.suppressionList` ([examples](/examples/suppressionList))
* [Templates](/docs/resources/templates.md) - `client.templates` ([examples](/examples/templates))
* [Transmissions](/docs/apis/transmission.md) - `client.transmission` ([examples](/examples/transmission))
* [Webhooks](/docs/resources/webhooks.md) - `client.webhooks` ([examples](/examples/webhooks))


## Development

Expand Down
45 changes: 45 additions & 0 deletions docs/resources/recipientLists.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Recipient Lists

This library provides easy access to the [Recipient Lists](https://www.sparkpost.com/api#/reference/recipient-lists/) Resource.

## Methods
* **all(callback)**
List a summary of all recipient lists.
* `callback` - executed after task is completed. **required**
* standard `callback(err, data)`
* `err` - any error that occurred
* `data.res` - full response from request client
* `data.body` - payload from response
* **find(options, callback)**
Retrieve details about a specified recipient list by its id
* `options.id` - the id of the recipient list you want to look up **required**
* `options.show_recipients` - specifies whether to retrieve the recipients Default: `false`
* `callback` - see all function
* **create(options, callback)**
Create a new recipient list
* `options.recipients` - an array of recipients to add to the list **required**
* `options.num_rcpt_errors` - limit the number of recipient errors returned
* `callback` - see all function
* **delete(id, callback)**
Delete an existing recipient list
* `id` - the id of the recipient list you want to delete **required**
* `callback` - see all function

## Examples

```js
var SparkPost = require('sparkpost');
var client = new SparkPost('YOUR_API_KEY');

client.recipientLists.all(function(err, data) {
if(err) {
console.log(err);
return;
}

console.log(data.body);
});

```

Check out all the examples provided [here](/examples/recipientLists).
60 changes: 60 additions & 0 deletions docs/resources/sendingDomains.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Sending Domains

This library provides easy access to the [Sending Domains](https://www.sparkpost.com/api#/reference/sending-domains/) Resource.

## Methods
* **all(callback)**
List an overview of all sending domains in the account.
* `callback` - executed after task is completed. **required**
* standard `callback(err, data)`
* `err` - any error that occurred
* `data.res` - full response from request client
* `data.body` - payload from response
* **find(domainName, callback)**
Retrieve a sending domain by its domain name
* `domainName` - the name of the domain you want to look up **required**
* `callback` - see all function
* **create(domainBody, callback)**
Create a new sending domain
* `domainBody` - see object description below **required**
* `callback` - see all function
* **update(domainBody, callback)**
Update an existing sending domain
* `domainBody` - see object description below **required**
* `callback` - see all function
* **verify(options, callback)**
Validate the specified verification field types for a sending domain
* `options.domainName` - the name of the domain you want to verify **required**
* `options.verifyDKIM` - initiates a check against the DKIM record default: `true`
* `options.verifySPF` - initiates a check against the SPF record default: `true`


### domainBody
| Field Name | Required? | Description | Data Type |
| ---------- | --------- | --------------------------------------------------------------- | --------- |
| domainName | yes | Name of the sending domain | String |
| privateKey | yes** | Private key used to create the DKIM Signature. | String |
| publicKey | yes** | Public key to be retrieved from the DNS of the sending domain. | String |
| selector | yes** | DomainKey selector that indicates the DKIM public key location. | String |
| headers | no | Header fields to be included in the DKIM signature | String |

** - If specifying a privateKey, publicKey, or selector, all three fields are required.

## Examples

```js
var SparkPost = require('sparkpost');
var client = new SparkPost('YOUR_API_KEY');

client.sendingDomains.all(function(err, data) {
if(err) {
console.log(err);
return;
}

console.log(data.body);
});

```

Check out all the examples provided [here](/examples/sendingDomains).
46 changes: 46 additions & 0 deletions docs/resources/suppressionList.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Suppression List

This library provides easy access to the [Suppression List](https://www.sparkpost.com/api#/reference/suppression-list/) Resource.

## Methods
* **search(parameters, callback)**
Perform a filtered search for entries in your suppression list.
* `parameters` - Object of [search parameters](https://www.sparkpost.com/api#/reference/suppression-list/search/search-for-suppression-list-entries)
* `callback` - executed after task is completed. **required**
* standard `callback(err, data)`
* `err` - any error that occurred
* `data.res` - full response from request client
* `data.body` - payload from response
* **checkStatus(email, callback)**
* `email` - `String` email address to check **required**
* `callback` - see search function
* **removeStatus(email, callback)**
* `email` - `String` email address to remove **required**
* `callback` - see search function
* **upsert(recipient, callback)**
* `recipient` - [Recipient Object](https://www.sparkpost.com/api#/reference/recipient-lists) or `Array` of Recipient Objects
* `callback` - see search function

## Examples

```js
var SparkPost = require('sparkpost');
var client = new SparkPost('YOUR_API_KEY');
var parameters = {
from: '2015-05-07T00:00:00+0000'
, to: '2015-05-07T23:59:59+0000'
, limit: 5
};

client.suppressionList.search(parameters, function(err, data) {
if(err) {
console.log(err);
return;
}

console.log(data.body);
});

```

Check out all the examples provided [here](/examples/suppressionList).
50 changes: 50 additions & 0 deletions docs/resources/templates.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Templates

This library provides easy access to the [Templates](https://www.sparkpost.com/api#/reference/templates/) Resource.

## Methods
* **all(callback)**
List a summary of all templates.
* `callback` - executed after task is completed. **required**
* standard `callback(err, data)`
* `err` - any error that occurred
* `data.res` - full response from request client
* `data.body` - payload from response
* **find(options, callback)**
Retrieve details about a specified template by its id
* `options.id` - the id of the template you want to look up **required**
* `options.draft` - specifies a draft or published template
* `callback` - see all function
* **create(options, callback)**
Create a new recipient list
* `options.template` - a template object **required**
* `callback` - see all function
* **delete(id, callback)**
Delete an existing template
* `id` - the id of the template you want to delete **required**
* `callback` - see all function
* **preview(options, callback)**
Preview the most recent version of an existing template by id
* `options.id` - the id of the template you want to look up **required**
* `options.data` - Object of substitution data
* `options.draft` - specifies a draft or published template
* `callback` - see all function

## Examples

```js
var SparkPost = require('sparkpost');
var client = new SparkPost('YOUR_API_KEY');

client.templates.all(function(err, data) {
if(err) {
console.log(err);
return;
}

console.log(data.body);
});

```

Check out all the examples provided [here](/examples/templates).
Loading

0 comments on commit cb81a45

Please sign in to comment.