Ware Send Developer Documentation

DÉMARRAGE RAPIDE

Premier envoi

Utilisez l’URL fournie lors du déploiement de Ware Send et un identifiant Bearer valide.

Base URL

Les exemples utilisent https://mail.votredomaine.com. Remplacez-la par le FQDN configuré pour votre installation.

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

Que signifie accepted ?

Ware Send a validé et persisté le travail dans sa file durable et assume la responsabilité du traitement. Cela ne signifie pas que le serveur destinataire a déjà confirmé la livraison.

AUTHENTIFICATION

Bearer token

Les endpoints protégés exigent l’identifiant dans l’en-tête HTTP Authorization.

HTTP Header

Authorization: Bearer <TOKEN>

À utiliser côté backend

N’exposez pas l’identifiant dans du JavaScript public, une application distribuée ou du code source accessible à l’utilisateur final.

Remise de l’identifiant

L’identifiant Bearer est remis de manière sécurisée, avec affichage unique, au responsable technique ou au développeur désigné lors du déploiement de l’intégration.

Besoin d’un nouveau token ?

Demandez un nouvel identifiant à DB Ware ou au responsable autorisé de l’installation Ware Send. L’ancien token ne peut pas être récupéré ; après le remplacement, l’ancien identifiant doit être révoqué.

ENDPOINTS

Référence rapide

POST/api/v1/send

Reçoit et persiste un message pour traitement asynchrone.

Bearer

GET/api/v1/info

Capacités et limites annoncées par l’Engine installé.

Bearer

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

Consulte l’état connu d’un message accepté.

Bearer

GET/api/v1/engine/status

Snapshot opérationnel du moteur, de la file, des ressources et des campagnes.

Bearer

GET/api/v1/engine/activity

Activité en cours et événements récents de l’Engine.

Bearer

GET/api/v1/engine/analytics

Séries temporelles et agrégats opérationnels du débit, de la file, des ressources, du scheduler, des domaines et des campagnes.

Bearer

GET/health

État de base du service.

Public

GET/ready

Disponibilité opérationnelle de la licence, de la file, de Postfix et de DKIM.

Public

ENVOI

Envoyer un message

Envoyez du JSON UTF-8 vers /api/v1/send. L’API valide, persiste et répond de façon asynchrone.

POST/api/v1/sendBearer

PAYLOAD

Champs d’envoi

Les champs ci-dessous constituent le contrat public actuel de l’API v1.

Champ	Type	Obligatoire	Description
`from_name`	string	Non	Nom convivial de l’expéditeur.
`from_email`	string	Oui	Adresse d’expéditeur autorisée pour le domaine configuré.
`to`	string \| array	Non	Destinataire principal. Accepte une adresse e-mail sous forme de chaîne ou plusieurs sous forme de tableau.
`cc`	string \| array	Non	Destinataire en copie. Accepte une chaîne ou un tableau.
`bcc`	string \| array	Non	Destinataire en copie cachée. Accepte une chaîne ou un tableau et n’est jamais exposé dans un en-tête visible.
`to_visible`	boolean	Non	Contrôle la visibilité des destinataires. Optionnel; valeur par défaut false. false isole chaque destinataire; true autorise des en-têtes To/Cc partagés. Bcc n’est jamais affiché.
`reply_to`	string	Non	Adresse Reply-To facultative.
`subject`	string	Oui	Objet du message.
`html`	string	Non	Corps HTML.
`text`	string	Non	Corps texte brut.
`tenant`	string	Non	Identifiant logique de l’application, du client ou du contexte d’intégration.
`campaign_id`	string	Non	Identifiant logique pour regrouper l’activité opérationnelle d’une campagne.
`campaign_report_email`	string	Non	Adresse e-mail optionnelle recevant le rapport de fin de campagne. Requiert campaign_id et reste liée à cette campagne tant que son état existe.
`idempotency_key`	string	Non	Clé stable pour éviter la resoumission accidentelle de la même requête.
`headers`	object	Non	En-têtes supplémentaires non réservés. Les en-têtes structurels du courrier sont contrôlés par l’Engine.
`attachments`	array	Non	Pièces jointes classiques ou inline/CID.

* Au moins un destinataire parmi to, cc et bcc et au moins un corps parmi html et text sont requis. Dans l’API HTTP, to/cc/bcc acceptent une chaîne ou un tableau et aucun plafond logique de destinataires n’est imposé par l’application; la taille de la requête et les ressources de l’hôte restent des limites pratiques. SMTP Submission possède une limite indépendante annoncée par GET /api/v1/info.

CONFIDENTIALITÉ DES DESTINATAIRES

Confidentialité par défaut pour les envois multi-destinataires

Les listes de destinataires de l’API sont des données de routage pour l’Engine. Fournir de nombreuses adresses dans un payload n’autorise pas Ware Send à exposer cette liste aux destinataires.

Default · to_visible=false

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

