Ware Send Developer Documentation

INICIO RÁPIDO

Primer envío

Use la URL entregada durante la implantación de Ware Send y una credencial Bearer válida.

Base URL

Los ejemplos usan https://mail.sudominio.com. Sustitúyala por el FQDN configurado en su instalación.

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"
}

¿Qué significa accepted?

Ware Send validó y persistió el trabajo en su cola duradera y asumió la responsabilidad del procesamiento. No significa que el servidor destinatario ya haya confirmado la entrega.

AUTENTICACIÓN

Bearer token

Los endpoints protegidos requieren la credencial en el encabezado HTTP Authorization.

HTTP Header

Authorization: Bearer <TOKEN>

Úselo en el backend

No exponga la credencial en JavaScript público, aplicaciones distribuidas o código fuente accesible al usuario final.

Entrega de la credencial

La credencial Bearer se entrega de forma segura y con visualización única al responsable técnico o desarrollador indicado durante la implantación de la integración.

¿Necesita un nuevo token?

Solicite una nueva credencial a DB Ware o al responsable autorizado de la instalación Ware Send. El token anterior no se puede recuperar; después del cambio, la credencial antigua debe revocarse.

ENDPOINTS

Referencia rápida

POST/api/v1/send

Recibe y persiste un mensaje para procesamiento asíncrono.

Bearer

GET/api/v1/info

Capacidades y límites anunciados por el Engine instalado.

Bearer

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

Consulta el estado conocido de un mensaje aceptado.

Bearer

GET/api/v1/engine/status

Snapshot operativo del motor, cola, recursos y campañas.

Bearer

GET/api/v1/engine/activity

Actividad actual y eventos recientes del Engine.

Bearer

GET/api/v1/engine/analytics

Series temporales y agregados operativos de throughput, cola, recursos, scheduler, dominios y campañas.

Bearer

GET/health

Estado básico del servicio.

Público

GET/ready

Disponibilidad operativa de licencia, cola, Postfix y DKIM.

Público

ENVIAR MENSAJE

Enviar un mensaje

Envíe JSON UTF-8 a /api/v1/send. La API valida, persiste y responde de forma asíncrona.

POST/api/v1/sendBearer

PAYLOAD

Campos de envío

Los campos siguientes forman el contrato público actual de API v1.

Campo	Tipo	Obligatorio	Descripción
`from_name`	string	No	Nombre amigable del remitente.
`from_email`	string	Sí	Dirección autorizada del remitente para el dominio configurado.
`to`	string \| array	No	Destinatario principal. Acepta un e-mail como string o varios como array.
`cc`	string \| array	No	Destinatario en copia. Acepta string o array.
`bcc`	string \| array	No	Destinatario en copia oculta. Acepta string o array y nunca se expone en un encabezado visible.
`to_visible`	boolean	No	Controla la visibilidad de destinatarios. Opcional; valor predeterminado false. false aísla cada destinatario; true permite To/Cc compartidos. Bcc nunca se muestra.
`reply_to`	string	No	Dirección Reply-To opcional.
`subject`	string	Sí	Asunto del mensaje.
`html`	string	No	Cuerpo HTML.
`text`	string	No	Cuerpo de texto plano.
`tenant`	string	No	Identificador lógico de la aplicación, cliente o contexto de integración.
`campaign_id`	string	No	Identificador lógico para agrupar actividad operativa de una campaña.
`campaign_report_email`	string	No	E-mail opcional que recibe el informe de finalización de campaña. Requiere campaign_id y queda vinculado a esa campaña mientras exista su estado.
`idempotency_key`	string	No	Clave estable para evitar el reenvío accidental de la misma solicitud.
`headers`	object	No	Encabezados adicionales no reservados. Los encabezados estructurales del correo son controlados por el Engine.
`attachments`	array	No	Adjuntos regulares o inline/CID.

* Se requiere al menos un destinatario entre to, cc y bcc y al menos un cuerpo entre html y text. En la API HTTP, to/cc/bcc aceptan string o array y no existe un límite lógico de cantidad de destinatarios a nivel de aplicación; el tamaño del request y los recursos del host siguen siendo límites prácticos. SMTP Submission tiene un límite independiente anunciado por GET /api/v1/info.

PRIVACIDAD DE DESTINATARIOS

Privacidad predeterminada en envíos con múltiples destinatarios

Las listas de destinatarios de la API son datos de enrutamiento para el Engine. Incluir muchas direcciones en un payload no autoriza a Ware Send a exponer esa lista a los receptores.

Default · to_visible=false

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

Predeterminado seguro: to_visible = false

