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":"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!

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

Call with REQUIRED parameters and template_data

var api = require('sendwithus')('API_KEY');
api.send({
    template: 'TEMPLATE_ID',
    recipient: {
        address: 'us@sendwithus.com', // 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: 'us@sendwithus.com' },
    template_data: { first_name: 'Matt' },
    sender: {
        address: 'company@company.com', // 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: 'us@sendwithus.com' },
    template_data: { first_name: 'Matt' },
    sender: {
        address: 'company@company.com', // required
        name: 'Company',
        reply_to: 'info@company.com'
    }
}, callback);

Optional BCC/CC

var api = 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

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

Optional ESP Account

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

Optional Locale

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

Optional Version

var api = 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

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

Delete a Customer

var api = require('sendwithus')('API_KEY');
api.customersDelete('foo@bar.com', 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": "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.

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

Keywords

FAQs

What is sendwithus?

Is sendwithus popular?

Is sendwithus well maintained?

Package last updated on 13 Jan 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

sendwithus

sendwithus node-client

Installation

Usage

Templates

List Your Templates

Create Template

Create Template Version

Send

Send an Email

Call with REQUIRED parameters only

Call with REQUIRED parameters and template_data

Optional Sender

Optional Sender with reply_to address

Optional BCC/CC

Optional Headers

Optional ESP Account

Optional Locale

Optional Version

Customers

Update or Create a Customer

Delete a Customer

Drip Campaigns

List Drip Campaigns

Show Drip Campaign Details

Start Customer on a Drip Campaign

Remove Customer from a Single Drip Campaign

Remove Customer from All Drip Campaigns

Expected Response

Success

Error cases

Render

Render an Email

Optional Locale

Optional Template Version

Sample Response

Logs

Resend

Batch

Send

Events

Run Tests

Troubleshooting

General Troubleshooting

Enable Debug Mode

Response Ranges

Keywords

Related posts

rv Is a New Rust-Powered Ruby Version Manager Inspired by Python's uv

Nx Investigation Reveals GitHub Actions Workflow Exploit Led to npm Token Theft, Prompting Switch to Trusted Publishing