@nitrosend/sdk

@nitrosend/sdk

Node.js/TypeScript SDK for the Nitrosend API — manage contacts, send campaigns, build automation flows, and track events programmatically.

Fully typed. Zero dependencies. Node.js 18+.

Installation

npm install @nitrosend/sdk

Get your API key

• Log in at nitrosend.com
• Go to Settings > API Keys
• Copy your live key (starts with nskey_live_)

Quick Start

import { Nitrosend } from '@nitrosend/sdk';

const ns = new Nitrosend('nskey_live_...');

// Create a contact
const contact = await ns.contacts.create({
  email: '[e-mail]',
  firstName: 'Alice',
});

// Fire an event (triggers any matching flows)
await ns.events.create({
  event: 'order_confirmed',
  contactEmail: '[e-mail]',
  idempotencyKey: 'order-123',
  data: { orderId: 123, total: 49.99 },
});

// Send a campaign
const campaign = await ns.campaigns.create({ name: 'March Sale', channelType: 'email' });
await ns.campaigns.send(campaign.id);

// Send a transactional message (receipt, OTP, reset — no campaign needed)
const msg = await ns.messages.send({
  channel: 'email',
  to: '[e-mail]',
  subject: 'Your order is confirmed',
  body: 'Thanks for your order!',
}, 'order-123-receipt'); // optional idempotency key

Resources

Resource	Methods
ns.account	get, update
ns.contacts	list*, get, create, update, delete
ns.campaigns	list, get, create, update, send, delete
ns.flows	list, get, create, update, delete, spec
ns.templates	list, get, update, sendTest, preview, spec
ns.events	list*, get, create, delete
ns.domains	list*, get, create, verify, delete
ns.brand	get, update, scrape
ns.segments	list, get, create, update, delete, count
ns.lists	list, get, create, update, delete
ns.keywords	list, get, create, update, delete
ns.messages	list*, get, send

* Paginated — returns { data, pagination }.

Pagination

Paginated endpoints return data and pagination metadata:

import { Nitrosend } from '@nitrosend/sdk';

const ns = new Nitrosend('nskey_live_...');
const result = await ns.contacts.list({ page: 1, limit: 25 });

console.log(result.data);       // Contact[]
console.log(result.pagination); // { page, totalPages, totalCount, nextPage, prevPage }

Error Handling

All errors are typed — use instanceof to handle specific cases:

import { Nitrosend, ValidationError, NotFoundError } from '@nitrosend/sdk';

const ns = new Nitrosend('nskey_live_...');

try {
  await ns.contacts.create({ email: 'invalid' });
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.validationErrors); // { email: ['is invalid'] }
  } else if (err instanceof NotFoundError) {
    console.log(err.message);
  }
}

Configuration

const ns = new Nitrosend({
  apiKey: 'nskey_live_...',
  baseUrl: 'https://api.nitrosend.com', // default
  timeout: 30000,                        // ms, default
});

License

MIT