Skip to content

Commit 137b11d

Browse files
aydrianaydrian
committed
Merge pull request #80 from aydrian/ISSUE-76
Updated transmission docs and examples.
2 parents be389b5 + 1ebd0d3 commit 137b11d

9 files changed

+163
-124
lines changed

‎docs/resources/transmissions.md

Lines changed: 25 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,23 @@
33
This library provides easy access to the [Transmissions](https://www.sparkpost.com/api#/reference/transmissions/) Resource.
44

55
## Methods
6-
* **all(callback)**
7-
List an overview of all transmissions in the account.
6+
* **all(options, callback)**
7+
List an overview of all transmissions in the account
8+
* `options.campaign_id` - id of the campaign used by the transmission
9+
* `options.template_id` - id of the template used by the transmission
810
* `callback` - executed after task is completed. **required**
911
* standard `callback(err, data)`
1012
* `err` - any error that occurred
1113
* `data` - full response from request client
1214
* **find(transmissionID, callback)**
1315
Retrieve the details about a transmission by its ID
14-
* `transmissionID` - the id of the transmission you want to look up **required**
16+
* `transmissionID` - id of the transmission you want to look up **required**
17+
* `callback` - see all function
18+
* **send(options, callback)**
19+
Sends a message by creating a new transmission
20+
* `options.transmissionBody` - a transmission object **required**
21+
* `options.num_rcpt_errors` - maximum number of recipient errors returned
1522
* `callback` - see all function
16-
* **send(transmissionBody, callback)**
1723

1824

1925
## Getting Started: Your First Mailing
@@ -22,23 +28,21 @@ This library provides easy access to the [Transmissions](https://www.sparkpost.c
2228
var SparkPost = require('sparkpost')
2329
, client = new SparkPost('YOUR API KEY');
2430

25-
var trans = {};
26-
27-
// Set some metadata for your email
28-
trans.campaign = 'first-mailing';
29-
trans.from = '[email protected]';
30-
trans.subject = 'First SDK Mailing';
31-
32-
// Add some content to your email
33-
trans.html = '<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>';
34-
trans.text = 'Congratulations, {{name}}!! You just sent your very first mailing!';
35-
trans.substitutionData = {name: 'YOUR FIRST NAME'};
36-
37-
// Pick someone to receive your email
38-
trans.recipients = [{ address: { name: 'YOUR FULL NAME', email: 'YOUR EMAIL ADDRESS' } }];
31+
var reqObj = {
32+
transmissionBody: {
33+
campaignId: 'first-mailing',
34+
content: {
35+
from: '[email protected]',
36+
subject: 'First SDK Mailing',
37+
html: '<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
38+
text: 'Congratulations, {{name}}!! You just sent your very first mailing!'
39+
},
40+
substitutionData: {name: 'YOUR FIRST NAME'},
41+
recipients: [{ address: { name: 'YOUR FULL NAME', email: 'YOUR EMAIL ADDRESS' } }]
42+
}
43+
};
3944

40-
// Send it off into the world!
41-
client.transmissions.send(trans, function(err, res) {
45+
client.transmissions.send(reqObj, function(err, res) {
4246
if (err) {
4347
console.log('Whoops! Something went wrong');
4448
console.log(err);
@@ -47,31 +51,7 @@ client.transmissions.send(trans, function(err, res) {
4751
}
4852
});
4953
```
50-
51-
## Field Descriptions
52-
### Transmissions
53-
| Field Name | Required? | Description | Data Type |
54-
| ------------ | ----------- | ------------- | ----------- |
55-
| description | no | Field for describing what this transmission is for the user | String |
56-
| campaign | no | Field for assigning a given transmission to a specific campaign, which is a logical container for similar transmissions | String |
57-
| metadata | no | Field for adding arbitrary key/value pairs which will be included in open/click tracking | Object (Simple) |
58-
| substitutionData | no | Field for adding transmission level substitution data, which can be used in a variety of fields and in content | Object (Complex) |
59-
| trackOpens | no | Field for enabling/disabling transmission level open tracking, if not set will use settings from Template | Boolean |
60-
| trackClicks | no | Field for enabling/disabling transmission level click tracking, if not set will use settings from Template | Boolean |
61-
| useSandbox | no | Field for enabling/disabling using sandbox domain to send transmission(You are limited to 50 messages ever with sandbox) | Boolean |
62-
| useDraftTemplate | no | Field for allowing the sending of a transmission using a draft of a stored template (default: false) | Boolean |
63-
| replyTo | no | Field for specifying the email address that should be used when a recipient hits the reply button | String |
64-
| subject | yes | Field for setting the subject line of a given transmission | String |
65-
| from | yes | Field for setting the from line of a given transmission | String or Object |
66-
| html | yes** | Field for setting the HTML content of a given transmission | String |
67-
| text | yes** | Field for setting the Plain Text content of a given transmission | String |
68-
| rfc822 | no** | Field for setting the RFC-822 encoded content of a given transmission | String |
69-
| template | no** | Field for specifying the Template ID of a stored template to be used when sending a given transmission | String |
70-
| customHeaders | no | Field for specifying additional headers to be applied to a given transmission (other than Subject, From, To, and Reply-To) | Object (Simple) |
71-
| recipients | yes** | Field for specifying who a given transmission should be sent to | Array of Objects |
72-
| recipientList | no** | Field for specifying a stored recipient list ID to be used for a given transmission | String |
73-
74-
** - 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.
54+
Check out all the examples provided [here](/examples/transmissions).
7555

7656
## Tips and Tricks
7757
* If you specify a stored recipient list and inline recipients in a Transmission, you will receive an error.

‎examples/transmissions/get_transmissions_by_campaign.js

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
'use strict';
2+
3+
var key = 'YOURAPIKEY'
4+
, SparkPost = require('sparkpost')
5+
, client = new SparkPost(key)
6+
, options = {
7+
campaign_id: 'my_campaign'
8+
};
9+
10+
client.transmissions.all(options, function(err, res) {
11+
if (err) {
12+
console.log(err);
13+
} else {
14+
console.log(res.body);
15+
console.log('Congrats you can use our SDK!');
16+
}
17+
});

‎examples/transmissions/get_transmissions_by_template.js

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
'use strict';
2+
3+
var key = 'YOURAPIKEY'
4+
, SparkPost = require('sparkpost')
5+
, client = new SparkPost(key)
6+
, options = {
7+
template_id: 'my_template'
8+
};
9+
10+
client.transmissions.all(options, function(err, res) {
11+
if (err) {
12+
console.log(err);
13+
} else {
14+
console.log(res.body);
15+
console.log('Congrats you can use our SDK!');
16+
}
17+
});

‎examples/transmissions/mime_parts.js

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,23 @@ var key = 'YOURAPIKEY'
44
, SparkPost = require('sparkpost')
55
, client = new SparkPost(key);
66

7-
var trans = {
8-
from: 'From Envelope <[email protected]>',
9-
recipients: [{ address: { email: '[email protected]' } }],
10-
subject: 'Example Email for MIME Parts',
11-
html: '<html><body><p>Hello World!</p></body></html>',
12-
text: 'Hello World!',
13-
trackOpens: true,
14-
trackClicks: true
7+
var reqObj = {
8+
transmissionBody: {
9+
recipients: [{ address: { email: '[email protected]' } }],
10+
content: {
11+
from: 'From Envelope <[email protected]>',
12+
subject: 'Example Email for MIME Parts',
13+
html: '<html><body><p>Hello World!</p></body></html>',
14+
text: 'Hello World!'
15+
},
16+
options: {
17+
open_tracking: true,
18+
click_tracking: true
19+
}
20+
}
1521
};
1622

17-
client.transmissions.send({transmissionBody: trans}, function(err, res) {
23+
client.transmissions.send(reqObj, function(err, res) {
1824
if (err) {
1925
console.log(err);
2026
} else {

‎examples/transmissions/rfc822.js

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,16 @@ var key = 'YOURAPIKEY'
44
, SparkPost = require('sparkpost')
55
, client = new SparkPost(key);
66

7-
var trans = {
8-
recipients: [{ address: { email: '[email protected]' } }],
9-
rfc822: 'Content-Type: text/plain\nFrom: From Envelope <[email protected]>\nSubject: Example Email\n\nHello World',
10-
from: 'From Envelope <[email protected]>',
11-
subject: 'Example Email for RFC-822 Content'
7+
var reqObj = {
8+
transmissionBody: {
9+
recipients: [{address: {email: '[email protected]'}}],
10+
content: {
11+
email_rfc822: 'Content-Type: text/plain\nFrom: From Envelope <[email protected]>\nSubject: Example Email\n\nHello World'
12+
}
13+
}
1214
};
1315

14-
client.transmissions.send({transmissionBody: trans}, function(err, res) {
16+
client.transmissions.send(reqObj, function(err, res) {
1517
if (err) {
1618
console.log(err);
1719
} else {

‎examples/transmissions/send_transmission_all_fields.js

Lines changed: 46 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -4,56 +4,58 @@ var key = "YOURAPIKEY"
44
, SparkPost = require("sparkpost")
55
, client = new SparkPost(key);
66

7-
var trans = {
8-
options: {
9-
open_tracking: true,
10-
click_tracking: true
11-
},
12-
campaign_id: "christmas_campaign",
13-
return_path: "[email protected]",
14-
metadata: {
15-
user_type: "students"
16-
},
17-
substitution_data: {
18-
sender: "Big Store Team"
19-
},
20-
recipients: [
21-
{
22-
return_path: "[email protected]",
23-
address: {
24-
email: "[email protected]",
25-
name: "Wilma Flintstone"
7+
var reqOpts = {
8+
transmissionBody: {
9+
options: {
10+
open_tracking: true,
11+
click_tracking: true
12+
},
13+
campaign_id: "christmas_campaign",
14+
return_path: "[email protected]",
15+
metadata: {
16+
user_type: "students"
17+
},
18+
substitution_data: {
19+
sender: "Big Store Team"
20+
},
21+
recipients: [
22+
{
23+
return_path: "[email protected]",
24+
address: {
25+
email: "[email protected]",
26+
name: "Wilma Flintstone"
27+
},
28+
tags: [
29+
"greeting",
30+
"prehistoric",
31+
"fred",
32+
"flintstone"
33+
],
34+
metadata: {
35+
place: "Bedrock"
36+
},
37+
substitution_data: {
38+
customer_type: "Platinum"
39+
}
40+
}
41+
],
42+
content: {
43+
from: {
44+
name: "Fred Flintstone",
45+
email: "[email protected]"
2646
},
27-
tags: [
28-
"greeting",
29-
"prehistoric",
30-
"fred",
31-
"flintstone"
32-
],
33-
metadata: {
34-
place: "Bedrock"
47+
subject: "Big Christmas savings!",
48+
reply_to: "Christmas Sales <[email protected]>",
49+
headers: {
50+
"X-Customer-Campaign-ID": "christmas_campaign"
3551
},
36-
substitution_data: {
37-
customer_type: "Platinum"
38-
}
52+
text: "Hi {{address.name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to {{user_type}}\n {{sender}}",
53+
html: "<p>Hi {{address.name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n</p><p>Hurry, this offer is only to {{user_type}}\n</p><p>{{sender}}</p>"
3954
}
40-
],
41-
content: {
42-
from: {
43-
name: "Fred Flintstone",
44-
email: "[email protected]"
45-
},
46-
subject: "Big Christmas savings!",
47-
reply_to: "Christmas Sales <[email protected]>",
48-
headers: {
49-
"X-Customer-Campaign-ID": "christmas_campaign"
50-
},
51-
text: "Hi {{address.name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to {{user_type}}\n {{sender}}",
52-
html: "<p>Hi {{address.name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n</p><p>Hurry, this offer is only to {{user_type}}\n</p><p>{{sender}}</p>"
5355
}
5456
};
5557

56-
client.transmissions.send({transmissionBody: trans}, function(err, res) {
58+
client.transmissions.send(reqOpts, function(err, res) {
5759
if (err) {
5860
console.log(err);
5961
} else {

‎examples/transmissions/stored_recipients_inline_content.js

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,21 @@ var key = 'YOURAPIKEY'
44
, SparkPost = require('sparkpost')
55
, client = new SparkPost(key);
66

7-
var trans = {
8-
from: 'From Envelope <[email protected]>',
9-
recipient_list: 'example-list',
10-
subject: 'Example Email for Stored List and Inline Content',
11-
html: '<html><body><p>Hello World</p></body></html>',
12-
text: 'Hello World!'
7+
var reqObj = {
8+
transmissionBody: {
9+
recipients: {
10+
list_id: 'example-list'
11+
},
12+
content: {
13+
from: 'From Envelope <[email protected]>',
14+
subject: 'Example Email for Stored List and Inline Content',
15+
html: '<html><body><p>Hello World</p></body></html>',
16+
text: 'Hello World!'
17+
}
18+
}
1319
};
1420

15-
client.transmissions.send({transmissionBody: trans}, function(err, res) {
21+
client.transmissions.send(reqObj, function(err, res) {
1622
if (err) {
1723
console.log(err);
1824
} else {

‎examples/transmissions/stored_recipients_stored_content.js

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,20 @@ var key = 'YOURAPIKEY'
44
, SparkPost = require('sparkpost')
55
, client = new SparkPost(key);
66

7-
var trans = {
8-
from: 'From Envelope <[email protected]>',
9-
subject: 'Example Email for Stored List and Template',
10-
recipient_list: 'example-list',
11-
template: 'my-template',
12-
recipients: [{ address: { email: '[email protected]' } }]
7+
var reqOpts = {
8+
transmissionBody: {
9+
recipients: {
10+
list_id: 'example-list'
11+
},
12+
content: {
13+
from: 'From Envelope <[email protected]>',
14+
subject: 'Example Email for Stored List and Template',
15+
template_id: 'my-template'
16+
}
17+
}
1318
};
1419

15-
client.transmissions.send({transmissionBody: trans}, function(err, res) {
20+
client.transmissions.send(reqOpts, function(err, res) {
1621
if (err) {
1722
console.log(err);
1823
} else {

‎examples/transmissions/stored_template_send.js

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,18 @@ var key = 'YOURAPIKEY'
44
, SparkPost = require('sparkpost')
55
, client = new SparkPost(key);
66

7-
var trans = {
8-
template: 'my-template',
9-
from: 'From Envelope <[email protected]>',
10-
subject: 'Example Email for Stored Template',
11-
recipients: [{ address: { email: '[email protected]' } }]
7+
var reqOpts = {
8+
transmissionBody: {
9+
recipients: [{ address: { email: '[email protected]' } }],
10+
content: {
11+
template_id: 'my-template',
12+
from: 'From Envelope <[email protected]>',
13+
subject: 'Example Email for Stored Template'
14+
}
15+
}
1216
};
1317

14-
client.transmissions.send({transmissionBody: trans}, function(err, res) {
18+
client.transmissions.send(reqOpts, function(err, res) {
1519
if (err) {
1620
console.log(err);
1721
} else {

0 commit comments

Comments
 (0)