SDK Reference

Node.js SDK

Official Node.js SDK for SimplySend to easily send emails and manage your domains, templates, and subscribers.

Installation

Install the SimplySend SDK using your package manager of choice. The SDK requires **Node.js 22 or higher** and comes with zero runtime dependencies.

npm install simplysend

Initialization

Import the specific client class for your required API (Transactional, Marketing, or Web Setup) and initialize it with your Account ID and API key.

import {
  SimplySendTransactionalClient,
  SimplySendMarketingClient,
  SimplySendWebSetupClient
} from 'simplysend';

// 1. Transactional Email Client
const transactionalClient = new SimplySendTransactionalClient({
  accountId: 'your_account_id_here',   // Mandatory
  apiKey: 'your_api_key_here'          // API Key
});

// 2. Marketing Email Client
const marketingClient = new SimplySendMarketingClient({
  accountId: 'your_account_id_here',   // Mandatory
  apiKey: 'your_api_key_here'          // API Key
});

// 3. Web Setup Client
const webSetupClient = new SimplySendWebSetupClient({
  accountId: 'your_account_id_here',   // Mandatory
  apiKey: 'your_api_key_here'          // API Key
});

Sending Transactional Emails

Use `SimplySendTransactionalClient` to dispatch transactional emails via the `email.send()` method. You can pass raw file buffers in `attachments` and they will be automatically encoded to base64 for delivery.

import { SimplySendTransactionalClient } from 'simplysend';

// Initialize with accountId and API key (apiKey)
const client = new SimplySendTransactionalClient({
  accountId: 'ss_acc_...',
  apiKey: 'ss_api_key_...'
});

async function sendEmail() {
  try {
    const response = await client.email.send({
      from: '[email protected]',
      to: '[email protected]',
      subject: 'Welcome, {{name}}!',
      html: '<h1>Hello, {{name}}!</h1><p>Thank you for signing up.</p>{{company_address_html}}{{unsubscribe_email_html}}',
      text: 'Hello, {{name}}! Thank you for signing up.', // Recommended plain text fallback
      replyTo: '[email protected]',
      enableClickTracking: true,
      enableOpenTracking: true,
      idempotencyKey: 'optional_unique_uuid_here', // Optional: to prevent duplicate sends
      templateVariables: {
        name: 'Alice'
      },
      attachments: [
        {
          name: 'invoice.pdf',
          contentType: 'application/pdf',
          content: Buffer.from('PDF file content...'), // Automatically base64 encoded by SDK
        }
      ]
    });
    
    console.log('Email sent successfully! Message ID -', response.data?.messageId);
  } catch (error) {
    console.error('Failed to send email:', error.message);
  }
}

sendEmail();

Sending Marketing Emails

Use `SimplySendMarketingClient` to send newsletters or marketing campaigns via the `email.send()` method. It accepts an optional `subscriptionGroupId` to target specific lists and check subscription status. If omitted, global contact opt-in status will be verified directly.

import { SimplySendMarketingClient } from 'simplysend';

// Initialize with accountId and API key (apiKey)
const client = new SimplySendMarketingClient({
  accountId: 'ss_acc_...',
  apiKey: 'ss_api_key_...'
});

async function sendMarketingCampaign() {
  try {
    const response = await client.email.send({
      from: '[email protected]',
      to: '[email protected]',
      subject: 'June Newsletter',
      html: '<h1>Our latest updates...</h1><p>Check out our brand new features.</p>{{company_address_html}}{{unsubscribe_email_html}}',
      subscriptionGroupId: 'sub_group_123', // Optional
      campaignId: 'camp_567', // Optional campaign tracking
      enableClickTracking: true,
      enableOpenTracking: true,
      idempotencyKey: 'optional_unique_uuid_here' // Optional: to prevent duplicate sends
    });
    
    console.log('Newsletter campaign sent! Message ID -', response.data?.messageId);
  } catch (error) {
    console.error('Failed to send campaign:', error.message);
  }
}

sendMarketingCampaign();

Resource Management

Use `SimplySendWebSetupClient` to manage your setup programmatically. The client exposes dedicated namespaces like `domains`, `domainGroups`, `contacts` (which manages contacts directory, subscription groups, and subscriber lists), `templates`, and `webhooks`.

import { SimplySendWebSetupClient } from 'simplysend';

// Initialize with accountId and API key (apiKey)
const client = new SimplySendWebSetupClient({
  accountId: 'ss_acc_...',
  apiKey: 'ss_api_key_...'
});

// 1. Manage domains
const newDomain = await client.domains.create({
  domain: 'example.com',
  useCaseId: 'tx-us-east-1'
});
console.log('DNS Verification records -', newDomain.dnsRecords);

// 2. Manage templates
const newTemplate = await client.templates.create({
  name: 'Welcome Template',
  html: '<h1>Welcome {{name}}!</h1>{{company_address_html}}{{unsubscribe_email_html}}',
  type: 'transactional'
});

// 3. Add subscribers to list
await client.contacts.addSubscriber('sub_group_123', {
  email: '[email protected]',
  firstName: 'Jane',
  consentMethod: 'single_opt_in',
  consentDetails: 'Footer subscription form checkbox'
});

Sample Web Application

We provide a pre-built, premium glassmorphic sample web application to help you quickly test the SimplySend Node.js SDK and preview transactional and marketing email templates. The repository is hosted on GitHub: simply-send-sample-app

Quickstart Guide

Clone the repository:

git clone https://github.com/simply-invent-labs/simply-send-sample-app.git
cd simply-send-sample-app

Configure Environment Settings:
Copy the example environment file and open it to configure your SimplySend credentials:
```
cp .env.example .env
```
Install and Start:
```
npm install
npm start
```
Test locally: Open [http://localhost:3005](http://localhost:3005) in your web browser to dispatch test emails using the interactive dashboard UI.

Error Handling

Handle SDK error responses by checking if they are instance of `SimplySendValidationError` (local checks) or `SimplySendHttpError` (remote API response).

import { SimplySendTransactionalClient, SimplySendHttpError, SimplySendValidationError } from 'simplysend';

try {
  // 1. Instantiation validation (throws locally)
  const client = new SimplySendTransactionalClient({
    accountId: '', // Throws validation error locally
    apiKey: 'ss_api_key_...'
  });

  // 2. Request parameter validation (throws locally)
  await client.email.send({
    from: '[email protected]',
    to: '', // Throws validation error locally
    subject: 'Hello',
    html: '...'
  });
} catch (error) {
  if (error instanceof SimplySendValidationError) {
    // Local validation failed (field check did not hit the network)
    console.error('Validation failed on field:', error.field); // e.g. "accountId", "to"
    console.error('Message:', error.message);
  } else if (error instanceof SimplySendHttpError) {
    // API server responded with a non-2xx status code
    console.error('HTTP Status:', error.statusCode); // e.g. 403, 400
    console.error('Error Code:', error.reasonCode); // e.g. "ACCOUNT_SUSPENDED"
    console.error('Message:', error.message);
  } else {
    // Generic connection/network failure
    console.error('Network/Request Error:', error.message);
  }
}

Transactional Email API Reference

Review all fields and JSON payload specifications for sending transactional emails.

Compliance Guide

Learn how to configure compliance mailing address and unsubscribe templates.

Domains Management API

See how to programmatically register and check DNS settings for sending domains.

Subscriber Management API

Create lists, subscription groups, and import subscribers programmatically.