API REST de Delark

URL base

https://delark.io

Autenticación

Autentícate con una API key de tipo hms_live_… en la cabecera Authorization. Las keys se crean desde el panel (o vía POST /api/v1/api-keys con tu sesión de administrador), están ligadas a una marca, y se muestran una única vez en el momento de crearlas — guárdala en un gestor de secretos. Si una key se expone, revócala y crea otra.

Authorization: Bearer hms_live_...

Endpoints

Enviar mensajes

POST /api/v1/messages envía un email a hasta 1.000 destinatarios por petición a través de la ruta de envío configurada para tu marca. Las direcciones en tu lista de supresión (bajas, rebotes duros, quejas) se filtran automáticamente y se devuelven en rejected — nunca se les envía.

• substitution_data define variables de personalización: global en la raíz, por destinatario dentro de cada recipient (esta última tiene prioridad). Se usan en el contenido como {{variable}}.
• Envía la cabecera Idempotency-Key con un valor único por operación: un reintento dentro de 60 s con la misma key devuelve 409 en lugar de duplicar el envío.
• Se requiere content.from, content.subject y al menos content.html o content.text.

curl https://delark.io/api/v1/messages \
  -H "Authorization: Bearer hms_live_..." \
  -H "Idempotency-Key: pedido-12345-confirmacion" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "from": { "email": "hola@tudominio.com", "name": "Tu Marca" },
      "subject": "Bienvenido, {{name}}",
      "html": "<h1>Hola {{name}} 👋</h1>",
      "reply_to": "soporte@tudominio.com"
    },
    "recipients": [
      { "address": { "email": "ana@example.com", "name": "Ana" } },
      { "address": "luis@example.com", "substitution_data": { "name": "Luis" } }
    ],
    "substitution_data": { "name": "cliente" }
  }'

Respuesta correcta (200):

{
  "results": {
    "total_accepted_recipients": 2,
    "total_rejected_recipients": 0,
    "id": "<id-del-mensaje>"
  }
}

Con destinatarios rechazados (200 si ninguno se aceptó, 207 si el proveedor falló parte del lote). Motivos: invalid_address, suppressed:

{
  "results": { "total_accepted_recipients": 1, "total_rejected_recipients": 1 },
  "rejected": [
    { "email": "baja@example.com", "reason": "suppressed" }
  ]
}

Errores

El cuerpo de error siempre tiene la forma { "errors": [{ "message": "..." }] }.

Webhooks de eventos

Suscríbete a los eventos de tus envíos creando un endpoint. Eventos disponibles: delivery, open, click, bounce, complaint, unsubscribe — o all. Al crearlo se devuelve una única vez un secreto de firma whsec_….

curl https://delark.io/api/webhooks-out \
  -H "Content-Type: application/json" \
  --cookie "payload-token=<tu sesión>" \
  -d '{ "url": "https://tuapp.com/webhooks/delark", "events": ["delivery", "bounce", "complaint"] }'

Cada entrega llega como POST JSON con las cabeceras X-Delark-Event (tipo de evento) y X-Delark-Signature (HMAC-SHA256 hex del cuerpo con tu secreto). Verifica siempre la firma:

import crypto from 'node:crypto'

function verify(rawBody: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

Responde 2xx en menos de 60 s. Ante error 5xx o timeout reintentamos la entrega hasta 3 veces.