Ware Send Developer Documentation

QUICK START

Primeiro envio

Use a URL entregue na implantação do Ware Send e uma credencial Bearer válida.

Base URL

Os exemplos usam https://mail.seudominio.com.br. Substitua pelo FQDN configurado na sua instalação.

cURL

curl -X POST "https://mail.seudominio.com.br/api/v1/send" \
  -H "Authorization: Bearer $WARESEND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_name": "Minha Empresa",
    "from_email": "notificacoes@seudominio.com.br",
    "to": ["cliente@example.com"],
    "subject": "Pedido confirmado",
    "html": "<h1>Pedido confirmado</h1>",
    "text": "Pedido confirmado"
  }'

202 Accepted

{
  "ok": true,
  "queued": true,
  "status": "accepted",
  "queue_id": "wsq_...",
  "message_id": "<...@mail.seudominio.com.br>",
  "accepted_at": "2026-08-24T03:00:00Z",
  "cost_class": "tiny",
  "version": "1.3.3"
}

O que significa accepted?

O Ware Send validou e persistiu o trabalho na fila durável e assumiu responsabilidade pelo processamento. Isso não significa que o servidor destinatário já confirmou a entrega.

AUTHENTICATION

Bearer token

Endpoints protegidos exigem a credencial no cabeçalho HTTP Authorization.

HTTP Header

Authorization: Bearer <TOKEN>

Use no backend

Não exponha a credencial em JavaScript público, aplicativo distribuído ou código-fonte acessível ao usuário final.

Entrega da credencial

A credencial Bearer é entregue ao responsável técnico ou desenvolvedor indicado durante a implantação da integração, por canal seguro e com visualização única.

Precisa de um novo token?

Solicite uma nova credencial à DB Ware ou ao responsável autorizado pela instalação Ware Send. O token anterior não é recuperável; após a troca, a credencial antiga deve ser revogada.

ENDPOINTS

Referência rápida

POST/api/v1/send

Recebe e persiste uma mensagem para processamento assíncrono.

Bearer

GET/api/v1/info

Capacidades e limites anunciados pelo Engine instalado.

Bearer

GET/api/v1/messages/status?message_id=...

Consulta o estado conhecido de uma mensagem aceita.

Bearer

GET/api/v1/engine/status

Snapshot operacional do motor, fila, recursos e campanhas.

Bearer

GET/api/v1/engine/activity

Atividade em execução e eventos recentes do Engine.

Bearer

GET/api/v1/engine/analytics

Séries temporais e agregados operacionais de throughput, fila, recursos, scheduler, domínios e campanhas.

Bearer

GET/health

Estado básico do serviço.

Público

GET/ready

Prontidão operacional de licença, fila, Postfix e DKIM.

Público

SEND MESSAGE

Enviar uma mensagem

Envie JSON UTF-8 para /api/v1/send. A API valida, persiste e responde de forma assíncrona.

POST/api/v1/sendBearer

PAYLOAD

Campos do envio

Os campos abaixo formam o contrato público atual da API v1.

Campo	Tipo	Obrigatório	Descrição
`from_name`	string	Não	Nome amigável do remetente.
`from_email`	string	Sim	Endereço do remetente autorizado para o domínio configurado.
`to`	string \| array	Não	Destinatário principal. Aceita um e-mail como string ou uma lista de e-mails como array.
`cc`	string \| array	Não	Destinatário em cópia. Aceita string ou array.
`bcc`	string \| array	Não	Destinatário em cópia oculta. Aceita string ou array e nunca é exposto em cabeçalho visível.
`to_visible`	boolean	Não	Controla a visibilidade dos destinatários. Opcional; padrão false. false isola cada destinatário; true permite To/Cc compartilhados. Bcc nunca aparece.
`reply_to`	string	Não	Endereço Reply-To opcional.
`subject`	string	Sim	Assunto da mensagem.
`html`	string	Não	Corpo HTML.
`text`	string	Não	Corpo texto puro.
`tenant`	string	Não	Identificador lógico da aplicação, cliente ou contexto de integração.
`campaign_id`	string	Não	Identificador lógico para agrupar atividade operacional de uma campanha.
`campaign_report_email`	string	Não	E-mail opcional que receberá o relatório de conclusão da campanha. Exige campaign_id; o endereço fica vinculado à campanha enquanto o estado existir.
`idempotency_key`	string	Não	Chave estável para evitar reenvio acidental da mesma requisição.
`headers`	object	Não	Cabeçalhos adicionais não reservados. Cabeçalhos estruturais do e-mail são controlados pelo Engine.
`attachments`	array	Não	Anexos regulares ou inline/CID.

