TypeScript SDK

The README covers installation, configuration, pagination, errors and webhooks. This page covers the rest of the SDK. Every example assumes a client:

import { Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({ apiKey: process.env.NUNTLY_API_KEY });

Client cloning

withOptions(partial) returns a new client built from the original one’s options. The original client is untouched, and the new one reuses its hooks and retry settings. defaultHeaders is merged with the original headers; any other option you pass replaces the original value. defaultHeaders is sent on every request, but Nuntly does not read or route on it. Use it for your own tracing and audit chain.

One API key per customer

When each customer of your SaaS has their own Nuntly API key, a new Nuntly per request would need the hooks and the retry settings passed again. Clone the root client instead:

const tenant = nuntly.withOptions({ apiKey: tenantApiKey });
await tenant.emails.send({ from, to, subject, html });

One trace ID across services

When a request in your app calls several services, forward your trace ID on every Nuntly call so your APM links the email send to the request that triggered it:

const traced = nuntly.withOptions({
  defaultHeaders: { 'X-Trace-Id': traceId },
});
await traced.emails.send({ from, to, subject, html });

Who sent this email

To record which user of your app sent an email, stamp a header on every request. Your gateway, proxy or log pipeline records it; Nuntly ignores it.

const audited = nuntly.withOptions({
  defaultHeaders: { 'X-Initiated-By': `user:${userId}` },
});

Lifecycle hooks

Hooks run around each HTTP request, for logging or telemetry. A hook reads the request and cannot change it. Every hook receives a single ctx argument:

import { APIError, Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
  hooks: {
    onRequest: (ctx) => {
      console.log(`-> ${ctx.method} ${ctx.url}`);
    },
    onResponse: (ctx) => {
      console.log(`<- ${ctx.response.status} ${ctx.request.path}`);
    },
    onSuccess: (ctx) => {
      metrics.increment('api.success');
    },
    onRetry: (ctx) => {
      console.warn(`Retry #${ctx.attempt} ${ctx.request.path}`);
    },
    onError: (ctx) => {
      if (ctx.error instanceof APIError) {
        sentry.captureException(ctx.error, { tags: { code: ctx.error.code } });
      } else {
        sentry.captureException(ctx.error);
      }
    },
  },
});

Hook	Signature	When
`onRequest`	`(ctx: RequestContext) => void \| Promise<void>`	Before each HTTP request
`onResponse`	`(ctx: ResponseContext) => void \| Promise<void>`	After the final HTTP response of a call, once retries are done (2xx, 4xx, 5xx); not called on network errors
`onSuccess`	`(ctx: SuccessContext) => void \| Promise<void>`	After each 2xx response, with the parsed payload
`onRetry`	`(ctx: RetryContext) => void \| Promise<void>`	Before each retry attempt
`onError`	`(ctx: ErrorContext) => void \| Promise<void>`	On 4xx and 5xx (`APIError`), a network error or timeout (`APIConnectionError`), or a call the SDK refuses before sending it (`NuntlyError`)

For one call, the hooks run in this order: onRequest, then onRetry and onRequest again for each retry, then onResponse, then onSuccess or onError. The client awaits every hook that returns a Promise. An error thrown by onError is logged and the call still rejects with its own error; an error thrown by any other hook rejects the call with that error. The Authorization header in ctx.headers reads Bearer [redacted]: no hook argument, log line or error carries the API key, and neither does console.log(nuntly).

Retries

By default the SDK retries a request up to 2 times on a 408, a 429, a 500, a 502, a 503, a 504, a timeout or a network error. The first retry waits 375 to 500 ms and each later one twice as long, up to 8 s. The initial interval is 500 ms, the exponent is 2, and a jitter shortens each delay to 75% to 100% of it.

A 409 is retried only when the API sends x-should-retry: true. The API does so when the first attempt of a send with an idempotency key is still in progress, and the retry gets the stored response of that attempt. Any other conflict, such as a contact that already exists, does not resolve on its own.
A POST or a PATCH is retried only on a 429, so a retry cannot apply it twice. The exception is the eight sending methods listed in the README’s per-request options: the API deduplicates them by Idempotency-Key, and they send your key or one they generate, so they are also retried on a 408, a 5xx, a timeout or a network error. An Idempotency-Key header you add to another method does not change its retries.
The SDK never retries a request you abort through signal, including with AbortSignal.timeout(...), or an error thrown by a hook.
A failure while reading the response body, such as a connection reset mid-body, is not retried.
A server-sent x-should-retry: true or false overrides these rules. A Retry-After header (seconds, decimals allowed, or an HTTP date) on any response replaces the backoff delay. Above 60 s the SDK does not wait, even with x-should-retry: true: it throws the error for that response at once, with RateLimitError.retryAfter set on a 429.
With retry: 'none', a per-request maxRetries does not turn retries back on.

