API

Referencia de la API REST

Todos los endpoints, parámetros, ejemplos de peticiones y respuestas. Autenticación: clave de API (Bearer).

Ejemplo rápido

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome",
    "html": "<h1>Hello!</h1>"
  }'

La clave de API se obtiene en el panel → pestaña Desarrollador. Se recomienda usar claves separadas y con permisos acotados para los entornos de producción y de pruebas.

Autenticación

Cada petición lleva una cabecera Authorization: Bearer YOUR_API_KEY. Las claves se crean en el panel, se muestran una sola vez al crearlas y después se almacenan con hash. Si pierdes una clave, generas una nueva y revocas la antigua: la clave antigua queda desactivada en el momento en que se revoca.

  • Permisos por scopes: 30 scopes (send · campaign · template · webhook · domain · ...). Una clave solo usa las áreas que tú permitas.
  • Lista blanca de IP: puedes restringir las claves de producción a rangos IP/CIDR concretos.
  • Límite de tiempo: puedes asignar un TTL a las claves; expiran automáticamente cuando se agota el plazo.
  • Registro de auditoría: cada uso de clave se registra con marca de tiempo + endpoint + resultado.

Idempotency-Key

Usa la cabecera Idempotency-Key en las peticiones POST: una segunda petición con la misma clave devuelve de nuevo la primera respuesta, sin envíos duplicados. Se recomienda UUIDv4; la clave se conserva durante 24 horas. 

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer sn_live_•••" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-..." \
  ...

Formato de errores

Todas las respuestas de error comparten el mismo envoltorio: código + mensaje + detalle específico de la petición:

{
  "error": {
    "code":    "invalid_recipient",
    "message": "Recipient address does not match the format rule",
    "field":   "to",
    "request_id": "req_01HX8K..."
  }
}

Los códigos de estado HTTP siguen la RFC 7231. Los errores temporales son 5xx + retry-after; los errores 4xx permanentes no se reintentan.

Límite de peticiones

El límite depende de tu plan y se muestra en tiempo real en el panel. Cada respuesta incluye las cabeceras:

  • X-RateLimit-Limit · peticiones permitidas en la ventana
  • X-RateLimit-Remaining · peticiones restantes disponibles
  • X-RateLimit-Reset · cuándo se reinicia la ventana (epoch Unix)

Si recibes un 429, espera el tiempo indicado en la cabecera Retry-After. Los SDK lo hacen automáticamente.

Versionado

La versión es obligatoria en la URL (/v1/). El paso a una nueva versión viene con una ventana de obsolescencia de 12 meses + aviso en el changelog. Los cambios incompatibles nunca se publican en silencio: en cuanto se usa un endpoint obsoleto, se devuelve una cabecera de advertencia.

Lista de endpoints

  • POST /v1/messages Envía un email individual o masivo.
  • GET /v1/messages/{id} Consulta el estado de un mensaje concreto.
  • GET /v1/messages Lista de mensajes, con filtrado y paginación.
  • POST /v1/templates Crea una nueva plantilla (mezcla de Handlebars + Liquid).
  • GET /v1/templates/{id} Detalle de la plantilla.
  • POST /v1/suppressions Añade una dirección a la lista de supresión.
  • GET /v1/suppressions Lista de supresión.
  • POST /v1/webhooks Registra un endpoint de webhook.
  • GET /v1/events Flujo de eventos (sent, delivered, opened, clicked, bounced, complained).
  • GET /v1/domains Tus dominios verificados.

Especificación OpenAPI 3.1: /v1/openapi.json — para importar en el IDE / Postman. Cada endpoint está documentado con todos sus parámetros, un ejemplo de petición y el esquema de respuesta.