The official Node.js SDK for the Send & Retain email API — send email, sync contacts, emit events that drive automations, and verify webhooks. Every request and response type is generated from the OpenAPI spec.
npm install @sendandretain/sdkNode 20 or later. ESM and CommonJS. Server-side only — never ship an API key to a browser.
Create a key in the dashboard under Settings → API keys and set it as
SENDANDRETAIN_API_KEY.
import { SendAndRetain } from "@sendandretain/sdk";
const sendandretain = new SendAndRetain(); // reads SENDANDRETAIN_API_KEY
const { data, error } = await sendandretain.emails.send({
to: "jane@acme.com",
template: "welcome",
props: { firstName: "Jane" },
});
if (error) {
console.error(error.code, error.message, error.request_id);
} else {
console.log(data.id); // queued — delivery is reported by webhook
}Sending needs a key with the write scope and the send grant (the dashboard's
Send + manage). A send is accepted with 202 and delivered in the background; follow it with
emails.get(id) or, better, a webhook.
Every method resolves to { data, error, headers } and never throws for an API or network failure:
const { data, error, headers } = await sendandretain.templates.get("welcome");
if (error) {
switch (error.code) {
case "not_found": // 404
break;
case "rate_limited": // already retried for you; this is after the last attempt
break;
case "network_error": // no response arrived — status is null
break;
}
console.error(`support reference: ${error.request_id}`);
}error is { code, message, status, request_id, ...extra }. Branch on code — the full list is in
the error reference. A 403 also carries
required_scope or required_grant. The constructor is the only thing that throws: on a missing or
malformed key.
Pass an idempotencyKey on any create to make it safe to retry:
await sendandretain.emails.send(
{ to: "jane@acme.com", template: "welcome" },
{ idempotencyKey: "welcome/user_42" }
);The same key and body replays the first result (Idempotency-Replay: true) instead of sending
again; a different body with the same key is a conflict error. Keys live 24 hours. When you pass
none, the SDK generates one per call, so its own retries can never send twice.
Requests that fail with 408, 429 or 5xx, or never get a response, are retried twice with
exponential backoff and jitter, honouring Retry-After. Only safe requests are retried: reads,
updates, deletes, and creates carrying an idempotency key — which is all of them, by default. A
429 daily_cap / monthly_cap is a sending quota, not a throttle, and is returned at once.
const sendandretain = new SendAndRetain({ maxRetries: 4, timeout: 10_000 });
// Per call: cancel, cap the whole call, or add headers.
await sendandretain.contacts.list({ limit: 100 }, { signal, timeout: 5_000 });Lists answer { object: "list", data, has_more, next_cursor }. iterate() walks every page:
for await (const email of sendandretain.emails.list.iterate({ status: "bounced" })) {
console.log(email.to);
}
// Or page by hand.
const page = await sendandretain.contacts.list({ limit: 100 });
const next = page.data?.next_cursor
? await sendandretain.contacts.list({ limit: 100, cursor: page.data.next_cursor })
: null;Subscribe an endpoint, store the secret it returns (shown once), and verify every delivery against the raw body:
const { data } = await sendandretain.webhooks.create({
url: "https://acme.com/api/webhooks/sendandretain",
event_types: ["email.delivered", "email.bounced", "email.complained"],
});
// data.secret → SENDANDRETAIN_WEBHOOK_SECRET
// In your handler:
import { verifyWebhook, WebhookVerificationError } from "@sendandretain/sdk";
const event = verifyWebhook({
payload: await req.text(), // the raw body, not req.json()
headers: req.headers,
secret: process.env.SENDANDRETAIN_WEBHOOK_SECRET!,
});
if (event.type === "email.bounced") {
// event is narrowed to the bounced payload
}verifyWebhook throws WebhookVerificationError on a bad signature or a stale timestamp — answer
400. Deliveries are Standard Webhooks, at-least-once and
unordered: dedupe on event.id, order on event.occurred_at. Missed one? webhooks.deliveries.replay(id, deliveryId).
See examples/ for a plain Node server and a Next.js route handler.
| Resource | Methods |
|---|---|
emails |
send, get, list (.iterate), reschedule, cancel, batch.send |
contacts |
upsert, get, list (.iterate), delete, import, events (.iterate) |
events |
emit |
suppressions |
list (.iterate), add, remove, import |
templates |
create, list, get, update, updateMeta, archive, listVersions, publish, unpublish, render, test, addTranslation |
automations |
create, list, get, update, archive, setStatus, duplicate, backfill, preflight, runs (.iterate), metrics, setAbTest, promoteAbWinner, steps.{add,update,remove,move,syncProps} |
segments |
create, list, update, delete, refreshCount |
domains |
create, list, verify, delete |
senders |
create, list, update, delete |
webhooks |
create, list, get, update, delete, rotateSecret, test, deliveries.list (.iterate), deliveries.replay, verify |
metrics |
get, trends, queueHealth |
settings |
get, update, getBrand, updateBrand |
setup |
onboarding, connection, registerProviderWebhook |
Every operation in the API has a method — a test fails if one is missing. sendandretain.http is
the underlying openapi-fetch client if you need the raw
response.
Request bodies, queries and responses are all typed from the spec. The generated types are exported for your own use:
import type { components, paths, WebhookEvent } from "@sendandretain/sdk";
type Contact = components["schemas"]["ContactResult"];| Option | Env var | Default |
|---|---|---|
apiKey |
SENDANDRETAIN_API_KEY |
— (required) |
baseUrl |
SENDANDRETAIN_BASE_URL |
https://sendandretain.com |
maxRetries |
2 |
|
timeout |
60000 ms per attempt |
|
fetch |
global fetch |
npm ci
npm run gen # regenerate src/schema.d.ts from openapi.json
npm run verify # fail if they drifted
npm test
npm run buildopenapi.json, src/runtime.ts, LICENSE and .github/ are synced from the Send & Retain source
tree and overwritten on every sync — change them there, not here. Everything else in this repo is
hand-written.
MIT