SDK ufficiali

Client TypeScript e Python per l'API di Sending, generati dallo spec OpenAPI.

Sono disponibili due SDK ufficiali, entrambi pubblicati come sending-sdk. I tipi (TypeScript) e i modelli (Pydantic) sono generati dallo spec OpenAPI dell'API v1; il client e' scritto a mano per la migliore DX. Entrambi puntano di default a https://sending.dev/api/v1.

Installazione

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

Requisiti: Node.js >= 18 (usa fetch nativo) · Python >= 3.10.

Inizializzazione

L'unico parametro obbligatorio e' l'apiKey. Il workspace e' sempre derivato dal token.

import { Sending } from "sending-sdk";
 
const sending = new Sending({
  apiKey: process.env.SENDING_API_KEY!, // richiesta
  // baseUrl: "http://localhost:3000/api/v1", // opzionale (dev/self-host)
  // fetch: customFetch,                       // opzionale (test/polyfill)
});

Invio

// Email transazionale
await sending.emails.send({
  from: "you@tuodominio.com",
  to: "cliente@esempio.com",
  subject: "Benvenuto",
  html: "<p>Ciao!</p>",
  idempotencyKey: "welcome-001",
});
 
// Messaggio multi-canale (email, WhatsApp, Telegram)
await sending.messages.send({
  channel: "whatsapp",
  to: "+393331234567",
  text: "Ciao!",
  idempotencyKey: "wa-msg-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: "mario@esempio.com", consent: "opted_in" }],
});
await sending.contacts.addTag(id, "<tag-uuid>");

Gestione errori

Le risposte non-2xx sollevano SendingError con status, code e body.

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);
  }
}

Client asincrono (Python)

Stessa API, su httpx.AsyncClient:

import asyncio
from sending import AsyncSending
 
async def main():
    async with AsyncSending(api_key="sk_...") as client:
        await client.emails.send({
            "from": "you@tuodominio.com",
            "to": "cliente@esempio.com",
            "subject": "Benvenuto",
            "html": "<p>Ciao!</p>",
            "idempotencyKey": "welcome-001",
        })
 
asyncio.run(main())

Risorse disponibili

Entrambi gli SDK espongono la stessa superficie dell'API v1 (in Python i nomi composti sono in snake_case, es. custom_fields, email_rules):

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

Schema completo di ogni endpoint, scope richiesti e "try it" nella API reference interattiva (OpenAPI).

Quickstart

Autenticazione