Si to_visible se omite o es false, el Engine realiza fan-out interno y materializa una entrega individual por destinatario. El mensaje recibido muestra solamente ese destinatario en To:; los demás to, cc y bcc permanecen ocultos.

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"
}

La visibilidad requiere opt-in explícito

Solo to_visible:true permite que las listas To y Cc del request aparezcan juntas en los encabezados visibles. Úselo únicamente cuando todos los participantes puedan conocer las demás direcciones.

Bcc nunca es visible

Bcc permanece únicamente en el envelope. El Engine nunca emite un encabezado Bcc visible, incluso con to_visible=true.

El fan-out es responsabilidad del Engine

La API HTTP no impone un límite lógico de destinatarios a nivel de aplicación. El Engine divide y procesa internamente el conjunto aceptado. El tamaño del request y los recursos del host son límites prácticos; SMTP Submission tiene su propio límite.

Jobs y destinatarios son métricas distintas

Un request con muchas direcciones sigue siendo un job lógico, pero contiene múltiples destinatarios. Use accepted_recipients_total y postfix_queued_recipients_total para el volumen de destinatarios; accepted_total y postfix_queued_total cuentan jobs.

ADJUNTOS

Adjuntos e imágenes inline

API v1 mantiene compatibilidad con adjuntos enviados en Base64. Tras la aceptación, el Engine persiste el contenido como Blob y procesa el envío de forma asíncrona.

Adjunto regular

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

Imagen 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
  }]
}

Reglas principales

filename y content_base64 son obligatorios en cada adjunto. Un adjunto inline requiere cid válido y cuerpo HTML. Se rechazan CIDs duplicados en el mismo mensaje.

FIABILIDAD

Idempotencia y campañas

idempotency_key

Use una clave predecible por evento lógico. Si la misma solicitud ya fue aceptada, Ware Send puede devolver la referencia anterior con duplicate: true sin crear un nuevo trabajo.

campaign_id

Permite agrupar actividad operativa de campañas grandes y seguir aceptados, procesados, retries y fallos en el snapshot del Engine.

campaign_report_email

Asocie campaign_report_email a campaign_id para recibir automáticamente el resumen y el HTML detallado de finalización.

Idempotencia en proceso

Si otra solicitud con la misma clave aún se está consolidando, la API puede responder 409 Conflict. Espere y consulte o reenvíe usando la misma clave.

FINALIZACIÓN DE CAMPAÑA

Informe de finalización de campaña

Al informar campaign_report_email junto con campaign_id, Ware Send sigue la campaña hasta el estado terminal del Engine y envía un resumen HTML estilizado con un informe HTML detallado adjunto.

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"
}

Regla del campo

El campo es opcional. Si se informa, campaign_id es obligatorio. El mismo campaign_id no puede cambiar silenciosamente el destinatario mientras exista el estado de campaña; use un ID único por campaña lógica.

Cuándo se emite

Cuando todos los jobs aceptados están en POSTFIX_QUEUED o fallo terminal del Engine y no se aceptan nuevos jobs durante el período de quietud configurado (60 s por defecto). Trabajo posterior puede generar una nueva revisión.

Qué certifica

Certifica la finalización en Ware Send y la entrega local a Postfix, con Queue-ID cuando esté disponible. No es un recibo de inbox; entrega remota, defer y bounce requieren evidencia MTA/DSN.

Contenido para el cliente

El cuerpo contiene un resumen visual y el HTML adjunto detalla campaña/tenant, jobs, destinatarios, bytes, handoff a Postfix, fallos, retries, Queue-IDs, distribución por dominio y revisión. No incluye secretos ni cuerpos de mensajes.

OBSERVABILIDAD

Estado del mensaje y del motor

Los endpoints siguientes permiten observar la ejecución sin acceder directamente al VPS.

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

Devuelve el último estado conocido del mensaje indicado.

Ejemplo

