Inicio rápido

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 500 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

En sandbox con sk_test_, el dominio From no necesita estar verificado. Con sk_live_, envía al destino de prueba del workspace (…@sandbox.notifique.dev) para interceptar en la bandeja sandbox sin entrega real. La vista previa HTML y el verificador de compatibilidad están en el compositor Nuevo email y en la bandeja.

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 500).

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

{
  "from": "Soporte <noreply@tudominio.com>",
  "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. En from, ponga el nombre antes del correo — como lo ve el destinatario en su bandeja.

Enviar con copias (CC y BCC)

Copia (CC) es como poner colegas en el mismo correo de Outlook: todos ven quién lo recibió. Copia oculta (BCC) funciona igual, pero los demás destinatarios no saben quién está en BCC. Con cc o bcc, todos reciben un único correo. Sin copias, cada dirección en to recibe un envío separado — como mandar cartas individuales a cada persona.

{
  "from": "Soporte <noreply@tudominio.com>",
  "to": ["cliente@example.com"],
  "cc": ["gestor@example.com"],
  "bcc": ["auditoria@example.com"],
  "type": "email",
  "payload": {
    "subject": "Pedido #12345",
    "html": "<p>Adjunto el comprobante.</p>"
  }
}

Responder a otra dirección (replyTo)

Cuando el remitente es noreply@..., la respuesta del cliente normalmente no llega a ningún sitio. Use replyTo para indicar adónde van las respuestas — como dejar un billete “responda en recepción”.

{
  "from": "Soporte <noreply@tudominio.com>",
  "to": ["cliente@example.com"],
  "replyTo": ["ayuda@tudominio.com"],
  "type": "email",
  "payload": {
    "subject": "Duda sobre tu pedido",
    "html": "<p>Responde este correo si necesitas ayuda.</p>"
  }
}

Adjuntos

Hasta 10 archivos, máximo ~30 MB en total. Envíe el archivo en base64 (content) o indique una URL pública (path).

{
  "from": "Soporte <noreply@tudominio.com>",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Comprobante del pedido",
    "html": "<p>Adjunto el comprobante.</p>"
  },
  "attachments": [
    {
      "filename": "comprobante.pdf",
      "content": "JVBERi0xLjQK...",
      "contentType": "application/pdf"
    },
    {
      "filename": "logo.png",
      "path": "https://cdn.tudominio.com/assets/logo.png",
      "contentType": "image/png"
    }
  ]
}

Correo con enlaces

Los enlaces en HTML funcionan como en cualquier cliente de correo. Use <a href="..."> en el cuerpo para botones de acción, restablecimiento de contraseña, seguimiento de pedidos y similares.

{
  "from": "Soporte <noreply@tudominio.com>",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Restablece tu contraseña",
    "html": "<p>Haz clic <a href=\"https://app.tudominio.com/reset?token=abc\">aquí</a> para restablecer tu contraseña. El enlace expira en 1 hora.</p>"
  }
}

Enviar con plantilla

Si ya tienes una plantilla del workspace con email habilitado:

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

cc, bcc, replyTo y attachments también funcionan con plantilla — el mismo patrón del envío con contenido libre. Respuesta esperada: 202

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

La respuesta incluye messageIds.

Dominio de no verificado → 400 con DOMAIN_NOT_VERIFIED.

Opciones en options: priority (high, normal, low), category (transactional o marketing), webhook (URL y secret solo para este lote). metadata va en la raíz del body (no en options). Usa headers para responder hilos (In-Reply-To, References). 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": "Soporte <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 (estado QUEUED o 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: básico, copias, adjuntos, enlaces, programado, plantilla y plantilla con copias.

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

API de correo

E-mail

Domínios

E-mails recebidos

Dominios

En resumen

Antes de empezar

1. Verificar dominio

1A, Vía panel

1B, Vía API

2. Enviar email

Enviar con copias (CC y BCC)

Responder a otra dirección (replyTo)

Adjuntos

Correo con enlaces

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 copias (CC y BCC)

​Responder a otra dirección (replyTo)

​Adjuntos

​Correo con enlaces

​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 copias (CC y BCC)

Responder a otra dirección (replyTo)

Adjuntos

Correo con enlaces

Enviar con plantilla

3. Consultar, programar y cancelar

4. Evitar duplicados

5. Webhooks (opcional)

Todos los tipos de envío

Próximos pasos