* É necessário pelo menos um destinatário entre to, cc e bcc e pelo menos um corpo entre html e text. Na API HTTP, to/cc/bcc aceitam string ou array e não há teto lógico de quantidade de destinatários; o tamanho máximo da requisição e os recursos do host continuam limites práticos. SMTP Submission possui limite independente, anunciado em GET /api/v1/info.

RECIPIENT PRIVACY

Privacidade por padrão no envio em lote

Na API, listas de destinatários são entrada de roteamento para o Motor. Enviar vários endereços no mesmo payload não autoriza o Ware Send a expor essa lista para quem recebe.

Default · to_visible=false

{
  "to": [
    "empresa-a@example.com",
    "empresa-b@example.com",
    "empresa-c@example.com"
  ],
  "subject": "Comunicado",
  "html": "<p>Olá</p>"
}

Padrão seguro: to_visible = false

Se to_visible for omitido ou false, o Motor faz fan-out interno e materializa uma entrega individual para cada destinatário. A mensagem recebida mostra apenas o próprio endereço em To:; os demais to, cc e bcc não são revelados.

Explicit opt-in · to_visible=true

{
  "to": ["a@example.com", "b@example.com"],
  "cc": ["c@example.com"],
  "to_visible": true,
  "subject": "Reunião compartilhada",
  "text": "Mensagem"
}

Visibilidade somente com opt-in explícito

Somente to_visible:true autoriza que as listas To e Cc do request apareçam conjuntamente no cabeçalho visível. Use esse modo apenas quando todos os participantes puderem conhecer os demais endereços.

Bcc nunca é visível

Bcc permanece apenas como destinatário de envelope. O Engine não emite Bcc como cabeçalho visível, inclusive quando to_visible=true.

Fan-out é responsabilidade do Motor

A API HTTP não impõe teto lógico de destinatários. O Engine divide e processa internamente o conjunto aceito. O tamanho do request e os recursos do host são limites práticos; o SMTP Submission possui limite próprio e independente.

Jobs e destinatários são métricas diferentes

Um request com muitos endereços continua sendo um job lógico, mas contém vários destinatários. Para volume real de destinatários use accepted_recipients_total e postfix_queued_recipients_total; accepted_total e postfix_queued_total contam jobs.

ATTACHMENTS

Anexos e imagens inline

A API v1 mantém compatibilidade com anexos enviados em Base64. Depois da aceitação, o Engine persiste o conteúdo em Blob e processa o envio de forma assíncrona.

Anexo regular

{
  "filename": "fatura.pdf",
  "content_type": "application/pdf",
  "content_base64": "JVBERi0xLjQK..."
}

Imagem inline / CID

{
  "html": "<img src=\"cid:logo_empresa\" alt=\"Logo\">",
  "attachments": [{
    "filename": "logo.png",
    "content_type": "image/png",
    "content_base64": "iVBORw0KGgoAAA...",
    "cid": "logo_empresa",
    "inline": true
  }]
}

Regras principais

filename e content_base64 são obrigatórios em cada anexo. Anexo inline exige cid válido e corpo HTML. CIDs duplicados na mesma mensagem são rejeitados.

RELIABILITY

Idempotência e campanhas

idempotency_key

Use uma chave previsível por evento lógico. Se a mesma requisição já tiver sido aceita, o Ware Send pode devolver a referência anterior com duplicate: true sem criar um novo trabalho.

campaign_id

Permite agrupar atividade operacional de campanhas grandes e acompanhar aceitos, processados, retries e falhas no snapshot do Engine.

campaign_report_email

Associe campaign_report_email a campaign_id para receber automaticamente um resumo da conclusão da campanha e um relatório HTML detalhado. A semântica termina no handoff ao Postfix, não no inbox.

Idempotência em processamento

Se outra requisição com a mesma chave ainda estiver sendo consolidada, a API pode responder 409 Conflict. Aguarde e consulte ou reenvie com a mesma chave.

CAMPAIGN COMPLETION

Relatório de conclusão da campanha

Quando campaign_report_email é informado junto de campaign_id, o Ware Send acompanha a campanha até o estado terminal do próprio Engine e envia um resumo HTML ao endereço configurado, com um relatório HTML autocontido e detalhado em anexo.

POST /api/v1/send

{
  "tenant": "erp-production",
  "campaign_id": "invoice-batch-2026-08-26",
  "campaign_report_email": "mail-ops@example.com",
  "from_email": "billing@example.com",
  "to": ["customer@example.net"],
  "subject": "Invoice",
  "text": "Your invoice is attached."
}

