Inicio rápido
Un request y tu correo queda en camino
Destinatarium expone una API REST sobre HTTPS. Antes de enviar, prepara estas tres piezas.
- 01 Verifica tu dominio
El dominio usado en
fromdebe estar activo en tu cuenta. - 02 Crea una API key
La clave necesita el permiso
emails:send. - 03 Envía la solicitud
Usa JSON e incluye al menos contenido
textohtml.
Autenticación
Autoriza cada solicitud
Envía tu API key como Bearer token en el header Authorization.
Authorization: Bearer TU_API_KEY No expongas tu API key en JavaScript del navegador, apps móviles ni repositorios públicos.
Emails
Enviar un correo
Crea un email transaccional y lo deja programado para entrega.
https://api.destinatarium.com/api/v1/emails/ curl --request POST \
--url https://api.destinatarium.com/api/v1/emails/ \
--header 'Authorization: Bearer TU_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: pedido-1842-confirmacion' \
--data '{
"from": "Mi App <notificaciones@tu-dominio.com>",
"to": "usuario@example.com",
"subject": "Tu código de verificación",
"html": "<h1>123456</h1>",
"text": "Tu código es 123456",
"scheduled_at": "2099-01-15T09:30:00+01:00",
"scheduled_timezone": "Europe/Paris"
}'El header opcional Idempotency-Key identifica la operación durante 24 horas. Genera una clave nueva para cada operación y reutilízala, con el mismo JSON, solo en sus reintentos.
Body JSON
Parámetros principales
Los campos desconocidos se rechazan para ayudarte a detectar errores de integración.
| Campo | Tipo | Descripción |
|---|---|---|
fromRequerido | string | Una dirección remitente, con nombre visible opcional. El dominio debe estar verificado y activo. |
toRequerido | string | string[] | Uno o varios destinatarios. Máximo 50 en este campo. |
subjectRequerido | string | Asunto no vacío de hasta 998 caracteres. |
htmlCondicional | string | Contenido HTML. Es obligatorio si no envías text. |
textCondicional | string | Contenido en texto plano. Es obligatorio si no envías html. |
cc, bccOpcional | string | string[] | Destinatarios con copia o copia oculta. Máximo 50 por campo y 100 destinatarios únicos en total entre to, cc y bcc. |
reply_toOpcional | string | string[] | Una única dirección a la que se enviarán las respuestas. |
scheduled_atOpcional | string | Timestamp futuro en formato RFC 3339. Debe incluir Z o un offset UTC numérico. |
scheduled_timezoneOpcional | string | Zona horaria IANA usada para programar el envío, por ejemplo Europe/Paris. Requiere scheduled_at y su offset debe coincidir. |
headersOpcional | object | Hasta 100 headers personalizados no reservados con valores string; máximo 64 KiB en total. |
attachmentsOpcional | object[] | Hasta 20 adjuntos. Cada uno requiere filename y exactamente uno de content (Base64) o path (URL HTTPS pública); admite content_type y content_id. |
Respuesta
Solicitud aceptada
Una solicitud válida devuelve HTTP 200, el identificador único y los datos normalizados de programación.
{
"data": {
"email": {
"id": "0198a1b2-c3d4-7000-8000-000000000001",
"status": "scheduled",
"scheduled_at": "2099-01-15T08:30:00.000Z",
"scheduled_timezone": "Europe/Paris"
}
},
"status": "success",
"statusCode": "200"
}“Aceptado” indica que Destinatarium creó y programó el email. El procesamiento es asíncrono y no garantiza la entrega ni la ubicación en inbox.
Errores
Códigos que debes manejar
Las respuestas de error incluyen un error.errorKey estable para que tu integración pueda decidir qué hacer.
400El JSON o alguno de sus campos no es válido.
401Falta la API key o no es válida.
403La clave no tiene permiso o el dominio remitente no está activo.
409La operación idempotente está en curso o la clave se reutilizó con otro payload.
413El body o el mensaje completo supera el tamaño permitido.
422La forma de un campo reconocido todavía no se puede procesar.
429Se alcanzó el límite de solicitudes o la cuota de emails.
5xxAlgunos errores 500, 502, 503 o 504 pueden ser transitorios; reintenta con backoff y la misma clave de idempotencia.
¿Listo para enviar?