// Disable retries
const noRetries = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
  retry: 'none',
});

// Custom backoff
const customBackoff = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
  maxRetries: 5,
  retry: {
    strategy: 'backoff',
    backoff: {
      initialInterval: 200, // ms
      maxInterval: 30000, // ms
      exponent: 1.5,
    },
  },
});

// Per-request override
await customBackoff.emails.send(payload, { maxRetries: 0 });

Safe mode for one call

createSafeNuntly makes every call return { data, error }. To get that shape for some calls only, wrap an existing client with safe():

import { Nuntly, safe } from '@nuntly/sdk';

const nuntly = new Nuntly({ apiKey: process.env.NUNTLY_API_KEY });
const { data, error } = await safe(nuntly).emails.retrieve('em_01ka8k8s80gvx9604cn9am5st4');

Response headers without the body

.asResponse() resolves to the raw Response as soon as the headers arrive, without reading the body. Use it for streaming or to read headers only. It does not throw on a 4xx or 5xx, so check response.status:

const response = await nuntly.emails.retrieve('em_01ka8k8s80gvx9604cn9am5st4').asResponse();
console.log(response.status, response.headers.get('x-request-id'));

Called once the SDK has read the body, such as after the call settled, .asResponse() and .withResponse() resolve to a copy of the response built from that body, so the body stays readable. The copy has no content-encoding or content-length header, since its body is the decoded text, and the call keeps that text in memory for as long as you hold its promise.

Abort a request

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await nuntly.emails.list(undefined, { signal: controller.signal });

The call rejects with an APIConnectionError and is not retried. An abort through AbortSignal.timeout(...) rejects with its subclass APIConnectionTimeoutError.

Debug logging

debug: true logs each request and response:

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
  debug: true,
});
// -> POST https://api.nuntly.com/emails
// <- 202 POST /emails [req_abc123]

Custom logger

logger accepts any logger compatible with console, such as pino or winston:

import { Nuntly } from '@nuntly/sdk';
import pino from 'pino';

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
  logger: pino({ level: 'debug' }),
});

Custom fetch

fetch replaces globalThis.fetch with any compatible function, for instrumentation, custom retry or another HTTP client. The SDK calls it with a Request as its first argument:

import { Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
  fetch: async (input, init) => {
    const startedAt = Date.now();
    const response = await globalThis.fetch(input, init);
    console.log(`${response.status} ${response.url} (${Date.now() - startedAt}ms)`);
    return response;
  },
});

HTTP and HTTPS proxies

On Node.js, pass an undici ProxyAgent as the dispatcher of the global fetch to send requests through a corporate or debugging proxy:

import { Nuntly } from '@nuntly/sdk';
import { ProxyAgent } from 'undici';

const proxy = new ProxyAgent({
  uri: 'http://corporate-proxy:8080',
  token: `Basic ${process.env.PROXY_TOKEN}`, // only when the proxy requires authentication
});

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
  // `dispatcher` is a Node.js extension that the standard RequestInit type does not declare.
  fetch: (input, init) => fetch(input, { ...init, dispatcher: proxy } as RequestInit),
});

API Reference

Agents

API Keys

Broadcasts

Templates

Segments

Topics

Contacts

Domains

Emails

Inboxes

Threads

Messages

Namespaces

Organizations

Contact Properties

Segment memberships

Topic memberships

Webhooks

Webhooks Events

Webhooks Hook

TypeScript SDK

Client cloning

One API key per customer

One trace ID across services

Who sent this email

Lifecycle hooks

Retries

Safe mode for one call

Response headers without the body

Abort a request

Debug logging

Custom logger

Custom fetch

HTTP and HTTPS proxies

​Client cloning

​One API key per customer

​One trace ID across services

​Who sent this email

​Lifecycle hooks

​Retries

​Safe mode for one call

​Response headers without the body

​Abort a request

​Debug logging

​Custom logger

​Custom fetch

​HTTP and HTTPS proxies

Client cloning

One API key per customer

One trace ID across services

Who sent this email

Lifecycle hooks

Retries

Safe mode for one call

Response headers without the body

Abort a request

Debug logging

Custom logger

Custom fetch

HTTP and HTTPS proxies