sending-sdk

SDK TypeScript ufficiale per l'API di Sending.dev (email + WhatsApp + Telegram).

I tipi sono generati dallo spec OpenAPI, il client e' scritto a mano per la migliore DX.

Installazione

npm install sending-sdk
# pnpm add sending-sdk · yarn add sending-sdk

Richiede Node.js >= 18 (usa fetch nativo).

Uso

import { Sending } from "sending-sdk";

const sending = new Sending({ apiKey: process.env.SENDING_API_KEY! });

// Email transazionale
await sending.emails.send({
  to: "[email protected]",
  from: "[email protected]",
  subject: "Benvenuto",
  html: "<p>Ciao!</p>",
  idempotencyKey: "welcome-001",
});

// Messaggio multi-canale
await sending.messages.send({
  channel: "whatsapp",
  to: "+393331234567",
  text: "Ciao!",
  idempotencyKey: "wa-001",
});

Contatti e paginazione

const page = await sending.contacts.list({ q: "mario", page: 1, pageSize: 50 });
console.log(page.total, page.data);

const { id } = await sending.contacts.create({
  attributes: { firstName: "Mario" },
  identities: [{ channel: "email", address: "[email protected]", consent: "opted_in" }],
});
await sending.contacts.addTag(id, "<tag-uuid>");

Gestione errori

import { SendingError } from "sending-sdk";

try {
  await sending.emails.send({ /* ... */ } as any);
} catch (err) {
  if (err instanceof SendingError) {
    console.error(err.status, err.code, err.body);
  }
}

Configurazione

new Sending({
  apiKey: "sk_...",            // richiesta
  baseUrl: "https://...",      // opzionale, default produzione
  fetch: customFetch,          // opzionale (test/polyfill)
});

Risorse disponibili

emails · messages · events · campaigns · contacts · lists · tags · customFields · segments · domains · inboxes · emailRules · automations · webhooks · utm · integrations · usage.

Autenticazione e scope

La key (sk_...) determina i permessi (scope). Vedi la reference interattiva per gli scope per endpoint.

Sviluppo

pnpm gen     # rigenera src/generated/types.ts da openapi.json
pnpm build   # bundle ESM + CJS + d.ts (tsup)
pnpm test    # vitest

Lo openapi.json viene copiato qui da pnpm openapi:generate (package @sending/openapi).