{
  "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 amplio del Engine: backlog, workers, tasas de entrada y salida, recursos, cola Postfix, estado adaptativo, actividad reciente y campañas.

GET/api/v1/engine/activityBearer

Vista reducida para seguimiento frecuente: estado adaptativo, pendientes, trabajos activos, eventos recientes y throughput.

GET/api/v1/engine/analyticsBearer

Series temporales y agregados operativos de throughput, cola, recursos, scheduler, dominios y campañas.

ACCEPTEDQUEUEDMATERIALIZINGPOSTFIX_QUEUED

API v1 acompaña con precisión la responsabilidad de Ware Send hasta la aceptación por Postfix. La confirmación final por destinatario, DSN/bounce y estados de entrega remota se documentarán cuando formen parte del contrato público.

HTTP

Respuestas y errores

HTTP	Significado	Tratamiento recomendado
202	Mensaje aceptado y persistido.	Guarde message_id y queue_id si necesita acompañar el procesamiento.
200	Consulta correcta o envío idempotente ya aceptado.	En duplicados, observe duplicate: true.
400	JSON o campos inválidos.	Corrija el payload. Los campos desconocidos también son rechazados.
401	Credencial ausente, inválida o revocada.	Verifique el Bearer token configurado en la aplicación.
403	Instalación sin licencia operativa.	Contacte al responsable de la instalación Ware Send.
409	La clave de idempotencia ya está en procesamiento.	Espere e inténtelo de nuevo usando la misma clave.
503	Cola no disponible o backpressure temporal.	Respete Retry-After cuando esté presente y reintente con backoff.

Error de autenticación

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

SISTEMAS LEGADOS

SMTP Submission

Para sistemas heredados que no pueden consumir una API HTTP, Ware Send ofrece SMTP Submission autenticado. SMTP entra en el mismo motor, cola, scheduler, workers y Postfix usados por la API; no existe un pipeline de entrega separado.

Disponible en Engine 1.0.0

SMTP Submission es solo entrada autenticada para aplicaciones. No es MX entrante, buzón, POP3, IMAP ni webmail; el puerto 25 permanece en el papel MTA/Postfix.

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

Use el FQDN de la instalación con el puerto 587 + STARTTLS o el puerto 465 + TLS implícito. La autenticación es obligatoria y usa una contraseña SMTP global de la instalación, separada de la API. La dirección canónica derivada del dominio del cliente (por ejemplo, empresa@empresa.com) es solo la identidad predeterminada: la misma contraseña puede autenticar cualquier dirección completa de ese dominio, como contacto@empresa.com, facturacion@empresa.com o nfe@empresa.com. El alias corto canónico (empresa) sigue disponible solo para AUTH. Se rechazan otros dominios y MAIL FROM continúa sujeto al dominio remitente autorizado. El Bearer token de la API no autentica SMTP.

Servidor	`mail.seudominio.com.br`
Puerto	`587` / `465`
Seguridad	`STARTTLS` / `implicit TLS`
Autenticación	`AUTH PLAIN` / `AUTH LOGIN`
Usuario	`empresa@empresa.com`
Contraseña	Contraseña SMTP propia entregada durante la implantación o rotación; no use el Bearer token ws_live_ de la API.

TLS es obligatorio en ambos puertos

En el puerto 587, conecte por SMTP y negocie STARTTLS antes de AUTH. En el puerto 465, TLS comienza inmediatamente al abrir la conexión. Ware Send no acepta autenticación SMTP sin cifrado.

Flujo 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_...

¿Qué significa 250?

Después de finalizar DATA, Ware Send responde 250 solo después de persistir el trabajo en la cola duradera. Significa responsabilidad asumida, equivalente a HTTP 202 Accepted; no significa entrega final al destinatario.

Límites y destinatarios

SMTP usa los mismos límites de tamaño de mensaje y destinatarios configurados en el Engine. Consulte GET /api/v1/info. Se admiten múltiples RCPT TO y el cliente puede reutilizar una sesión para varios mensajes.

BCC y MIME

Se preserva el contenido RFC 5322/MIME. Los destinatarios ocultos deben estar en el envelope RCPT TO; si un cliente heredado también envía Bcc o Resent-Bcc en los encabezados, Ware Send elimina esos encabezados antes de la entrega para evitar exposición.

Metadatos opcionales

Los clientes SMTP pueden enviar X-WareSend-Tenant y X-WareSend-Campaign-ID para asociar el mensaje con un contexto operativo y una campaña.

Idempotencia SMTP

La semántica idempotency_key de la API no está disponible en SMTP 1.0.0. Si la conexión cae después de DATA pero antes de recibir 250, la aceptación puede quedar ambigua; no suponga deduplicación automática por Message-ID.

Mismo dataplane de la API

Después de la admisión, API y SMTP usan la misma cola y ruta de entrega. No existe un límite de egress específico para SMTP. El throughput numérico depende del benchmark de la instalación y del comportamiento del cliente SMTP.

GET/api/v1/infoBearer

GET /api/v1/info informa si SMTP Submission está habilitado, host, usuario predeterminado, auth_domain, username_policy, si existe una contraseña configurada, 587/STARTTLS, 465/TLS implícito y mecanismos AUTH.

Descubrir la configuración

{
  "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

Integración simple. Operación controlada por el Engine.

La aplicación envía el mensaje; Ware Send asume persistencia, cola, control adaptativo y entrega al MTA según la capacidad de la infraestructura.

Volver a Ware Send