202 Accepted

{
  "ok": true,
  "status": "accepted",
  "message_id": "wsm_...",
  "campaign_report_requested": true,
  "version": "1.3.3"
}

Regra do campo

O campo é opcional. Se informado, campaign_id é obrigatório. O mesmo campaign_id não pode trocar silenciosamente o destinatário do relatório enquanto seu estado existir; use um ID exclusivo para cada campanha lógica.

Quando o relatório é emitido

Após todos os jobs aceitos da campanha estarem em POSTFIX_QUEUED ou falha terminal do Engine e não ocorrerem novos aceites durante o período de quietude configurado (padrão: 60 segundos). Novos jobs posteriores podem gerar uma nova revisão.

O que ele comprova

O relatório confirma conclusão no Ware Send e handoff ao Postfix, incluindo Queue-ID quando disponível. Não é comprovante de inbox. Entrega remota, defer, bounce e classificação pelo provedor destinatário dependem de evidência do MTA/DSN.

Conteúdo entregue ao cliente

O e-mail contém resumo visual; o anexo HTML detalha campanha/tenant, jobs e destinatários aceitos, bytes, handoff ao Postfix, falhas, retries, Queue-IDs, distribuição por domínio e revisão. Tokens, senhas, licença e conteúdo das mensagens não entram no relatório.

OBSERVABILITY

Status da mensagem e do motor

Os endpoints abaixo permitem observar a execução sem acessar diretamente a VPS.

GET/api/v1/messages/status?message_id=...Bearer

Retorna o último estado conhecido para a mensagem indicada.

Exemplo

{
  "ok": true,
  "message_id": "<...@mail.seudominio.com.br>",
  "queue_id": "wsq_...",
  "state": "POSTFIX_QUEUED",
  "stage": "POSTFIX_OWNS_MESSAGE",
  "postfix_queue_id": "4ABC123DEF",
  "cost_class": "tiny",
  "recipients": 1,
  "attempts": 0,
  "version": "1.3.3"
}

GET/api/v1/engine/statusBearer

Snapshot amplo do Engine: backlog, workers, taxas de entrada e saída, recursos, fila Postfix, estado adaptativo, atividade recente e campanhas.

GET/api/v1/engine/activityBearer

Visão reduzida para acompanhamento frequente: estado adaptativo, pendentes, trabalhos ativos, eventos recentes e throughput.

GET/api/v1/engine/analyticsBearer

Séries temporais e agregados operacionais de throughput, fila, recursos, scheduler, domínios e campanhas.

ACCEPTEDQUEUEDMATERIALIZINGPOSTFIX_QUEUED

A API v1 atual acompanha com precisão a responsabilidade do Ware Send até a aceitação pelo Postfix. Confirmação final por destinatário, DSN/bounce e estados de entrega remota serão documentados quando fizerem parte do contrato público.

HTTP

Respostas e erros

HTTP	Significado	Tratamento recomendado
202	Mensagem aceita e persistida.	Guarde message_id e queue_id quando precisar acompanhar o processamento.
200	Consulta bem-sucedida ou envio idempotente já aceito.	Em duplicidade, observe duplicate: true.
400	JSON ou campos inválidos.	Corrija o payload. Campos desconhecidos também são rejeitados.
401	Credencial ausente, inválida ou revogada.	Verifique o Bearer token configurado na aplicação.
403	Instalação sem licença operacional.	Acione o responsável pela instalação Ware Send.
409	Chave de idempotência já está em processamento.	Aguarde e tente novamente usando a mesma chave.
503	Fila indisponível ou backpressure temporário.	Respeite Retry-After quando presente e faça retry com backoff.

Erro de autenticação

{
  "ok": false,
  "error": "unauthorized"
}

LEGACY SYSTEMS

SMTP Submission

Para sistemas legados que não consomem API HTTP, o Ware Send oferece SMTP Submission autenticado. O SMTP entra no mesmo motor, fila, scheduler, workers e Postfix usados pela API; não existe um pipeline de entrega separado.

Disponível no Engine 1.0.0

SMTP Submission é apenas entrada autenticada para aplicações. Não é MX inbound, mailbox, POP3, IMAP ou webmail; a porta 25 permanece no papel MTA/Postfix.

SMTPmail.seudominio.com.br:587 / :465TLS + AUTH

