> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt > Use this file to discover all available pages before exploring further. # Enviar correo > Envía correo a uno o más destinatarios. Escribe el texto o usa una plantilla. ## OpenAPI ````yaml /es/emails-api/api-reference/openapi-email.json post /v1/email/messages 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: 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 components: schemas: 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_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 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`' ````