{"id":15817,"library":"sailthru-client","title":"Sailthru Node.js Client","description":"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.","status":"active","version":"5.0.5","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/sailthru/sailthru-node-client","tags":["javascript"],"install":[{"cmd":"npm install sailthru-client","lang":"bash","label":"npm"},{"cmd":"yarn add sailthru-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add sailthru-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required if the client application needs to route its HTTP requests through an upstream proxy server. Used for `agent` option during client initialization.","package":"proxy-agent","optional":true}],"imports":[{"note":"The `sailthru-client` library is primarily a CommonJS module. Use `require()` for client initialization. ESM `import` syntax is not officially supported or documented.","wrong":"import { createSailthruClient } from 'sailthru-client';","symbol":"createSailthruClient","correct":"const sailthru = require('sailthru-client').createSailthruClient(apiKey, apiSecret, options);"},{"note":"Access the client library's version directly from the module's exports using `require()`.","wrong":"import { VERSION } from 'sailthru-client';","symbol":"VERSION","correct":"const version = require('sailthru-client').VERSION;"},{"note":"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.","wrong":"import { ProxyAgent } from 'proxy-agent';","symbol":"ProxyAgent","correct":"const ProxyAgent = require('proxy-agent');"}],"quickstart":{"code":"const ProxyAgent = require('proxy-agent');\nconst sailthruClient = require('sailthru-client');\n\nconst apiKey = process.env.SAILTHRU_API_KEY ?? '';\nconst apiSecret = process.env.SAILTHRU_API_SECRET ?? '';\nconst proxyUrl = process.env.HTTP_PROXY || ''; // e.g., 'http://168.63.43.102:3128'\n\nconst clientOptions = {};\nif (proxyUrl) {\n  clientOptions.agent = new ProxyAgent(proxyUrl);\n}\n\nconst sailthru = sailthruClient.createSailthruClient(apiKey, apiSecret, clientOptions);\n\n// Enable logging for debugging (optional)\nsailthru.enableLogging();\n\n// Make a POST request to add an email to a list\nconst data = {\n  email: 'testuser@example.com',\n  lists: {\n    'my-newsletter-list': 1 // 1 for subscribe, 0 for unsubscribe\n  },\n  vars: {\n    firstName: 'Test',\n    lastName: 'User'\n  }\n};\n\nsailthru.apiPost('email', data, function(err, response) {\n  if (err) {\n    console.error('Error adding email:', err.message || err);\n    // Log detailed error from Sailthru API if available\n    if (err.statusCode) console.error('Status Code:', err.statusCode);\n    if (err.error) console.error('Error Code:', err.error);\n    if (err.errormsg) console.error('Error Message:', err.errormsg);\n  } else {\n    console.log('Successfully added email to list:', response);\n  }\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18.14.0 or newer. Consider using a Node Version Manager (NVM) for easy switching.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Refactor client initialization: `createSailthruClient(apiKey, apiSecret, { agent: new ProxyAgent(proxyUrl), apiUrl: 'api.example.com' });`","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":"<5.0.1"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"<3.0.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.3"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use CommonJS `require` syntax: `const sailthruClient = require('sailthru-client'); const sailthru = sailthruClient.createSailthruClient(apiKey, apiSecret);`","cause":"Attempting to use ES module import syntax (`import { createSailthruClient } from 'sailthru-client';`) in a CommonJS environment, or incorrect destructuring for a CommonJS module.","error":"TypeError: sailthru.createSailthruClient is not a function"},{"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.","cause":"The provided API key or secret is incorrect, missing, or has insufficient permissions for the attempted operation.","error":"Error: Invalid API Key/Secret"},{"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.","cause":"The `apiUrl` option provided during client initialization is incorrect or points to an unreachable host.","error":"Error: getaddrinfo ENOTFOUND api.example.com"},{"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.","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.","error":"Error when using apiPost with multipart in v5.0.1: 'Signature hash does not match'"}],"ecosystem":"npm"}