> ## 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 e-mail > Envia e-mail para um ou vários destinatários. Escreva o texto na hora ou use um template. ## OpenAPI ````yaml /emails-api/api-reference/openapi-email.json post /v1/email/messages openapi: 3.0.3 info: title: Notifique API. E-mail description: >- Envie e-mails, gerencie domínios e consulte status. Autentique com `Authorization: Bearer sk_live_...` ou `x-api-key`. version: 1.0.0 servers: - url: https://api.notifique.dev description: Produção security: - ntfEmailBearerAuth: [] - ntfEmailApiKeyHeader: [] tags: - name: E-mail description: Envio e consulta de e-mail - name: Domínios description: Registro e verificação de domínios para envio de e-mail paths: /v1/email/messages: post: tags: - E-mail summary: Enviar e-mail description: >- Envia e-mail para um ou vários destinatários. Escreva o texto na hora ou use um template. operationId: ntfEmail_postV1EmailSend parameters: - name: Idempotency-Key in: header required: false description: >- Chave única para evitar envio duplicado. Alternativa: x-idempotency-key. schema: type: string - name: x-idempotency-key in: header required: false description: Chave única para idempotência (alternativa a Idempotency-Key). schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NtfEmail_SendEmailRequest' examples: email: summary: E-mail value: from: noreply@seudominio.com fromName: Suporte to: - cliente@example.com type: email payload: subject: Confirmação de pedido html:

Olá, seu pedido foi confirmado.

schedule: sendAt: '2025-12-31T14:00:00.000Z' options: priority: high webhook: url: https://api.seudominio.com/hooks/email-events secret: opcional_hmac_secret metadata: campaign: welcome template: summary: Template do workspace value: from: noreply@seudominio.com to: - cliente@example.com type: template payload: templateId: tpl_abc123 variables: name: Maria responses: '202': description: E-mail(s) aceito(s). Enfileirado(s) para envio imediato ou agendado. content: application/json: schema: $ref: '#/components/schemas/NtfEmail_SendEmailResponse' examples: queued: summary: Envio imediato value: success: true data: messageIds: - clxx123... - clxx456... emailIds: - clxx123... - clxx456... status: QUEUED count: 2 scheduled: summary: Agendado value: success: true data: messageIds: - clxx123... emailIds: - clxx123... status: SCHEDULED count: 1 scheduledAt: '2025-12-31T14:00:00.000Z' '400': description: >- Validação: to/from/subject inválidos, corpo ausente, domínio do from não verificado (`DOMAIN_NOT_VERIFIED`), ou `listUnsubscribeTopicId` inválido (`INVALID_LIST_UNSUBSCRIBE_TOPIC`). content: application/json: schema: $ref: '#/components/schemas/NtfEmail_ErrorResponse' examples: invalidListUnsubscribeTopic: summary: Tópico de List-Unsubscribe inválido 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 obrigatório value: success: false error: Bad Request message: from and subject are required details: - field: from message: from is required code: BAD_REQUEST domain: summary: Domínio não 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: API Key ausente ou inválida. content: application/json: schema: $ref: '#/components/schemas/NtfEmail_ErrorResponse' '402': description: >- Trial/plano expirado (WORKSPACE_BLOCKED), créditos/saldo insuficientes (INSUFFICIENT_CREDITS / INSUFFICIENT_CREDITS_OR_BALANCE) ou limite da API Key (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: >- Escopo email:send ausente ou créditos/plano insuficiente (PLAN_LIMIT_CREDITS) ou agendamento não permitido (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: Serviço de e-mail não configurado ou falha ao enfileirar. 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: >- Endereço do remetente (ex.: noreply@seudominio.com). O domínio deve estar verificado no workspace. fromName: type: string description: Nome exibido do remetente (opcional). to: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 description: >- Lista de endereços de e-mail dos destinatários. Um e-mail por endereço. type: type: string enum: - email - template description: >- Tipo do envio: `email` (conteúdo em `payload`) ou `template` (template do workspace em `payload.templateId`). payload: type: object description: >- Conteúdo conforme `type`. **email:** `subject` (obrigatório) e `text` e/ou `html`. **template:** `templateId` (obrigatório) e `variables` opcionais. schedule: type: object properties: sendAt: type: string format: date-time description: Data/hora em ISO 8601 para agendar o envio. options: type: object properties: priority: type: string enum: - high - normal - low default: normal description: >- Prioridade: `high` usa fila Redis prioritária de e-mail e fila prioritária de webhooks; `normal`/`low` usam filas padrão. webhook: type: object description: >- Webhook só para este envio: eventos `email.*` deste lote vão para esta URL HTTPS. required: - url properties: url: type: string format: uri maxLength: 2048 secret: type: string description: Opcional. Segredo HMAC (`X-Notifique-Signature`). metadata: type: object additionalProperties: type: string description: >- Metadados persistidos em `Email.metadata` (pares string→string). Respeite limites de payload. listUnsubscribe: type: boolean default: true description: >- RFC 8058: injeta headers `List-Unsubscribe` e `List-Unsubscribe-Post` quando o destinatário resolve para um contato do workspace. Use `false` em e-mails transacionais. listUnsubscribeTopicId: type: string description: >- Opcional. ID do tópico de comunicação para one-click scoped (unsubscribe só daquele tópico). description: Pelo menos um de text ou html é obrigatório. 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: >- IDs canônicos (cuid) dos e-mails para consulta em GET /v1/email/messages/{id} ou cancelamento em POST /v1/email/messages/{id}/cancel. emailIds: type: array items: type: string description: Alias de compatibilidade para messageIds. Mesmo valor. status: type: string enum: - QUEUED - SCHEDULED description: QUEUED = envio imediato; SCHEDULED = agendado. count: type: integer description: Quantidade de e-mails criados. scheduledAt: type: string format: date-time description: >- Presente quando status é scheduled; data/hora do agendamento em ISO 8601. NtfEmail_ErrorResponse: type: object properties: success: type: boolean example: false error: type: string description: 'Rótulo HTTP do erro (ex.: Unauthorized, Bad Request, Not Found).' message: type: string description: >- Mensagem legível para exibir ao usuário (localizada via Accept-Language / x-locale quando aplicável). code: type: string description: >- Código estável da API v1 (enum). Sempre presente em erros. Use com o status HTTP para decidir retry ou correção. Ver [Respostas de erro](/guides/conceitos/resposta-de-erros). details: type: array items: type: object properties: field: type: string message: type: string data: type: object description: 'Dados adicionais em alguns erros (ex.: status do e-mail em cancel).' required: - success - error - message - code securitySchemes: ntfEmailBearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key no header Authorization. Exemplo: `Authorization: Bearer sk_live_xxxxx` ntfEmailApiKeyHeader: type: apiKey in: header name: x-api-key description: 'API Key no header x-api-key. Exemplo: `x-api-key: sk_live_xxxxx`' ````