{ "openapi": "3.0.3", "info": { "title": "Notificar a la API: correo electrónico", "description": "Envíe correos, gestione dominios y consulte el estado. Autentíquese con `Authorization: Bearer sk_live_...` o `x-api-key`.", "version": "1.0.0" }, "servers": [ { "url": "https://api.notifique.dev", "description": "Producción" } ], "security": [ { "ntfEmailBearerAuth": [] }, { "ntfEmailApiKeyHeader": [] } ], "tags": [ { "name": "E-mail", "description": "Envío de correo electrónico y consulta." }, { "name": "Dominios", "description": "Registro y verificación de dominios para envío de correos electrónicos." } ], "paths": { "/v1/email/messages": { "get": { "tags": [ "E-mail" ], "summary": "Listar mensajes correo", "description": "Muestra el historial de correo enviados. Puedes filtrar por fecha y estado.", "operationId": "ntfEmail_getV1EmailMessages", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "string" }, "description": "Página (por defecto 1)." }, { "name": "limit", "in": "query", "schema": { "type": "string" }, "description": "Elementos por página (predeterminado 20, máximo 100)." }, { "name": "fromDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inicio del rango (filtrar por creado en, inclusive)." }, { "name": "toDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Fin del rango (filtrar por creado en, inclusive)." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Uno o más estados separados por comas: EN COLA, PROGRAMADO, PROCESANDO, ENVIADO, ENTREGADO, ABIERTO, HACIENDO CLIC, FALLADO, CANCELADO, QUEJADO. Los valores no válidos se ignoran." }, { "name": "emailDomainId", "in": "query", "schema": { "type": "string" }, "description": "Filtra por el ID (cuid) del dominio de envío; debe pertenecer al espacio de trabajo. Alternativa: `email_domain_id`." }, { "name": "email_domain_id", "in": "query", "schema": { "type": "string" }, "description": "Alias de `emailDomainId`." } ], "responses": { "200": { "description": "Lista de correo electrónico y paginación.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "description": "Cada elemento tiene los mismos campos que GET /v1/email/messages/{id} en `data`. No incluye cuerpo (`html`/`text`), `emailDomainId`, `externalId` o `providerUsed`.", "items": { "$ref": "#/components/schemas/NtfEmail_EmailListItem" } }, "pagination": { "type": "object", "required": [ "total", "page", "limit", "totalPages" ], "properties": { "total": { "type": "integer", "description": "Número total de correos electrónicos que coinciden con los filtros." }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "example": { "success": true, "data": [ { "id": "clxx123...", "to": "cliente@example.com", "from": "noreply@seudominio.com", "fromName": "Suporte", "subject": "Confirmação", "status": "SENT", "scheduledFor": null, "sentAt": "2025-02-16T12:00:00.000Z", "deliveredAt": null, "failedAt": null, "errorMessage": null, "createdAt": "2025-02-16T11:59:58.000Z" } ], "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 } } } } }, "400": { "description": "`emailDomainId` informado no existe en este espacio de trabajo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "401": { "description": "Clave API faltante o no válida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Falta correo electrónico: ámbito de lectura, o `emailDomainId` no permitido para la clave API (restricción de **domainIds**), o listado con clave restringida a dominios sin acceso al filtro solicitado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } }, "post": { "tags": [ "E-mail" ], "summary": "Enviar correo", "description": "Envía correo a uno o más destinatarios. Escribe el texto o usa una plantilla.", "operationId": "ntfEmail_postV1EmailSend", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Clave única para evitar envíos duplicados. Alternativa: x-idempotencia-clave.", "schema": { "type": "string" } }, { "name": "x-idempotency-key", "in": "header", "required": false, "description": "Clave única para idempotencia (alternativa a Idempotency-Key).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_SendEmailRequest" }, "examples": { "email": { "summary": "Correo", "value": { "from": "noreply@tudominio.com", "fromName": "Soporte", "to": [ "cliente@example.com" ], "type": "email", "payload": { "subject": "Confirmación de pedido", "html": "

Hola, tu pedido fue confirmado.

" }, "schedule": { "sendAt": "2025-12-31T14:00:00.000Z" }, "options": { "priority": "high", "webhook": { "url": "https://api.tudominio.com/hooks/email-events", "secret": "secreto_hmac_opcional" } }, "metadata": { "campaign": "welcome" } } }, "template": { "summary": "Plantilla del workspace", "value": { "from": "noreply@tudominio.com", "to": [ "cliente@example.com" ], "type": "template", "payload": { "templateId": "tpl_abc123", "variables": { "name": "María" } } } } } } } }, "responses": { "202": { "description": "Correo electrónico(s) aceptado(s). En cola para envío inmediato o programado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_SendEmailResponse" }, "examples": { "queued": { "summary": "Envío inmediato", "value": { "success": true, "data": { "messageIds": [ "clxx123...", "clxx456..." ], "emailIds": [ "clxx123...", "clxx456..." ], "status": "QUEUED", "count": 2 } } }, "scheduled": { "summary": "Programado", "value": { "success": true, "data": { "messageIds": [ "clxx123..." ], "emailIds": [ "clxx123..." ], "status": "SCHEDULED", "count": 1, "scheduledAt": "2025-12-31T14:00:00.000Z" } } } } } } }, "400": { "description": "Validación: no válido para/desde/asunto, cuerpo faltante, no verificado desde el dominio (`DOMAIN_NOT_VERIFIED`) o `listUnsubscribeTopicId` (`INVALID_LIST_UNSUBSCRIBE_TOPIC`) no válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "examples": { "invalidListUnsubscribeTopic": { "summary": "Lista no válida: tema para cancelar suscripción", "value": { "success": false, "error": "Bad Request", "message": "listUnsubscribeTopicId does not match a communication topic in this workspace.", "code": "INVALID_LIST_UNSUBSCRIBE_TOPIC", "details": [ { "field": "listUnsubscribeTopicId", "message": "Topic not found in workspace" } ] } }, "validation": { "summary": "Campo requerido", "value": { "success": false, "error": "Bad Request", "message": "from and subject are required", "details": [ { "field": "from", "message": "from is required" } ], "code": "BAD_REQUEST" } }, "domain": { "summary": "Dominio no verificado", "value": { "success": false, "error": "Bad Request", "message": "Domain example.com is not verified for this workspace. Add and verify the domain first.", "code": "DOMAIN_NOT_VERIFIED" } } } } } }, "401": { "description": "Clave API faltante o no válida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "402": { "description": "Prueba/plan caducado (WORKSPACE_BLOCKED), créditos/saldo insuficientes (INSUFFICIENT_CREDITS / INSUFFICIENT_CREDITS_OR_BALANCE) o límite de clave API (API_KEY_SPEND_LIMIT_EXCEEDED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Payment Required", "message": "Insufficient credits.", "code": "INSUFFICIENT_CREDITS" } } } }, "403": { "description": "Correo electrónico de alcance: enviar créditos/plan faltantes o insuficientes (PLAN_LIMIT_CREDITS) o programación no permitida (PLAN_LIMIT_SCHEDULING).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "429": { "description": "Rate limit excedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "503": { "description": "El servicio de correo electrónico no está configurado o no se puso en cola.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Service Unavailable", "message": "Email service is not configured.", "code": "SERVICE_UNAVAILABLE" } } } } } } }, "/v1/email/messages/{id}": { "get": { "tags": [ "E-mail" ], "summary": "Consultar envío correo", "description": "Consulta si fue enviado, entregado o falló, y ve los detalles.", "operationId": "ntfEmail_getV1EmailById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de correo electrónico (cuid) devuelto en POST /v1/email/messages.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Datos de correo electrónico.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_EmailStatusResponse" }, "example": { "success": true, "data": { "id": "clxx123...", "to": "cliente@example.com", "from": "noreply@seudominio.com", "fromName": "Suporte", "subject": "Confirmação", "status": "SENT", "scheduledFor": null, "sentAt": "2025-02-16T12:00:00.000Z", "deliveredAt": null, "failedAt": null, "errorMessage": null, "createdAt": "2025-02-16T11:59:58.000Z" } } } } }, "401": { "description": "Clave API faltante o no válida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Correo electrónico faltante: alcance de lectura.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "404": { "description": "Correo electrónico no encontrado o no pertenece al espacio de trabajo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Not Found", "message": "Email not found", "code": "NOT_FOUND" } } } } } } }, "/v1/email/messages/{id}/cancel": { "post": { "tags": [ "E-mail" ], "summary": "Cancelar correo programado", "description": "Cancela algo que aún no salió — en cola o programado.", "operationId": "ntfEmail_postV1EmailCancel", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID (atención) del correo electrónico programado.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Correo electrónico cancelado exitosamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_CancelEmailResponse" }, "example": { "success": true, "data": { "emailId": "clxx123...", "status": "CANCELLED" } } } } }, "400": { "description": "El correo electrónico no está EN COLA ni PROGRAMADO (solo estos estados se pueden cancelar).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Bad Request", "message": "Only queued or scheduled emails can be cancelled.", "data": { "status": "QUEUED" }, "code": "BAD_REQUEST" } } } }, "401": { "description": "Clave API faltante o no válida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Correo electrónico de alcance: falta cancelar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "404": { "description": "Correo electrónico no encontrado o no pertenece al espacio de trabajo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } } }, "/v1/email/domains": { "get": { "tags": [ "Domínios", "E-mail" ], "summary": "Listar dominios de correo", "description": "Lista los dominios registrados para envío.", "operationId": "ntfEmail_getV1EmailDomains", "responses": { "200": { "description": "Lista de dominios.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ListEmailDomainsResponse" }, "example": { "success": true, "data": [ { "id": "clxx123...", "domain": "seudominio.com", "status": "VERIFIED", "dnsRecords": [ { "type": "TXT", "name": "notifique._domainkey.seudominio.com", "value": "p=MIGf..." } ], "verifiedAt": "2025-02-16T12:00:00.000Z", "createdAt": "2025-02-15T10:00:00.000Z" } ] } } } }, "401": { "description": "Clave API faltante o no válida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Falta correo electrónico:dominios:alcance de la lista.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } }, "post": { "tags": [ "Domínios", "E-mail" ], "summary": "Registrar dominio de correo", "description": "Registra un dominio para enviar correos (ej.: @suempresa.com). La respuesta indica qué configurar en DNS.", "operationId": "ntfEmail_postV1EmailDomains", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_CreateEmailDomainRequest" }, "examples": { "rootDomain": { "summary": "Dominio raíz", "description": "Ej.: correos de @suempresa.com", "value": { "domain": "suempresa.com" } }, "subdomain": { "summary": "Subdominio", "description": "Ej.: correos de @mail.suempresa.com", "value": { "domain": "mail.suempresa.com" } } } } } }, "responses": { "200": { "description": "Dominio registrado. Configure los registros DNS devueltos y luego llame al punto final de verificación.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_CreateEmailDomainResponse" }, "example": { "success": true, "data": { "id": "clxx123...", "domain": "seudominio.com", "status": "PENDING", "dnsRecords": [ { "type": "TXT", "name": "notifique._domainkey.seudominio.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." } } } }, "400": { "description": "Dominio no válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Bad Request", "message": "Invalid domain", "details": [ { "field": "domain", "message": "domain must be a valid domain name" } ], "code": "BAD_REQUEST" } } } }, "401": { "description": "Clave API faltante o no válida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "402": { "description": "Prueba/plano caducado (WORKSPACE_BLOCKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Falta el alcance o el límite de dominio del plan (PLAN_LIMIT_EMAIL_DOMAINS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Plan limit reached", "message": "Your plan allows up to N domain(s). Upgrade to add more.", "code": "PLAN_LIMIT_EMAIL_DOMAINS" } } } }, "409": { "description": "Dominio ya registrado en este espacio de trabajo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Conflict", "message": "This domain is already registered for this workspace.", "data": { "id": "clxx...", "domain": "seudominio.com", "status": "PENDING" }, "code": "CONFLICT" } } } }, "502": { "description": "No se pudo iniciar la verificación del dominio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "503": { "description": "Servicio de correo electrónico no configurado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } } }, "/v1/email/domains/{id}": { "get": { "tags": [ "Domínios", "E-mail" ], "summary": "Consultar dominio de correo", "description": "Consulta estado y registros DNS de un dominio.", "operationId": "ntfEmail_getV1EmailDomainById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de dominio (cuidado).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Datos de dominio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_EmailDomainResponse" }, "example": { "success": true, "data": { "id": "clxx123...", "domain": "seudominio.com", "status": "VERIFIED", "dnsRecords": [], "verifiedAt": "2025-02-16T12:00:00.000Z", "createdAt": "2025-02-15T10:00:00.000Z", "updatedAt": "2025-02-16T12:00:00.000Z" } } } } }, "401": { "description": "Clave API faltante o no válida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Falta correo electrónico:dominios:alcance de la lista.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "404": { "description": "Dominio no encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Not Found", "message": "Email domain not found or not in this workspace", "code": "EMAIL_DOMAIN_NOT_FOUND" } } } } } } }, "/v1/email/domains/{id}/verify": { "post": { "tags": [ "Domínios", "E-mail" ], "summary": "Verificar dominio de correo", "description": "Comprueba si el DNS es correcto para aprobar el dominio.", "operationId": "ntfEmail_postV1EmailDomainVerify", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID (cuid) del dominio a verificar.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verificar resultado. verificado: verdadero cuando el dominio pasó la verificación de DNS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_VerifyEmailDomainResponse" }, "examples": { "verified": { "summary": "Dominio verificado", "value": { "success": true, "verified": true, "code": "EMAIL_DOMAIN_VERIFIED", "message": "Domain verified. You can send email from this domain.", "data": { "id": "clxx123...", "domain": "yourdomain.com", "status": "VERIFIED", "dnsRecords": [], "verifiedAt": "2025-02-16T12:00:00.000Z" } } }, "dnsPending": { "summary": "DNS aún pendiente", "value": { "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": "clxx123...", "domain": "yourdomain.com", "status": "PENDING", "dnsRecords": [] } } } } } } }, "401": { "description": "Clave API faltante o no válida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Alcance correo electrónico:dominios:lista y correo electrónico:dominios:crear faltantes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "404": { "description": "Dominio no encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Not Found", "message": "Email domain not found or not in this workspace", "code": "EMAIL_DOMAIN_NOT_FOUND" } } } }, "502": { "description": "No se pudo consultar el estado del proveedor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "503": { "description": "Servicio de correo electrónico no configurado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "ntfEmailBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Clave API sin autorización de encabezado. Ejemplo: `Authorization: Bearer sk_live_xxxxx`" }, "ntfEmailApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Clave API sin encabezado x-api-key. Ejemplo: `x-api-key: sk_live_xxxxx`" } }, "schemas": { "NtfEmail_ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Etiqueta de error de estilo HTTP (por ejemplo, no autorizado, solicitud incorrecta, no encontrada)." }, "message": { "type": "string", "description": "Mensaje legible por humanos para usuarios finales (localizado a través de Accept-Language/x-locale cuando corresponda)." }, "code": { "type": "string", "description": "Código API v1 estable (enumeración). Siempre presente en los errores. Úselo con el estado HTTP para decidir reintentar o corregir. Ver [Respuestas de error](/es/guides/conceitos/resposta-de-erros)." }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } }, "data": { "type": "object", "description": "Datos adicionales en algunos errores (por ejemplo: estado del correo electrónico en cancelación)." } }, "required": [ "success", "error", "message", "code" ] }, "NtfEmail_SendEmailRequest": { "type": "object", "required": [ "from", "to", "type", "payload" ], "properties": { "from": { "type": "string", "minLength": 1, "description": "Dirección del remitente (por ejemplo, noreply@tudominio.com). El dominio debe estar verificado en el espacio de trabajo." }, "fromName": { "type": "string", "description": "Nombre mostrado del remitente (opcional)." }, "to": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100, "description": "Lista de direcciones de correo electrónico de los destinatarios. Un correo electrónico por dirección." }, "type": { "type": "string", "enum": [ "email", "template" ], "description": "Tipo de envío: `email` (contenido en `payload`) o `template` (plantilla del workspace en `payload.templateId`)." }, "payload": { "type": "object", "description": "Contenido según `type`. **email:** `subject` (obligatorio) y `text` y/o `html`. **template:** `templateId` (obligatorio) y `variables` opcionales." }, "schedule": { "type": "object", "properties": { "sendAt": { "type": "string", "format": "date-time", "description": "Fecha/hora en ISO 8601 para programar el envío." } } }, "options": { "type": "object", "properties": { "priority": { "type": "string", "enum": [ "high", "normal", "low" ], "default": "normal", "description": "Prioridad: `high` utiliza la cola de correo electrónico prioritaria de Redis y la cola de webhooks prioritarios; `normal`/`low` utilizan colas estándar." }, "webhook": { "type": "object", "description": "Webhook solo para este envío: los eventos `email.*` de este lote van a esta URL HTTPS.", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "secret": { "type": "string", "description": "Opcional. Secreto HMAC (`X-Notifique-Signature`)." } } } } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Metadatos almacenados en `Email.metadata` (cadena → pares de cadenas). Respete los límites de carga útil." }, "listUnsubscribe": { "type": "boolean", "default": true, "description": "RFC 8058: inyecta encabezados `List-Unsubscribe` y `List-Unsubscribe-Post` cuando el destinatario se asigna a un contacto del espacio de trabajo. Configure `false` para correo electrónico transaccional." }, "listUnsubscribeTopicId": { "type": "string", "description": "Opcional. ID del tema de comunicación para cancelar la suscripción con un solo clic en el ámbito del tema." } }, "description": "Al menos uno de texto o html es obligatorio." }, "NtfEmail_SendEmailResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "required": [ "messageIds", "status", "count" ], "properties": { "messageIds": { "type": "array", "items": { "type": "string" }, "description": "ID canónicos (cuid) de correos electrónicos para consulta en GET /v1/email/messages/{id} o cancelación en POST /v1/email/messages/{id}/cancel." }, "emailIds": { "type": "array", "items": { "type": "string" }, "description": "Alias ​​de compatibilidad para messageIds. Mismo valor." }, "status": { "type": "string", "enum": [ "QUEUED", "SCHEDULED" ], "description": "QUEUED = envío inmediato; PROGRAMADO = programado." }, "count": { "type": "integer", "description": "Número de correos electrónicos creados." }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Presente cuando se programa el estado; fecha/hora de programación en ISO 8601." } } } } }, "NtfEmail_EmailListItem": { "type": "object", "description": "Metadatos de envío devueltos en el listado y en GET by ID; la API siempre devuelve todos estos campos (anulables donde se indique).", "required": [ "id", "to", "from", "fromName", "subject", "status", "scheduledFor", "sentAt", "deliveredAt", "failedAt", "errorMessage", "createdAt" ], "properties": { "id": { "type": "string", "description": "ID (algunos) de su correo electrónico." }, "to": { "type": "string", "description": "Beneficiario." }, "from": { "type": "string", "description": "Remitente (dirección verificada)." }, "fromName": { "type": "string", "nullable": true }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "QUEUED", "SCHEDULED", "PROCESSING", "SENT", "DELIVERED", "OPENED", "CLICKED", "FAILED", "CANCELLED", "COMPLAINED" ], "description": "Estado actual del correo electrónico." }, "scheduledFor": { "type": "string", "format": "date-time", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "NtfEmail_EmailStatusResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/NtfEmail_EmailListItem" } } }, "NtfEmail_CancelEmailResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "emailId": { "type": "string" }, "status": { "type": "string", "enum": [ "CANCELLED" ] } } } } }, "NtfEmail_EmailDomainItem": { "type": "object", "description": "Elemento de dominio de correo electrónico (listado o detalle).", "properties": { "id": { "type": "string", "description": "ID de dominio (cuidado)." }, "domain": { "type": "string", "description": "Dominio (por ejemplo, tudominio.com)." }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "FAILED" ], "description": "PENDIENTE = esperando DNS; VERIFICADO = verificado; FAILED = verificación fallida." }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo de registro (por ejemplo: TXT, CNAME)." }, "name": { "type": "string", "description": "Nombre del registro." }, "value": { "type": "string", "description": "Valor de registro." } } }, "description": "Registros DNS a configurar en el dominio (cuando estado PENDIENTE)." }, "verifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Fecha/hora de verificación (cuando esté VERIFICADO)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Sólo presente en GET por ID." } } }, "NtfEmail_ListEmailDomainsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NtfEmail_EmailDomainItem" } } } }, "NtfEmail_CreateEmailDomainRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "minLength": 1, "description": "Dominio desde el que enviará (ej.: suempresa.com o mail.suempresa.com)." } } }, "NtfEmail_CreateEmailDomainResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "FAILED" ] }, "dnsRecords": { "type": "array", "items": { "type": "object" } }, "createdAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string", "description": "Mensaje que le indica que configure DNS y verifique la llamada." } } }, "NtfEmail_EmailDomainResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/NtfEmail_EmailDomainItem" } } }, "NtfEmail_VerifyEmailDomainResponse": { "type": "object", "required": [ "success", "code", "message", "verified" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/NtfEmail_EmailDomainItem" }, "verified": { "type": "boolean", "description": "Verdadero cuando el dominio pasó la verificación DNS." }, "code": { "type": "string", "description": "EMAIL_DOMAIN_VERIFIED, EMAIL_DOMAIN_DNS_PENDING o EMAIL_DOMAIN_VERIFY_FAILED." }, "message": { "type": "string", "description": "Mensaje legible por humanos (localizado)." } } } } } }