Use o FQDN da instalação com porta 587 + STARTTLS ou porta 465 + TLS implícito. A autenticação é obrigatória e usa uma senha SMTP global da instalação, separada da API. O endereço canônico derivado do domínio (por exemplo, dbware@dbware.com.br) é apenas a identidade padrão: a mesma senha pode autenticar qualquer endereço completo do mesmo domínio, como contato@dbware.com.br, financeiro@dbware.com.br ou nfe@dbware.com.br. O alias curto canônico (dbware) continua disponível apenas para AUTH. Endereços de outro domínio são recusados e o MAIL FROM permanece sujeito ao domínio autorizado. O Bearer token da API não autentica SMTP.

Servidor	`mail.seudominio.com.br`
Porta	`587` / `465`
Segurança	`STARTTLS` / `implicit TLS`
Autenticação	`AUTH PLAIN` / `AUTH LOGIN`
Usuário	`dbware@dbware.com.br`
Senha	Senha SMTP própria entregue durante a implantação ou rotação; não use o Bearer token ws_live_ da API.

TLS é obrigatório nas duas portas

Na porta 587, conecte em SMTP e negocie STARTTLS antes de AUTH. Na porta 465, o TLS começa imediatamente na conexão. O Ware Send não aceita autenticação SMTP sem criptografia.

Fluxo SMTP

# Porta 587 / STARTTLS
S: 220 mail.seudominio.com.br ESMTP Ware Send 1.0.0
C: EHLO legado.local
S: 250-STARTTLS
C: STARTTLS
   ... TLS handshake ...
C: EHLO legado.local
S: 250-AUTH PLAIN LOGIN
C: AUTH ...
S: 235 2.7.0 Authentication successful
C: MAIL FROM:<notificacoes@seudominio.com.br>
S: 250 2.1.0 Sender OK
C: RCPT TO:<cliente@example.com>
S: 250 2.1.5 Recipient OK
C: DATA
S: 354 End data with <CR><LF>.<CR><LF>
C: ... RFC 5322 / MIME ...
C: .
S: 250 2.0.0 Message accepted for delivery; queue_id=wsq_...

O que significa o 250?

Depois do fim de DATA, o Ware Send responde 250 somente após persistir o trabalho na fila durável. Significa responsabilidade assumida, equivalente ao HTTP 202 Accepted; não significa entrega final ao destinatário.

Limites e destinatários

O SMTP usa os mesmos limites de tamanho e destinatários configurados no Engine. Consulte GET /api/v1/info. Múltiplos RCPT TO são suportados e o cliente pode reutilizar a mesma sessão para várias mensagens.

BCC e MIME

O conteúdo RFC 5322/MIME é preservado. Destinatários ocultos devem estar no envelope RCPT TO; se um cliente legado também enviar Bcc ou Resent-Bcc no cabeçalho, o Ware Send remove esse cabeçalho antes da entrega para evitar exposição.

Metadados opcionais

Clientes SMTP podem enviar X-WareSend-Tenant e X-WareSend-Campaign-ID nos cabeçalhos para associar a mensagem ao contexto operacional e à campanha.

Idempotência SMTP

A idempotência explícita da API por idempotency_key não existe no SMTP 1.0.0. Se a conexão cair depois do DATA e antes de o cliente receber o 250, a aceitação pode ficar ambígua; não assuma deduplicação automática por Message-ID.

Mesmo dataplane da API

Depois da admissão, API e SMTP usam a mesma fila e o mesmo caminho de entrega. Não há teto de egress específico para SMTP. Resultados numéricos de throughput dependem de benchmark da instalação e do comportamento do cliente SMTP.

GET/api/v1/infoBearer

GET /api/v1/info anuncia se SMTP Submission está habilitado, host, usuário padrão, auth_domain, username_policy, se existe senha configurada, 587/STARTTLS, 465/TLS implícito e mecanismos AUTH.

Descobrir a configuração

{
  "supports_smtp_submission": true,
  "smtp_submission": {
    "enabled": true,
    "host": "mail.seudominio.com.br",
    "username": "seudominio@seudominio.com.br",
    "auth_domain": "seudominio.com.br",
    "username_policy": "any-mailbox-in-auth-domain",
    "auth_configured": true,
    "auth_mechanisms": ["PLAIN", "LOGIN"],
    "starttls": {"enabled": true, "port": 587, "required": true},
    "implicit_tls": {"enabled": true, "port": 465}
  }
}

WARE SEND

Integração simples. Operação controlada pelo Engine.

A aplicação envia a mensagem; o Ware Send assume persistência, fila, controle adaptativo e entrega ao MTA conforme a capacidade da infraestrutura.

Voltar ao Ware Send