Invio email transazionale.
| POST | /api/v1/emails | Invia un'email transazionale. `idempotencyKey` nel body obbligatoria (min 8 char); `from`/`replyTo` accettano 'Nome <a@b.com>'.(scope: email:send) |
| GET | /api/v1/emails/:id | Stato di un invio (metadati + timeline eventi). |
| POST | /api/v1/messages | Invio transazionale unificato email/WhatsApp/Telegram.(scope: messages:send) |
POST /api/v1/emails
Parametri del body (JSON):
| Campo | Tipo | Obblig. | Note |
|---|---|---|---|
to | string (email) | sì | Destinatario. |
from | string | sì | a@b.com oppure Nome <a@b.com>. Il dominio deve essere verificato. |
subject | string | sì* | Min 1 char. Opzionale se il template fornisce il subject. |
html | string | sì* | HTML del messaggio. In alternativa usa templateId. |
text | string | no | Versione testo semplice (parte multipart). |
replyTo | string | no | Reply-To: a@b.com o Nome <a@b.com>. |
templateId | string | no | Id (uuid) o nome del template del tenant; alternativo a html. |
variables | object | no | Variabili di interpolazione del template. |
idempotencyKey | string | sì | Min 8 caratteri. Previene i doppi invii sui retry. Va nel body, non in un header. |
disableTracking | boolean | no | Disattiva pixel/redirect per questo invio (default false). |
disableUtm | boolean | no | Salta l'auto-tagging UTM dei link (default false). |
*
subject/html sono richiesti se non usi un templateId che li fornisce.Risposte: 202 ({ id, status: "queued" }), 200 ({ status: "duplicate", idempotencyKey }),
422 (validazione), 402 (quota piano), 403 (domain_not_verified), 409 (suppressed).
Esempio
import { Sending } from "sending-sdk";
const sending = new Sending({ apiKey: process.env.SENDING_API_KEY! });
const { id } = await sending.emails.send({
from: "Acme <ciao@tuodominio.dev>",
to: "sara@acme.io",
subject: "Ciao",
html: "<p>Hey</p>",
replyTo: "Supporto <support@tuodominio.dev>",
idempotencyKey: "ciao-sara-001",
});GET /api/v1/emails/:id
Stato di un invio: usa l'id restituito dall'invio.
const status = await sending.emails.get(id);
console.log(status.status, status.events);Ritorna status, metadati (to, from, subject, provider, createdAt) e la timeline
events (sent, delivered, open, click, bounce, complaint).
Schema completo e "try it" nella API reference interattiva (OpenAPI).