Inicio rápido - Notifique

De cero a su primer email en cola en pocos pasos. Lo imprescindible es un dominio verificado en DNS; sin eso, el envío no funcionará.

En resumen

Verifique un dominio en DNS; demuestra que controla el remitente (noreply@yourdomain.com).
Envíe con asunto y cuerpo (texto y/o HTML) a hasta 100 destinatarios por llamada.
Consulte, programe o cancele y obtenga estado vía webhooks.

Contexto: Introducción. Alcances: Alcances de API Key.

Antes de empezar

Clave con email:domains:create, email:domains:list, and email:send (o alcance admin en pruebas)
El dominio from debe estar VERIFIED antes del envío
Auth: Authorization: Bearer sk_live_... or x-api-key
Base URL: https://api.notifique.dev, use sk_test_... in Sandbox al empezar

1. Verificar dominio

Dos caminos, elija lo que encaje con su integración:

1A, Vía panel

Settings → Email → Add domain
Copie los registros DNS (TXT/CNAME) en su proveedor de dominio
Haga clic en Verify hasta que el estado sea VERIFIED

1B, Vía API

Registrar dominio

POST /v1/email/domains
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "domain": "yourdomain.com"
}

Respuesta esperada: 200 con estado PENDING y registros DNS:

{
  "success": true,
  "data": {
    "id": "clxx123...",
    "domain": "yourdomain.com",
    "status": "PENDING",
    "dnsRecords": [
      {
        "type": "TXT",
        "name": "notifique._domainkey.yourdomain.com",
        "value": "p=MIGf..."
      }
    ],
    "createdAt": "2025-02-15T10:00:00.000Z"
  },
  "message": "Add the DNS record(s) above to your domain, then call the verify endpoint or use the Verify button in the dashboard."
}

Guarde el id del dominio para el paso de verificación. Verificar (llame de nuevo tras propagar DNS):

POST /v1/email/domains/:id/verify
Authorization: Bearer sk_live_xxxxx

DNS aún pendiente, 200, no es error HTTP:

{
  "success": true,
  "verified": false,
  "code": "EMAIL_DOMAIN_DNS_PENDING",
  "message": "DNS records are not verified yet. Check your DNS provider and try again in a few minutes.",
  "data": { "id": "clxx...", "domain": "yourdomain.com", "status": "PENDING" }
}

Verificado, 200:

{
  "success": true,
  "verified": true,
  "code": "EMAIL_DOMAIN_VERIFIED",
  "message": "Domain verified successfully.",
  "data": { "id": "clxx...", "domain": "yourdomain.com", "status": "VERIFIED" }
}

Códigos y errores HTTP: Respuestas de error.

2. Enviar email

Con un dominio VERIFIED, envíe a uno o muchos destinatarios. to es siempre un array (hasta 100).

POST /v1/email/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "from": "noreply@tudominio.com",
  "fromName": "Soporte",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Confirmación de pedido",
    "html": "<p>Hola, tu pedido fue confirmado.</p>",
    "text": "Hola, tu pedido fue confirmado."
  }
}

Obligatorio en payload: subject y al menos text o html.

Enviar con plantilla

Si ya tienes una plantilla del workspace con email habilitado:

{
  "from": "noreply@tudominio.com",
  "to": ["cliente@example.com"],
  "type": "template",
  "payload": {
    "templateId": "ID_DE_LA_PLANTILLA",
    "variables": { "name": "María", "orderId": "12345" }
  }
}

Respuesta esperada: 202

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 1,
    "messageIds": ["clemail1..."],
    "emailIds": ["clemail1..."]
  }
}

messageIds es el campo canónico; emailIds es un alias de compatibilidad.

Dominio de no verificado → 400 con DOMAIN_NOT_VERIFIED.

Opciones en options: priority (high, normal, low), webhook (URL y secret solo para este lote), metadata (texto libre). Detalles en la referencia de API. RFC 8058 (one-click unsubscribe): por defecto, si el destinatario es un contacto del workspace, Notifique inyecta List-Unsubscribe. Para email transaccional use "listUnsubscribe": false. Topic inválido → 400 INVALID_LIST_UNSUBSCRIBE_TOPIC. Guía: One-click unsubscribe.

3. Consultar, programar y cancelar

Listar enviados

GET /v1/email/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

Filtros opcionales: fromDate, toDate, status, emailDomainId. Requiere email:read. Ver un envío

GET /v1/email/messages/:id
Authorization: Bearer sk_live_xxxxx

Programar, incluya en el cuerpo del envío:

{
  "from": "noreply@tudominio.com",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Recordatorio",
    "html": "<p>Contenido.</p>"
  },
  "schedule": {
    "sendAt": "2025-12-31T14:00:00.000Z"
  }
}

Cancelar programación (solo con estado SCHEDULED):

POST /v1/email/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx

Alcance: email:cancel. Los créditos programados vuelven al workspace.

4. Evitar duplicados

Idempotency-Key header en POST. Repeticiones dentro de 24 h no crean envíos duplicados. Ver Seguridad y confiabilidad.

5. Webhooks (opcional)

Configure email.sent, email.delivered, email.opened, email.clicked, email.failed, email.complained, and email.cancelled para rastrear sin polling. Guía: Eventos de Webhook.

Todos los tipos de envío

En la referencia de la API (pestaña Correo), abra Enviar correo y elija un ejemplo en el playground: HTML+texto, Solo texto, Plantilla, Programado, List-Unsubscribe.

Próximos pasos

Introducción: cuándo usar y ciclo de estados
Alcances: permisos de la clave
Eventos de Webhook: estado en tiempo real
Respuestas de error: códigos HTTP y code

​En resumen

​Antes de empezar

​1. Verificar dominio

​1A, Vía panel

​1B, Vía API

​2. Enviar email

​Enviar con plantilla

​3. Consultar, programar y cancelar

​4. Evitar duplicados

​5. Webhooks (opcional)

​Todos los tipos de envío

​Próximos pasos

En resumen

Antes de empezar

1. Verificar dominio

1A, Vía panel

1B, Vía API

2. Enviar email

Enviar con plantilla

3. Consultar, programar y cancelar

4. Evitar duplicados

5. Webhooks (opcional)

Todos los tipos de envío

Próximos pasos