SparkPost Node.js Client

The SparkPost Node.js client provides methods to manage your Suppression List, which contains email addresses that should not receive further communications.

All methods in this library return Promises and also accept an optional callback as the last argument.

Supported operations include:

• list([parameters]): Retrieve entries filtered by search parameters.
• get(email): Retrieve a specific entry by the recipient's email address.
• upsert(listEntries): Insert or update one or many entries. Accepts a single entry object or an array of entry objects.
• delete(email): Remove an entry by the recipient's email address.

The library may not wrap every SparkPost API resource (e.g., the Metrics resource). You can use the base object methods to perform requests to these unwrapped resources by providing a uri in the options object.

All methods return Promises and accept an optional callback.

// Example: Accessing the Metrics resource via the base object
const options = {
  uri: 'metrics/domains'
};

client.get(options)
  .then(data => {
    console.log(data);
  })
  .catch(err => {
    console.log(err);
  });

Guidelines for handling primitive and complex data types:

Strings

• Use single-quoted strings exclusively.
• For strings longer than 80 characters, use string concatenation across multiple lines.
• Use Array.join() instead of concatenation when building strings programmatically.
• Avoid building HTML strings; manipulate the DOM directly instead.

Arrays

• Use literal syntax ([]) for creation rather than new Array().
• Use Array.push() to add elements to the end of an array.
• Use Array.slice() to clone arrays.
• Do not use associative arrays (e.g., arr['key'] = value). Use an Object or a Map instead.

// Array best practices
var items = [];

var stack = [];
stack.push('element');

var src = [1, 2, 3];
var dst = src.slice();

// Use Objects for key-value pairs, not Arrays
var items = {};
items.animal = 'dog';

This guide outlines the coding standards and conventions used within the SparkPost Node SDK. Adhering to these patterns ensures consistency, readability, and maintainability when contributing to or working with the codebase.

Key areas covered include:

• Comments: Using JSDoc for documentation and proper formatting for single/multiline comments.
• Whitespace & Semicolons: Standardizing indentation (2-space soft tabs) and enforcing semicolon usage to avoid ASI (Automatic Semicolon Insertion) issues.
• Blocks & Functions: Proper brace placement and function declaration patterns.
• Conditions & Equality: Favoring explicit equality (===) and specific comparison patterns.
• Library Usage: Guidelines on when to use native JavaScript versus external libraries like Lo-dash.
• Composition: Avoiding deep method chaining in favor of temporary variables.

If you prefer using callbacks, you can pass a callback function as the final argument to any library method. The library follows the standard Node.js error-first callback pattern: (err, data) => { ... }.

let client = new SparkPost(key);

client.templates.get(id, (err, data) => {
  if (err) {
    // handle the sad error
    return;
  }

  // this is the full API response body
});

Install the official SparkPost Node.js binding using npm:

npm install sparkpost

Note: Node.js versions 0.10 and 0.12 are no longer supported.

Before submitting a new issue to the SparkPost repository, follow these steps to ensure it can be resolved efficiently:

1. Search for existing issues: Check the existing issues list to prevent duplication.
2. Provide a meaningful title: Give your issue a clear and descriptive name.
3. Include required technical details:
   • Operating System and Version
   • Programming language version
   • Exception, error, or issue summary
   • Recreation steps or a Use case summary
   • Example data (if available)
   • Expected result or desired functionality
   • Any additional relevant information
4. Maintain professional conduct: Avoid trolling or flaming comments.
5. Monitor your issue: Follow or watch the issue to respond to contributor questions or requests for more information.

All methods in the SparkPost Node.js client library return Promises by default. You can use .then() to handle successful API responses and .catch() to handle errors.

let client = new SparkPost(key);

client.templates.get(id)
  .then((data) => {
    // this the full API response body
  })
  .catch((err) => {
    // handle the sad error
  });

When using transmissions.send(), the library provides automatic payload formatting for recipient addresses and headers if the recipients field is an array.

Address Formatting:

• You can provide addresses as strings (e.g., "Name" <email@example.com> or just email@example.com).
• The library converts these into the required object format: { name: '...', email: '...' }.

CC and BCC Handling:

• If you provide a cc or bcc array of recipients, the library will:
  1. Generate the appropriate CC header in content.headers.CC.
  2. Convert cc and bcc recipients into the standard recipients list.
  3. Automatically set the header_to property on CC/BCC recipients so they are excluded from the primary To header in the email metadata.