> ## 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. # Send email > Send email to one or more recipients. Write directly or use a template. ## OpenAPI ````yaml /en/emails-api/api-reference/openapi-email.json post /v1/email/messages openapi: 3.0.3 info: title: Notifique API. E-mail description: >- Send emails, manage domains, and check status. Authenticate with `Authorization: Bearer sk_live_...` or `x-api-key`. version: 1.0.0 servers: - url: https://api.notifique.dev description: Production 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: Send email description: Send email to one or more recipients. Write directly or use a template. operationId: ntfEmail_postV1EmailSend parameters: - name: Idempotency-Key in: header required: false description: >- Unique key to prevent duplicate sends. Alternative: x-idempotency-key. schema: type: string - name: x-idempotency-key in: header required: false description: Unique idempotency key (alternative to Idempotency-Key). schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NtfEmail_SendEmailRequest' examples: email: summary: Email value: from: noreply@yourdomain.com fromName: Support to: - customer@example.com type: email payload: subject: Order confirmation html:

Hello, your order is confirmed.

schedule: sendAt: '2025-12-31T14:00:00.000Z' options: priority: high webhook: url: https://api.example.com/hooks/email-events secret: optional_hmac_secret metadata: campaign: welcome template: summary: Workspace template value: from: noreply@yourdomain.com to: - customer@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: >- Validation: invalid to/from/subject, missing body, unverified from domain (`DOMAIN_NOT_VERIFIED`), or invalid `listUnsubscribeTopicId` (`INVALID_LIST_UNSUBSCRIBE_TOPIC`). content: application/json: schema: $ref: '#/components/schemas/NtfEmail_ErrorResponse' examples: invalidListUnsubscribeTopic: summary: Invalid List-Unsubscribe topic 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: Required field value: success: false error: Bad Request message: from and subject are required details: - field: from message: from is required code: BAD_REQUEST domain: summary: Unverified domain 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: Missing or invalid API Key. 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: >- Sender address (e.g. noreply@yourdomain.com). Domain must be verified in the workspace. fromName: type: string description: Display name of the sender (optional). to: type: array items: type: string minLength: 1 minItems: 1 maxItems: 100 description: Recipient email addresses. One email per address. type: type: string enum: - email - template description: >- Send type: `email` (content in `payload`) or `template` (workspace template in `payload.templateId`). payload: type: object description: >- Content per `type`. **email:** `subject` (required) and `text` and/or `html`. **template:** `templateId` (required) and optional `variables`. 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: >- Metadata stored on `Email.metadata` (string→string pairs). Respect payload limits. listUnsubscribe: type: boolean default: true description: >- RFC 8058: injects `List-Unsubscribe` and `List-Unsubscribe-Post` headers when the recipient maps to a workspace contact. Set `false` for transactional email. listUnsubscribeTopicId: type: string description: >- Optional. Communication topic ID for topic-scoped one-click unsubscribe. 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: HTTP-style error label (e.g. Unauthorized, Bad Request, Not Found). message: type: string description: >- Human-readable message for end users (localized via Accept-Language / x-locale when applicable). code: type: string description: >- Stable API v1 code (enum). Always present on errors. Use with the HTTP status to decide retry or fix. See [Error responses](/en/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`' ````