Sailthru Node.js Client

5.0.5 · active · verified Tue Apr 21

The `sailthru-client` is the official Node.js client library for interacting with the Sailthru REST API. It facilitates common operations such as sending emails, managing user profiles, and executing jobs, primarily communicating in JSON format. The current stable version is `5.0.5`. This library typically sees minor patch releases for bug fixes and dependency updates, with major version increments reserved for significant internal refactors or breaking changes in API interaction or environment requirements. Key differentiators include its direct integration with the Sailthru ecosystem, handling API authentication, rate limiting information, and supporting various HTTP methods including multipart uploads for tasks like importing user data. It's designed for server-side Node.js applications and has a clear focus on robust API interaction rather than front-end integration.

Common errors

```
TypeError: sailthru.createSailthruClient is not a function
```
cause Attempting to use ES module import syntax (`import { createSailthruClient } from 'sailthru-client';`) in a CommonJS environment, or incorrect destructuring for a CommonJS module.

fix Use CommonJS `require` syntax: `const sailthruClient = require('sailthru-client'); const sailthru = sailthruClient.createSailthruClient(apiKey, apiSecret);`
```
Error: Invalid API Key/Secret
```
cause The provided API key or secret is incorrect, missing, or has insufficient permissions for the attempted operation.

fix Double-check your `SAILTHRU_API_KEY` and `SAILTHRU_API_SECRET` values against your Sailthru account. Ensure they are correctly configured in your environment variables or code. Verify API key permissions for the specific API calls being made.
```
Error: getaddrinfo ENOTFOUND api.example.com
```
cause The `apiUrl` option provided during client initialization is incorrect or points to an unreachable host.

fix Verify the `apiUrl` option. The default is `'api.sailthru.com'`. If you're using a custom API endpoint, ensure it is correct and resolvable. Check network connectivity to the API host.
```
Error when using apiPost with multipart in v5.0.1: 'Signature hash does not match'
```
cause Reported issue on GitHub where multipart uploads with `v5.0.1` could lead to signature mismatch errors, especially for specific API endpoints like `job` imports.

fix This was a known issue in `v5.0.1`. Consider upgrading to `v5.0.4` or newer, as subsequent patch releases (like `v5.0.4` and `v5.0.5`) addressed issues related to `Sailthru Util` which could impact multipart requests.

Warnings

breaking Node.js engine support changed. Applications must now run on Node.js version `18.14.0` or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js runtime to version 18.14.0 or newer. Consider using a Node Version Manager (NVM) for easy switching.
breaking The constructor signature for `createSailthruClient` changed in `v4.0.0`. Optional parameters like `proxyUrl` and `apiUrl` are no longer directly passed as separate arguments but must be provided within a configuration object as the third argument.
Fix: Refactor client initialization: `createSailthruClient(apiKey, apiSecret, { agent: new ProxyAgent(proxyUrl), apiUrl: 'api.example.com' });`
gotcha Older versions of the client (prior to `v5.0.1`) could encounter 'JavaScript heap out of memory' issues when performing large multipart uploads via `apiPostMultiPart` (e.g., ~200MB files).
Fix: Ensure you are using `sailthru-client` version `5.0.1` or newer to avoid memory issues with large file uploads. If upgrading is not immediately possible, consider splitting large files or optimizing the upload process.
gotcha Between Node.js 7 and 8, changes in the `fs` module caused import jobs to fail with older versions of the `sailthru-client` that relied on the unmaintained `restler` dependency. This was fixed by updating to `restler-base` in `v3.0.4` and later `needle` in `v5.0.0`.
Fix: Upgrade `sailthru-client` to `v3.0.4` or newer to ensure compatibility with modern Node.js `fs` module behavior, especially for multipart job imports.
gotcha The internal logging mechanism changed from `Node Util` to `console.log` in `v5.0.3`. While not a breaking API change, developers who were relying on specific `Node Util` output formatting or redirection for debugging might observe differences.
Fix: Adjust any custom logging parsers or debugging scripts that relied on the previous Node Util-based output format. Standard `console.log` output should now be expected.

Install

npm install sailthru-client npm
yarn add sailthru-client yarn
pnpm add sailthru-client pnpm

Imports

createSailthruClient
wrong:
```
import { createSailthruClient } from 'sailthru-client';
```
correct:
```
const sailthru = require('sailthru-client').createSailthruClient(apiKey, apiSecret, options);
```
The `sailthru-client` library is primarily a CommonJS module. Use `require()` for client initialization. ESM `import` syntax is not officially supported or documented.
VERSION
wrong:
```
import { VERSION } from 'sailthru-client';
```
correct:
```
const version = require('sailthru-client').VERSION;
```
Access the client library's version directly from the module's exports using `require()`.
ProxyAgent
wrong:
```
import { ProxyAgent } from 'proxy-agent';
```
correct:
```
const ProxyAgent = require('proxy-agent');
```
The `ProxyAgent` class is from the separate `proxy-agent` npm package, not `sailthru-client`. It is used to configure proxy settings for the Sailthru client. Ensure `proxy-agent` is installed if needed.

Quickstart

This quickstart demonstrates how to initialize the Sailthru client with API credentials and optional proxy settings, then make an `apiPost` call to add a user's email to a specified list, including error handling.

const ProxyAgent = require('proxy-agent');
const sailthruClient = require('sailthru-client');

const apiKey = process.env.SAILTHRU_API_KEY ?? '';
const apiSecret = process.env.SAILTHRU_API_SECRET ?? '';
const proxyUrl = process.env.HTTP_PROXY || ''; // e.g., 'http://168.63.43.102:3128'

const clientOptions = {};
if (proxyUrl) {
  clientOptions.agent = new ProxyAgent(proxyUrl);
}

const sailthru = sailthruClient.createSailthruClient(apiKey, apiSecret, clientOptions);

// Enable logging for debugging (optional)
sailthru.enableLogging();

// Make a POST request to add an email to a list
const data = {
  email: 'testuser@example.com',
  lists: {
    'my-newsletter-list': 1 // 1 for subscribe, 0 for unsubscribe
  },
  vars: {
    firstName: 'Test',
    lastName: 'User'
  }
};

sailthru.apiPost('email', data, function(err, response) {
  if (err) {
    console.error('Error adding email:', err.message || err);
    // Log detailed error from Sailthru API if available
    if (err.statusCode) console.error('Status Code:', err.statusCode);
    if (err.error) console.error('Error Code:', err.error);
    if (err.errormsg) console.error('Error Message:', err.errormsg);
  } else {
    console.log('Successfully added email to list:', response);
  }
});

view raw JSON →