Skip to content
BranchesTags

Repository files navigation

sendwithus node-client

Build Status

Installation

npm install sendwithus

Usage

All callbacks accept err and response:

constcallback=function(err,response){if(err){console.log({message: err.message,status: response.status,statusText: response.statusText});}else{console.log(response);}};

Templates

List Your Templates

varapi=require('sendwithus')('API_KEY');api.templates(callback);

Create Template

varapi=require('sendwithus')('API_KEY');vardata={name: 'name',subject: 'subject',html: '<html><head></head><body></body></html>',text: 'some text'};api.createTemplate(data,callback);

Create Template Version

varapi=require('sendwithus')('API_KEY');vardata={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":"cc@email.com"}
  • bcc (optional) — An array of BCC recipients, of the format {"address":"bcc@email.com"}
  • 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!

varapi=require('sendwithus')('API_KEY');api.send({template: 'TEMPLATE_ID',recipient: {address: 'us@sendwithus.com'}},callback);

Call with REQUIRED parameters and template_data

varapi=require('sendwithus')('API_KEY');api.send({template: 'TEMPLATE_ID',recipient: {address: 'us@sendwithus.com',// requiredname: 'Matt and Brad'},template_data: {first_name: 'Matt'}},callback);

Optional Sender

sender['address'] is a required sender field

varapi=require('sendwithus')('API_KEY');api.send({template: 'TEMPLATE_ID',recipient: {address: 'us@sendwithus.com'},template_data: {first_name: 'Matt'},sender: {address: 'company@company.com',// requiredname: 'Company'}},callback);

Optional Sender with reply_to address

sender['name'] and sender['reply_to'] are both optional

varapi=require('sendwithus')('API_KEY');api.send({template: 'TEMPLATE_ID',recipient: {address: 'us@sendwithus.com'},template_data: {first_name: 'Matt'},sender: {address: 'company@company.com',// requiredname: 'Company',reply_to: 'info@company.com'}},callback);

Optional BCC/CC

varapi=require('sendwithus')('API_KEY');api.send({template: TEMPLATE_ID,recipient: {address: 'us@sendwithus.com'},bcc: [{address: 'bcc@sendwithus.com'}],cc: [{address: 'cc1@sendwithus.com'},{address: 'cc2@sendwithus.com'}]},callback);

Optional Headers

varapi=require('sendwithus')('API_KEY');api.send({template: TEMPLATE_ID,recipient: {address: 'us@sendwithus.com'},headers:{'X-HEADER-ONE': 'header-value'}},callback);

Optional ESP Account

varapi=require('sendwithus')('API_KEY');api.send({template: TEMPLATE_ID,recipient: {address: 'us@sendwithus.com'},esp_account:'esp_1234asdf1234'},callback);

Optional Locale

varapi=require('sendwithus')('API_KEY');api.send({template: TEMPLATE_ID,recipient: {address: 'us@sendwithus.com'},locale:'en-US'},callback);

Optional Version

varapi=require('sendwithus')('API_KEY');api.send({template: TEMPLATE_ID,recipient: {address: 'us@sendwithus.com'},version_name:'Version A'},callback);

Customers

Update or Create a Customer

varapi=require('sendwithus')('API_KEY');api.customersUpdateOrCreate({email: 'foo@bar.com',locale: 'fr-CA'},callback);

Delete a Customer

varapi=require('sendwithus')('API_KEY');api.customersDelete('foo@bar.com',callback);

Drip Campaigns

List Drip Campaigns

varapi=require('sendwithus')('API_KEY');api.dripCampaignList(callback);

Show Drip Campaign Details

varapi=require('sendwithus')('API_KEY');api.dripCampaignDetails('DRIP_CAMPAIGN_ID',callback);

Start Customer on a Drip Campaign

varapi=require('sendwithus')('API_KEY');vardata={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

varapi=require('sendwithus')('API_KEY');vardata={recipient_address: 'RECIPIENT_ADDRESS'};api.dripCampaignDeactivate('DRIP_CAMPAIGN_ID',data,callback);

Remove Customer from All Drip Campaigns

varapi=require('sendwithus')('API_KEY');vardata={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

varapi=require('sendwithus')('API_KEY');api.render({template: 'SAMPLE_TEMPLATE_ID',template_data: {name: 'Bob'},strict: true},callback);

Optional Locale

varapi=require('sendwithus')('API_KEY');api.render({template: 'SAMPLE_TEMPLATE_ID',template_data: {name: 'Bob'},locale: 'en-US',strict: true},callback);

Optional Template Version

varapi=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

varapi=require('sendwithus')('API_KEY');api.resend({"log_id": "log_asdf123456qwerty"},callback);

Batch

Send

varapi=require('sendwithus')('API_KEY');api.batch([{"path": "/api/v1/send","method": "POST","body": {"template": "TEMPLATE_ID","recipient": {"address": "test+1@mydomain.com"}}},{"path": "/api/v1/send","method": "POST","body": {"template": "TEMPLATE_ID","recipient": {"address": "test+2@mydomain.com"}}}],callback);

Events

  • request: function(method, url, headers, body) - emitted when a request has been sent to Sendwithus
  • response: 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.

varapi=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

About

Sendwithus NodeJS Client

www.sendwithus.com

Resources

Readme
Apache-2.0 license
Activity
Custom properties

Stars

21 stars

Watchers

20 watching

Forks

17 forks
Report repository

Releases

Packages

Used by

Contributors

Languages