{ "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": { "get": { "tags": [ "E-mail" ], "summary": "Listar mensagens e-mail", "description": "Mostra o histórico de e-mail enviados. Dá para filtrar por data e status.", "operationId": "ntfEmail_getV1EmailMessages", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "string" }, "description": "Página (padrão 1)." }, { "name": "limit", "in": "query", "schema": { "type": "string" }, "description": "Itens por página (padrão 20, máx. 100)." }, { "name": "fromDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Início do intervalo (filtro em createdAt, inclusive)." }, { "name": "toDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Fim do intervalo (filtro em createdAt, inclusive)." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Um ou mais status separados por vírgula: QUEUED, SCHEDULED, PROCESSING, SENT, DELIVERED, OPENED, CLICKED, FAILED, CANCELLED, COMPLAINED. Valores inválidos são ignorados." }, { "name": "emailDomainId", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo ID (cuid) do domínio de envio; deve pertencer ao workspace. Alternativa: `email_domain_id`." }, { "name": "email_domain_id", "in": "query", "schema": { "type": "string" }, "description": "Alias de `emailDomainId`." } ], "responses": { "200": { "description": "Lista de e-mails e paginação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "description": "Cada item tem os mesmos campos que GET /v1/email/messages/{id} em `data`. Não inclui corpo (`html`/`text`), `emailDomainId`, `externalId` nem `providerUsed`.", "items": { "$ref": "#/components/schemas/NtfEmail_EmailListItem" } }, "pagination": { "type": "object", "required": [ "total", "page", "limit", "totalPages" ], "properties": { "total": { "type": "integer", "description": "Total de e-mails que batem com os 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 não existe neste workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "401": { "description": "API Key ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Escopo email:read ausente, ou `emailDomainId` não permitido para a API Key (restrição **domainIds**), ou listagem com chave restrita a domínios sem acesso ao filtro solicitado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } }, "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" } } } } } } }, "/v1/email/messages/{id}": { "get": { "tags": [ "E-mail" ], "summary": "Consultar envio e-mail", "description": "Consulta se foi enviado, entregue ou falhou, e vê os detalhes.", "operationId": "ntfEmail_getV1EmailById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID (cuid) do e-mail retornado em POST /v1/email/messages.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dados do e-mail.", "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": "API Key ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Escopo email:read ausente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "404": { "description": "E-mail não encontrado ou não pertence ao workspace.", "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 e-mail agendado", "description": "Cancela algo que ainda não saiu — estava na fila ou agendado.", "operationId": "ntfEmail_postV1EmailCancel", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID (cuid) do e-mail agendado.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "E-mail cancelado com sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_CancelEmailResponse" }, "example": { "success": true, "data": { "emailId": "clxx123...", "status": "CANCELLED" } } } } }, "400": { "description": "E-mail não está QUEUED nem SCHEDULED (apenas esses status podem ser cancelados).", "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": "API Key ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Escopo email:cancel ausente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "404": { "description": "E-mail não encontrado ou não pertence ao workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } } }, "/v1/email/domains": { "get": { "tags": [ "Domínios", "E-mail" ], "summary": "Listar domínios de e-mail", "description": "Lista os domínios cadastrados para envio.", "operationId": "ntfEmail_getV1EmailDomains", "responses": { "200": { "description": "Lista de domínios.", "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": "API Key ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Escopo email:domains:list ausente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } }, "post": { "tags": [ "Domínios", "E-mail" ], "summary": "Cadastrar domínio de e-mail", "description": "Cadastra um domínio para enviar e-mails (ex.: @suaempresa.com). A resposta traz o que configurar no DNS.", "operationId": "ntfEmail_postV1EmailDomains", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_CreateEmailDomainRequest" }, "examples": { "rootDomain": { "summary": "Domínio raiz", "description": "Ex.: emails de @suaempresa.com", "value": { "domain": "suaempresa.com" } }, "subdomain": { "summary": "Subdomínio", "description": "Ex.: emails de @mail.suaempresa.com", "value": { "domain": "mail.suaempresa.com" } } } } } }, "responses": { "200": { "description": "Domínio registrado. Configure os registros DNS retornados e depois chame o endpoint de verify.", "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": "Domínio invá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": "API Key ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "402": { "description": "Trial/plano expirado (WORKSPACE_BLOCKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Escopo ausente ou limite de domínios do plano (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": "Domínio já registrado neste workspace.", "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": "Falha ao iniciar verificação do domínio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "503": { "description": "Serviço de e-mail não configurado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } } }, "/v1/email/domains/{id}": { "get": { "tags": [ "Domínios", "E-mail" ], "summary": "Consultar domínio de e-mail", "description": "Consulta status e registros DNS de um domínio.", "operationId": "ntfEmail_getV1EmailDomainById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID (cuid) do domínio.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dados do domínio.", "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": "API Key ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Escopo email:domains:list ausente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "404": { "description": "Domínio não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Not Found", "message": "Domain not found", "code": "NOT_FOUND" } } } } } } }, "/v1/email/domains/{id}/verify": { "post": { "tags": [ "Domínios", "E-mail" ], "summary": "Verificar domínio de e-mail", "description": "Confere se o DNS está correto para liberar o domínio para envio.", "operationId": "ntfEmail_postV1EmailDomainVerify", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID (cuid) do domínio a verificar.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resultado da verificação. verified: true quando o domínio passou na checagem DNS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_VerifyEmailDomainResponse" }, "examples": { "verified": { "summary": "Domínio verificado", "value": { "success": true, "verified": true, "code": "EMAIL_DOMAIN_VERIFIED", "message": "Domínio verificado. Você já pode enviar e-mails por este domínio.", "data": { "id": "clxx123...", "domain": "seudominio.com", "status": "VERIFIED", "dnsRecords": [], "verifiedAt": "2025-02-16T12:00:00.000Z" } } }, "dnsPending": { "summary": "DNS ainda pendente", "value": { "success": true, "verified": false, "code": "EMAIL_DOMAIN_DNS_PENDING", "message": "Os registros DNS ainda não foram verificados. Confira no seu provedor DNS e tente novamente em alguns minutos.", "data": { "id": "clxx123...", "domain": "seudominio.com", "status": "PENDING", "dnsRecords": [] } } } } } } }, "401": { "description": "API Key ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "403": { "description": "Escopo email:domains:list e email:domains:create ausentes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "404": { "description": "Domínio não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" }, "example": { "success": false, "error": "Not Found", "message": "Domínio de e-mail não encontrado ou não pertence a este workspace", "code": "EMAIL_DOMAIN_NOT_FOUND" } } } }, "502": { "description": "Falha ao consultar status no provedor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } }, "503": { "description": "Serviço de e-mail não configurado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfEmail_ErrorResponse" } } } } } } } }, "components": { "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`" } }, "schemas": { "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" ] }, "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_EmailListItem": { "type": "object", "description": "Metadados de envio retornados na listagem e em GET por ID; a API sempre devolve todos estes campos (nullable onde indicado).", "required": [ "id", "to", "from", "fromName", "subject", "status", "scheduledFor", "sentAt", "deliveredAt", "failedAt", "errorMessage", "createdAt" ], "properties": { "id": { "type": "string", "description": "ID (cuid) do e-mail." }, "to": { "type": "string", "description": "Destinatário." }, "from": { "type": "string", "description": "Remetente (endereço verificado)." }, "fromName": { "type": "string", "nullable": true }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "QUEUED", "SCHEDULED", "PROCESSING", "SENT", "DELIVERED", "OPENED", "CLICKED", "FAILED", "CANCELLED", "COMPLAINED" ], "description": "Status atual do e-mail." }, "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": "Item de domínio de e-mail (listagem ou detalhe).", "properties": { "id": { "type": "string", "description": "ID (cuid) do domínio." }, "domain": { "type": "string", "description": "Domínio (ex.: seudominio.com)." }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "FAILED" ], "description": "PENDING = aguardando DNS; VERIFIED = verificado; FAILED = verificação falhou." }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo do registro (ex.: TXT, CNAME)." }, "name": { "type": "string", "description": "Nome do registro." }, "value": { "type": "string", "description": "Valor do registro." } } }, "description": "Registros DNS a serem configurados no domínio (quando status PENDING)." }, "verifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora da verificação (quando VERIFIED)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Presente apenas em 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": "Domínio que você vai usar no remetente (ex.: suaempresa.com ou mail.suaempresa.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": "Mensagem orientando a configurar DNS e chamar verify." } } }, "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": "true quando o domínio passou na verificação DNS." }, "code": { "type": "string", "description": "EMAIL_DOMAIN_VERIFIED, EMAIL_DOMAIN_DNS_PENDING ou EMAIL_DOMAIN_VERIFY_FAILED." }, "message": { "type": "string", "description": "Mensagem legível (localizada)." } } } } } }