sendwithus
v6.0.2
Published
Sendwithus.com Node.js client
Downloads
10,878
Maintainers
Readme
sendwithus node-client
Installation
npm install sendwithus
Usage
All callbacks accept err
and response
:
const callback = function(err, response) {
if (err) {
console.log({message: err.message, status: response.status, statusText: response.statusText});
} else {
console.log(response);
}
};
Templates
List Your Templates
var api = require('sendwithus')('API_KEY');
api.templates(callback);
Create Template
var api = require('sendwithus')('API_KEY');
var data = { name: 'name', subject: 'subject', html: '<html><head></head><body></body></html>', text: 'some text' };
api.createTemplate(data, callback);
Create Template Version
var api = require('sendwithus')('API_KEY');
var data = { name: 'name', subject: 'subject', html: '<html><head></head><body></body></html>', text: 'some text' };
api.createTemplateVersion(TEMPLATE_ID, data, callback);
Send
Send an Email
NOTE - If a customer does not exist by the specified email (recipient address), the send call will create a customer.
- template — Template ID to send
- recipient
- address — The recipient's email address
- name (optional) — The recipient's name
- template_data (optional) — Object containing email template data
- sender (optional)
- address — The sender's email address
- reply_to (optional) — The sender's reply-to address
- name (optional) — The sender's name
- cc (optional) — An array of CC recipients, of the format {"address":"[email protected]"}
- bcc (optional) — An array of BCC recipients, of the format {"address":"[email protected]"}
- headers (optional) — Object contain SMTP headers to be included with the email
- esp_account (optional) — ID of the ESP Account to send this email through. ex: esp_1a2b3c4d5e
- locale (optional) — Template locale to send (ie: en-US)
- version_name (optional) — Template version to send (ie: Version A)
Call with REQUIRED parameters only
The template_data
field is optional, but highly recommended!
var api = require('sendwithus')('API_KEY');
api.send({
template: 'TEMPLATE_ID',
recipient: { address: '[email protected]' }
}, callback);
Call with REQUIRED parameters and template_data
var api = require('sendwithus')('API_KEY');
api.send({
template: 'TEMPLATE_ID',
recipient: {
address: '[email protected]', // required
name: 'Matt and Brad'
},
template_data: { first_name: 'Matt' }
}, callback);
Optional Sender
sender['address']
is a required sender field
var api = require('sendwithus')('API_KEY');
api.send({
template: 'TEMPLATE_ID',
recipient: { address: '[email protected]' },
template_data: { first_name: 'Matt' },
sender: {
address: '[email protected]', // required
name: 'Company'
}
}, callback);
Optional Sender with reply_to address
sender['name']
and sender['reply_to']
are both optional
var api = require('sendwithus')('API_KEY');
api.send({
template: 'TEMPLATE_ID',
recipient: { address: '[email protected]' },
template_data: { first_name: 'Matt' },
sender: {
address: '[email protected]', // required
name: 'Company',
reply_to: '[email protected]'
}
}, callback);
Optional BCC/CC
var api = require('sendwithus')('API_KEY');
api.send({
template: TEMPLATE_ID,
recipient: { address: '[email protected]' },
bcc: [{ address: '[email protected]' }],
cc: [
{ address: '[email protected]' },
{ address: '[email protected]' }
]
}, callback);
Optional Headers
var api = require('sendwithus')('API_KEY');
api.send({
template: TEMPLATE_ID,
recipient: { address: '[email protected]' },
headers:{ 'X-HEADER-ONE': 'header-value' }
}, callback);
Optional ESP Account
var api = require('sendwithus')('API_KEY');
api.send({
template: TEMPLATE_ID,
recipient: { address: '[email protected]' },
esp_account:'esp_1234asdf1234'
}, callback);
Optional Locale
var api = require('sendwithus')('API_KEY');
api.send({
template: TEMPLATE_ID,
recipient: { address: '[email protected]' },
locale:'en-US'
}, callback);
Optional Version
var api = require('sendwithus')('API_KEY');
api.send({
template: TEMPLATE_ID,
recipient: { address: '[email protected]' },
version_name:'Version A'
}, callback);
Customers
Update or Create a Customer
var api = require('sendwithus')('API_KEY');
api.customersUpdateOrCreate({
email: '[email protected]',
locale: 'fr-CA'
}, callback);
Delete a Customer
var api = require('sendwithus')('API_KEY');
api.customersDelete('[email protected]', callback);
Drip Campaigns
List Drip Campaigns
var api = require('sendwithus')('API_KEY');
api.dripCampaignList(callback);
Show Drip Campaign Details
var api = require('sendwithus')('API_KEY');
api.dripCampaignDetails('DRIP_CAMPAIGN_ID', callback);
Start Customer on a Drip Campaign
var api = require('sendwithus')('API_KEY');
var data = {
recipient: {
address: 'RECIPIENT_ADDRESS',
name: 'RECIPIENT_NAME'
},
email_data: {
country: 'Latveria'
}
}
api.dripCampaignActivate('DRIP_CAMPAIGN_ID', data, callback);
Remove Customer from a Single Drip Campaign
var api = require('sendwithus')('API_KEY');
var data = { recipient_address: 'RECIPIENT_ADDRESS' };
api.dripCampaignDeactivate('DRIP_CAMPAIGN_ID', data, callback);
Remove Customer from All Drip Campaigns
var api = require('sendwithus')('API_KEY');
var data = { recipient_address: 'RECIPIENT_ADDRESS' };
api.dripCampaignDeactivateAll(data, callback);
Expected Response
Success
> response.status;
OK
> response.success;
True
> response.receipt_id;
'numeric-receipt-id'
Error cases
- malformed request
> err.statusCode;
400
- bad API key
> err.statusCode;
403
Render
Render an Email
var api = require('sendwithus')('API_KEY');
api.render({ template: 'SAMPLE_TEMPLATE_ID', template_data: { name: 'Bob' }, strict: true }, callback);
Optional Locale
var api = require('sendwithus')('API_KEY');
api.render({
template: 'SAMPLE_TEMPLATE_ID',
template_data: { name: 'Bob' },
locale: 'en-US',
strict: true
}, callback);
Optional Template Version
var api = require('sendwithus')('API_KEY');
api.render({
template: 'SAMPLE_TEMPLATE_ID',
template_data: { name: 'Bob' },
version_id: 'SAMPLE_VERSION_ID',
strict: true
}, callback);
Sample Response
{
"success": true,
"status": "OK",
"template": {
"id": "ver_r4nd0ml3tt3rsv15h4l0l",
"name": "Template name",
"version_name": "Template version name",
"locale": "en-US"
},
"subject": "RENDERED SUBJECT WITH DATA",
"html": "RENDERED HTML BODY WITH DATA",
"text": "RENDERED TEXT BODY WITH DATA"
}
Logs
Resend
var api = require('sendwithus')('API_KEY');
api.resend({"log_id": "log_asdf123456qwerty"}, callback);
Batch
Send
var api = require('sendwithus')('API_KEY');
api.batch([{
"path": "/api/v1/send",
"method": "POST",
"body": {
"template": "TEMPLATE_ID",
"recipient": {
"address": "[email protected]"
}
}
}, {
"path": "/api/v1/send",
"method": "POST",
"body": {
"template": "TEMPLATE_ID",
"recipient": {
"address": "[email protected]"
}
}
}], callback);
Events
request: function(method, url, headers, body)
- emitted when a request has been sent to Sendwithusresponse: function(statusCode, body, response)
- emitted when a response has been received back from Sendwithus
Run Tests
Install requirements
npm install
Run Unit Tests
npm test
Troubleshooting
General Troubleshooting
- Enable debug mode
- Make sure you're using the latest Node client
- Capture the response data and check your logs — often this will have the exact error
Enable Debug Mode
Debug mode prints out the underlying request information as well as the data payload that gets sent to Sendwithus. You will most likely find this information in your logs. To enable it, simply put debug=true
as a parameter when instantiating the API object. Use the debug mode to compare the data payload getting sent to Sendwithus' API docs.
var api = require('sendwithus')('API_KEY', debug=true);
Response Ranges
Sendwithus' API typically sends responses back in these ranges:
- 2xx – Successful Request
- 4xx – Failed Request (Client error)
- 5xx – Failed Request (Server error)
If you're receiving an error in the 400 response range follow these steps:
- Double check the data and ID's getting passed to Sendwithus
- Ensure your API key is correct
- Log and check the body of the response