@destinatarium/node

SDK oficial de cliente, sin dependencias de ejecucion, exclusivamente para enviar emails con una API key de Destinatarium desde Node.js 18 o posterior. El paquete usa ESM e incluye declaraciones TypeScript.

Alcance

La unica operacion del SDK es client.emails.send(payload, options). Permite enviar emails con texto o HTML, CC/BCC, direccion de respuesta, adjuntos y programacion. No permite listar o consultar emails, destinatarios o adjuntos, ni acceder a funciones administrativas de Destinatarium.

La API key esta vinculada al cliente y su equipo y solo admite el permiso emails:send. El backend comprueba los permisos del equipo, el dominio del remitente y los limites del cliente. Las consultas se realizan desde la aplicacion web con una sesion autenticada.

Guarde la API key en una variable de entorno de su servidor; no la incluya en codigo del navegador ni repositorios publicos.

Instalacion

npm install @destinatarium/node

import { Destinatarium } from "@destinatarium/node";

const client = new Destinatarium(process.env.DESTINATARIUM_API_KEY);

La URL base predeterminada es https://api.destinatarium.com/api/v1. La autenticacion se envia exclusivamente como Authorization: Bearer <apiKey>.

Enviar un email

const result = await client.emails.send({
  from: "Equipo <[email protected]>",
  to: ["[email protected]"],
  cc: "[email protected]",
  reply_to: "[email protected]",
  subject: "Bienvenido",
  text: "Gracias por registrarte.",
  html: "<p>Gracias por registrarte.</p>",
  headers: { "X-Campaign": "welcome" },
});

console.log(result.email);
console.log(result.idempotency, result.rateLimit, result.quota);

Reemplace el remitente por una direccion de su dominio verificado. Una respuesta exitosa indica que el email fue aceptado en la cola, no que ya fue entregado. Consulte su estado desde la aplicacion web de Destinatarium. rateLimit y quota son metadatos de la respuesta del envio, no funciones de administracion.

El SDK genera una clave de idempotencia UUID por envio. Tambien se puede proporcionar una clave estable o desactivarla de forma explicita:

await client.emails.send(payload, { idempotencyKey: "order-123" });
await client.emails.send(payload, { idempotencyKey: null });

Al desactivar la idempotencia, el SDK no reintenta el POST, porque no puede garantizar que una repeticion sea segura. En los reintentos idempotentes conserva exactamente la misma clave y el mismo cuerpo serializado.

Programacion

await client.emails.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Recordatorio",
  text: "Tu cita es manana.",
  scheduled_at: "2026-10-15T09:00:00+02:00",
  scheduled_timezone: "Europe/Madrid",
});

scheduled_at debe usar RFC 3339 e incluir Z o un offset UTC numerico. Si se envia scheduled_timezone, ese offset debe coincidir con la zona IANA para la fecha indicada.

Adjuntos

Una ruta local no se puede enviar directamente en path. Para leer un archivo local y crear el contenido Base64 canonico, use attachmentFromFile:

import { attachmentFromFile } from "@destinatarium/node";

const invoice = await attachmentFromFile("./factura.pdf");

await client.emails.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Factura",
  attachments: [invoice],
});

El segundo argumento permite cambiar el nombre enviado: attachmentFromFile("./tmp/a.pdf", "factura.pdf").

Para un adjunto remoto, path debe ser una URL HTTPS:

attachments: [{ filename: "catalogo.pdf", path: "https://cdn.example.com/catalogo.pdf" }]

Errores y reintentos

import { DestinatariumApiError, DestinatariumError } from "@destinatarium/node";

try {
  await client.emails.send(payload);
} catch (error) {
  if (error instanceof DestinatariumApiError) {
    console.error(error.errorKey, error.description, error.details, error.httpStatus);
  } else if (error instanceof DestinatariumError) {
    console.error(error.code, error.message);
  }
}

La configuracion predeterminada usa un timeout de 30 segundos y hasta 2 reintentos. Se reintentan fallos de red y respuestas HTTP 408, 425, 429 y 5xx; no se reintentan errores 4xx ordinarios. Retry-After se respeta tanto en segundos como en formato de fecha, con una espera maxima acotada.

const client = new Destinatarium(apiKey, {
  baseUrl: "https://api.destinatarium.com/api/v1",
  timeout: 15_000,
  maxRetries: 3,
});

const controller = new AbortController();
await client.emails.send(payload, { signal: controller.signal });

Los errores del SDK no incluyen la clave de API. Las respuestas no JSON o con envoltorios invalidos se convierten en DestinatariumError sin exponer el cuerpo recibido.

Licencia

MIT