Valeur sûre par défaut : to_visible = false

Si to_visible est omis ou false, l’Engine effectue le fan-out en interne et matérialise une livraison individuelle pour chaque destinataire. Le message reçu n’affiche que ce destinataire dans To:; les autres adresses to, cc et bcc restent cachées.

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 visibilité exige un opt-in explicite

Seul to_visible:true autorise l’affichage conjoint des listes To et Cc dans les en-têtes visibles. Utilisez ce mode uniquement lorsque tous les participants peuvent connaître les autres adresses.

Bcc n’est jamais visible

Bcc reste limité à l’enveloppe. L’Engine n’émet jamais d’en-tête Bcc visible, même avec to_visible=true.

Le fan-out relève de l’Engine

L’API HTTP n’impose aucun plafond logique de destinataires au niveau applicatif. L’Engine divise et traite le groupe accepté en interne. La taille de la requête et les ressources de l’hôte restent des limites pratiques; SMTP Submission a sa propre limite indépendante.

Jobs et destinataires sont des métriques distinctes

Une requête contenant de nombreuses adresses reste un job logique mais contient plusieurs destinataires. Utilisez accepted_recipients_total et postfix_queued_recipients_total pour le volume de destinataires; accepted_total et postfix_queued_total comptent les jobs.

PIÈCES JOINTES

Pièces jointes et images inline

L’API v1 reste compatible avec les pièces jointes Base64. Après acceptation, l’Engine persiste le contenu sous forme de Blob et traite l’envoi de manière asynchrone.

Pièce jointe classique

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

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

Règles principales

filename et content_base64 sont obligatoires pour chaque pièce jointe. Une pièce inline exige un cid valide et un corps HTML. Les CIDs dupliqués dans le même message sont rejetés.

FIABILITÉ

Idempotence et campagnes

idempotency_key

Utilisez une clé prévisible par événement logique. Si la même requête a déjà été acceptée, Ware Send peut retourner la référence précédente avec duplicate: true sans créer un nouveau travail.

campaign_id

Regroupe l’activité opérationnelle des grandes campagnes et permet de suivre les acceptés, traités, retries et échecs dans le snapshot de l’Engine.

campaign_report_email

Associez campaign_report_email à campaign_id pour recevoir automatiquement le résumé et le rapport HTML détaillé de fin.

Idempotence en cours

Si une autre requête avec la même clé est encore en consolidation, l’API peut répondre 409 Conflict. Attendez puis consultez ou renvoyez avec la même clé.

FIN DE CAMPAGNE

Rapport de fin de campagne

Avec campaign_report_email et campaign_id, Ware Send suit la campagne jusqu’à l’état terminal de l’Engine puis envoie un résumé HTML stylisé et un rapport HTML détaillé en pièce jointe.

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

Règle du champ

Champ optionnel; campaign_id devient obligatoire. Un même campaign_id ne peut pas changer silencieusement de destinataire tant que son état existe; utilisez un ID unique par campagne logique.

Quand le rapport est émis

Après que tous les jobs acceptés sont POSTFIX_QUEUED ou en échec terminal Engine et qu’aucun nouveau job n’est accepté pendant la période de silence configurée (60 s par défaut). Un travail ultérieur peut produire une nouvelle révision.

Ce qu’il certifie

Il certifie la fin de traitement Ware Send et le handoff local vers Postfix, Queue-ID inclus si disponible. Ce n’est pas un reçu inbox; livraison distante, defer et bounce exigent des preuves MTA/DSN.

Contenu reçu par le client

Le corps e-mail contient un résumé visuel; le HTML joint détaille campagne/tenant, jobs, destinataires, octets, handoff Postfix, erreurs, retries, Queue-IDs, répartition par domaine et révision. Aucun secret ni corps de message.

OBSERVABILITÉ

Statut du message et du moteur

Les endpoints ci-dessous permettent d’observer l’exécution sans accès direct au VPS.

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

Retourne le dernier état connu pour le message indiqué.

Exemple

