Updated transmission docs and examples.

SparkPost · Jun 16, 2015 · a221c57 · a221c57
1 parent be389b5
commit a221c57
Show file tree

Hide file tree

Showing 8 changed files with 87 additions and 60 deletions.
diff --git a/docs/resources/transmissions.md b/docs/resources/transmissions.md
@@ -3,17 +3,23 @@
 This library provides easy access to the [Transmissions](https://www.sparkpost.com/api#/reference/transmissions/) Resource.
 
 ## Methods
-* **all(callback)**
-  List an overview of all transmissions in the account.
+* **all(options, callback)**
+  List an overview of all transmissions in the account
+  * `options.campaign_id` - id of the campaign used by the transmission
+  * `options.template_id` - id of the template used by the transmission
   * `callback` - executed after task is completed. **required**
     * standard `callback(err, data)`
     * `err` - any error that occurred
     * `data` - full response from request client
 * **find(transmissionID, callback)**
   Retrieve the details about a transmission by its ID
-  * `transmissionID` - the id of the transmission you want to look up **required**
+  * `transmissionID` - id of the transmission you want to look up **required**
+  * `callback` - see all function
+* **send(options, callback)**
+  Sends a message by creating a new transmission
+  * `options.transmissionBody` - a transmission object **required**
+  * `options.num_rcpt_errors` - maximum number of recipient errors returned
   * `callback` - see all function
-* **send(transmissionBody, callback)**
 
 
 ## Getting Started: Your First Mailing
@@ -22,23 +28,25 @@ This library provides easy access to the [Transmissions](https://www.sparkpost.c
 var SparkPost = require('sparkpost')
   , client = new SparkPost('YOUR API KEY');
 
-var trans = {};
+var trans = {
+  content: {}
+};
 
 // Set some metadata for your email
-trans.campaign = 'first-mailing';
-trans.from = 'you@your-company.com';
-trans.subject = 'First SDK Mailing';
+trans.campaignId = 'first-mailing';
+trans.content.from = 'you@your-company.com';
+trans.content.subject = 'First SDK Mailing';
 
 // 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.content.html = '<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>';
+trans.content.text = 'Congratulations, {{name}}!! You just sent your very first mailing!';
 trans.substitutionData = {name: 'YOUR FIRST NAME'};
 
 // Pick someone to receive your email
 trans.recipients = [{ address: { name: 'YOUR FULL NAME', email: 'YOUR EMAIL ADDRESS' } }];
 
 // Send it off into the world!
-client.transmissions.send(trans, function(err, res) {
+client.transmissions.send({transmissionBody: trans}, function(err, res) {
   if (err) {
     console.log('Whoops! Something went wrong');
     console.log(err);
@@ -47,31 +55,7 @@ client.transmissions.send(trans, function(err, res) {
   }
 });
 ```
-
-## 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.
+Check out all the examples provided [here](/examples/transmissions).
 
 ## Tips and Tricks
 * If you specify a stored recipient list and inline recipients in a Transmission, you will receive an error.

diff --git a/examples/transmissions/get_transmissions_by_campaign.js b/examples/transmissions/get_transmissions_by_campaign.js
@@ -0,0 +1,17 @@
+'use strict';
+
+var key = 'YOURAPIKEY'
+  , SparkPost = require('sparkpost')
+  , client = new SparkPost(key)
+  , options = {
+    campaign_id: 'my_campaign'
+  };
+
+client.transmissions.all(options, function(err, res) {
+  if (err) {
+    console.log(err);
+  } else {
+    console.log(res.body);
+    console.log('Congrats you can use our SDK!');
+  }
+});
diff --git a/examples/transmissions/get_transmissions_by_template.js b/examples/transmissions/get_transmissions_by_template.js
@@ -0,0 +1,17 @@
+'use strict';
+
+var key = 'YOURAPIKEY'
+  , SparkPost = require('sparkpost')
+  , client = new SparkPost(key)
+  , options = {
+    template_id: 'my_template'
+  };
+
+client.transmissions.all(options, function(err, res) {
+  if (err) {
+    console.log(err);
+  } else {
+    console.log(res.body);
+    console.log('Congrats you can use our SDK!');
+  }
+});
diff --git a/examples/transmissions/mime_parts.js b/examples/transmissions/mime_parts.js
@@ -5,13 +5,17 @@ var key = 'YOURAPIKEY'
   , client = new SparkPost(key);
 
 var trans = {
-  from: 'From Envelope <from@example.com>',
   recipients: [{ address: { email: 'john.doe@example.com' } }],
-  subject: 'Example Email for MIME Parts',
-  html: '<html><body><p>Hello World!</p></body></html>',
-  text: 'Hello World!',
-  trackOpens: true,
-  trackClicks: true
+  content: {
+    from: 'From Envelope <from@example.com>',
+    subject: 'Example Email for MIME Parts',
+    html: '<html><body><p>Hello World!</p></body></html>',
+    text: 'Hello World!'
+  },
+  options: {
+    open_tracking: true,
+    click_tracking: true
+  }
 };
 
 client.transmissions.send({transmissionBody: trans}, function(err, res) {

diff --git a/examples/transmissions/rfc822.js b/examples/transmissions/rfc822.js
@@ -5,10 +5,10 @@ var key = 'YOURAPIKEY'
   , client = new SparkPost(key);
 
 var trans = {
-  recipients: [{ address: { email: 'john.doe@example.com' } }],
-  rfc822: 'Content-Type: text/plain\nFrom: From Envelope <from@example.com>\nSubject: Example Email\n\nHello World',
-  from: 'From Envelope <from@example.com>',
-  subject: 'Example Email for RFC-822 Content'
+  recipients: [{address: {email: 'john.doe@example.com'}}],
+  content: {
+    email_rfc822: 'Content-Type: text/plain\nFrom: From Envelope <from@example.com>\nSubject: Example Email\n\nHello World'
+  }
 };
 
 client.transmissions.send({transmissionBody: trans}, function(err, res) {

diff --git a/examples/transmissions/stored_recipients_inline_content.js b/examples/transmissions/stored_recipients_inline_content.js
@@ -5,11 +5,13 @@ var key = 'YOURAPIKEY'
   , client = new SparkPost(key);
 
 var trans = {
-  from: 'From Envelope <from@example.com>',
-  recipient_list: 'example-list',
-  subject: 'Example Email for Stored List and Inline Content',
-  html: '<html><body><p>Hello World</p></body></html>',
-  text: 'Hello World!'
+  listId: 'example-list',
+  content: {
+    from: 'From Envelope <from@example.com>',
+    subject: 'Example Email for Stored List and Inline Content',
+    html: '<html><body><p>Hello World</p></body></html>',
+    text: 'Hello World!'
+  }
 };
 
 client.transmissions.send({transmissionBody: trans}, function(err, res) {

diff --git a/examples/transmissions/stored_recipients_stored_content.js b/examples/transmissions/stored_recipients_stored_content.js
@@ -5,11 +5,12 @@ var key = 'YOURAPIKEY'
   , client = new SparkPost(key);
 
 var trans = {
-  from: 'From Envelope <from@example.com>',
-  subject: 'Example Email for Stored List and Template',
-  recipient_list: 'example-list',
-  template: 'my-template',
-  recipients: [{ address: { email: 'john.doe@example.com' } }]
+  listId: 'example-list',
+  content: {
+    from: 'From Envelope <from@example.com>',
+    subject: 'Example Email for Stored List and Template',
+    templateId: 'my-template'
+  }
 };
 
 client.transmissions.send({transmissionBody: trans}, function(err, res) {

diff --git a/examples/transmissions/stored_template_send.js b/examples/transmissions/stored_template_send.js
@@ -5,10 +5,12 @@ var key = 'YOURAPIKEY'
   , client = new SparkPost(key);
 
 var trans = {
-  template: 'my-template',
-  from: 'From Envelope <example@sparkpostbox.com>',
-  subject: 'Example Email for Stored Template',
-  recipients: [{ address: { email: 'john.doe@example.com' } }]
+  recipients: [{ address: { email: 'john.doe@example.com' } }],
+  content: {
+    templateId: 'my-template',
+    from: 'From Envelope <example@sparkpostbox.com>',
+    subject: 'Example Email for Stored Template'
+  }
 };
 
 client.transmissions.send({transmissionBody: trans}, function(err, res) {