{
  "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 large de l’Engine : backlog, workers, débits d’entrée et de sortie, ressources, file Postfix, état adaptatif, activité récente et campagnes.

GET/api/v1/engine/activityBearer

Vue réduite pour suivi fréquent : état adaptatif, attente, travaux actifs, événements récents et throughput.

GET/api/v1/engine/analyticsBearer

Séries temporelles et agrégats opérationnels du débit, de la file, des ressources, du scheduler, des domaines et des campagnes.

ACCEPTEDQUEUEDMATERIALIZINGPOSTFIX_QUEUED

L’API v1 suit précisément la responsabilité de Ware Send jusqu’à l’acceptation par Postfix. La confirmation finale par destinataire, DSN/bounce et les états de livraison distante seront documentés lorsqu’ils feront partie du contrat public.

HTTP

Réponses et erreurs

HTTP	Signification	Traitement recommandé
202	Message accepté et persisté.	Conservez message_id et queue_id si vous devez suivre le traitement.
200	Requête réussie ou envoi idempotent déjà accepté.	En cas de doublon, observez duplicate: true.
400	JSON ou champs invalides.	Corrigez le payload. Les champs inconnus sont également rejetés.
401	Identifiant absent, invalide ou révoqué.	Vérifiez le Bearer token configuré dans l’application.
403	Installation sans licence opérationnelle.	Contactez le responsable de l’installation Ware Send.
409	La clé d’idempotence est déjà en cours de traitement.	Attendez puis réessayez avec la même clé.
503	File indisponible ou backpressure temporaire.	Respectez Retry-After lorsqu’il est présent et réessayez avec backoff.

Erreur d’authentification

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

SYSTÈMES LEGACY

SMTP Submission

Pour les systèmes hérités qui ne peuvent pas utiliser une API HTTP, Ware Send fournit un SMTP Submission authentifié. SMTP rejoint le même moteur, la même file, le même scheduler, les mêmes workers et Postfix que l’API ; il n’existe pas de pipeline de livraison séparé.

Disponible avec Engine 1.0.0

SMTP Submission est uniquement une entrée applicative authentifiée. Ce n’est ni un MX entrant, ni une boîte mail, ni POP3, IMAP ou webmail ; le port 25 reste du ressort MTA/Postfix.

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

Utilisez le FQDN de l’installation avec le port 587 + STARTTLS ou le port 465 + TLS implicite. L’authentification est obligatoire et utilise un mot de passe SMTP global pour l’installation, distinct de l’API. L’adresse canonique dérivée du domaine client (par exemple, entreprise@entreprise.com) n’est que l’identité par défaut : le même mot de passe peut authentifier toute adresse complète de ce domaine, par exemple contact@entreprise.com, facturation@entreprise.com ou nfe@entreprise.com. L’alias court canonique (entreprise) reste disponible uniquement pour AUTH. Les autres domaines sont refusés et MAIL FROM reste soumis au domaine expéditeur autorisé. Le Bearer token de l’API n’authentifie pas SMTP.

Serveur	`mail.seudominio.com.br`
Port	`587` / `465`
Sécurité	`STARTTLS` / `implicit TLS`
Authentification	`AUTH PLAIN` / `AUTH LOGIN`
Utilisateur	`entreprise@entreprise.com`
Mot de passe	Mot de passe SMTP dédié remis lors du déploiement ou de la rotation ; n’utilisez pas le Bearer token ws_live_ de l’API.

TLS est obligatoire sur les deux ports

Sur le port 587, connectez-vous en SMTP puis négociez STARTTLS avant AUTH. Sur le port 465, TLS démarre immédiatement à l’ouverture de la connexion. Ware Send n’accepte pas l’authentification SMTP sans chiffrement.

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

Que signifie 250 ?

Après la fin de DATA, Ware Send renvoie 250 uniquement après persistance du travail dans la file durable. Cela signifie que la responsabilité est assumée, comme HTTP 202 Accepted ; cela ne signifie pas livraison finale au destinataire.

Limites et destinataires

SMTP utilise les mêmes limites de taille et de destinataires que celles configurées dans l’Engine. Consultez GET /api/v1/info. Plusieurs RCPT TO sont pris en charge et une session peut être réutilisée pour plusieurs messages.

BCC et MIME

Le contenu RFC 5322/MIME est préservé. Les destinataires en copie cachée doivent être présents dans l’enveloppe RCPT TO ; si un ancien client envoie aussi Bcc ou Resent-Bcc dans les en-têtes, Ware Send les retire avant livraison pour éviter toute divulgation.

Métadonnées optionnelles

Les clients SMTP peuvent envoyer X-WareSend-Tenant et X-WareSend-Campaign-ID pour associer le message à un contexte opérationnel et à une campagne.

Idempotence SMTP

La sémantique idempotency_key de l’API n’est pas disponible dans SMTP 1.0.0. Si la connexion tombe après DATA mais avant la réception du 250, l’acceptation peut être ambiguë ; ne supposez pas de déduplication automatique par Message-ID.

Même dataplane que l’API

Après admission, API et SMTP utilisent la même file et le même chemin de livraison. Il n’existe pas de plafond d’egress propre à SMTP. Le throughput chiffré dépend des benchmarks de l’installation et du comportement du client SMTP.

GET/api/v1/infoBearer

GET /api/v1/info indique si SMTP Submission est activé, l’hôte, l’utilisateur par défaut, auth_domain, username_policy, si un mot de passe est configuré, 587/STARTTLS, 465/TLS implicite et les mécanismes AUTH.

Découvrir la configuration

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

Intégration simple. Opération contrôlée par l’Engine.

L’application soumet le message ; Ware Send assure la persistance, la file, le contrôle adaptatif et la remise au MTA selon la capacité de l’infrastructure.

Retour à Ware Send