Ware Send Developer Documentation

AVVIO RAPIDO

Primo invio

Usa l’URL fornito durante il deployment di Ware Send e una credenziale Bearer valida.

Base URL

Gli esempi usano https://mail.tuodominio.it. Sostituiscilo con il FQDN configurato nella tua installazione.

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

Cosa significa accepted?

Ware Send ha validato e persistito il lavoro nella coda durevole e ha assunto la responsabilità dell’elaborazione. Non significa che il server destinatario abbia già confermato la consegna.

AUTENTICAZIONE

Bearer token

Gli endpoint protetti richiedono la credenziale nell’header HTTP Authorization.

HTTP Header

Authorization: Bearer <TOKEN>

Usalo nel backend

Non esporre la credenziale in JavaScript pubblico, applicazioni distribuite o codice sorgente accessibile all’utente finale.

Consegna della credenziale

La credenziale Bearer viene consegnata in modo sicuro, con visualizzazione unica, al referente tecnico o sviluppatore indicato durante l’implementazione dell’integrazione.

Serve un nuovo token?

Richiedi una nuova credenziale a DB Ware o al referente autorizzato dell’installazione Ware Send. Il token precedente non è recuperabile; dopo la sostituzione, la vecchia credenziale deve essere revocata.

ENDPOINTS

Riferimento rapido

POST/api/v1/send

Riceve e persiste un messaggio per elaborazione asincrona.

Bearer

GET/api/v1/info

Capacità e limiti dichiarati dall’Engine installato.

Bearer

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

Consulta lo stato noto di un messaggio accettato.

Bearer

GET/api/v1/engine/status

Snapshot operativo del motore, coda, risorse e campagne.

Bearer

GET/api/v1/engine/activity

Attività in corso ed eventi recenti dell’Engine.

Bearer

GET/api/v1/engine/analytics

Serie temporali e aggregati operativi per throughput, coda, risorse, scheduler, domini e campagne.

Bearer

GET/health

Stato base del servizio.

Pubblico

GET/ready

Prontezza operativa di licenza, coda, Postfix e DKIM.

Pubblico

INVIO MESSAGGIO

Inviare un messaggio

Invia JSON UTF-8 a /api/v1/send. L’API valida, persiste e risponde in modo asincrono.

POST/api/v1/sendBearer

PAYLOAD

Campi invio

I campi seguenti costituiscono il contratto pubblico attuale di API v1.

Campo	Tipo	Obbligatorio	Descrizione
`from_name`	string	No	Nome descrittivo del mittente.
`from_email`	string	Sì	Indirizzo mittente autorizzato per il dominio configurato.
`to`	string \| array	No	Destinatario principale. Accetta un indirizzo e-mail come stringa o più indirizzi come array.
`cc`	string \| array	No	Destinatario in copia. Accetta stringa o array.
`bcc`	string \| array	No	Destinatario in copia nascosta. Accetta stringa o array e non viene mai esposto in un header visibile.
`to_visible`	boolean	No	Controlla la visibilità dei destinatari. Opzionale; default false. false isola ogni destinatario; true consente header To/Cc condivisi. Bcc non viene mai mostrato.
`reply_to`	string	No	Indirizzo Reply-To opzionale.
`subject`	string	Sì	Oggetto del messaggio.
`html`	string	No	Corpo HTML.
`text`	string	No	Corpo testo semplice.
`tenant`	string	No	Identificatore logico dell’applicazione, cliente o contesto di integrazione.
`campaign_id`	string	No	Identificatore logico per raggruppare l’attività operativa di una campagna.
`campaign_report_email`	string	No	Indirizzo e-mail opzionale che riceve il report di completamento campagna. Richiede campaign_id e resta associato alla campagna finché ne esiste lo stato.
`idempotency_key`	string	No	Chiave stabile per evitare il reinvio accidentale della stessa richiesta.
`headers`	object	No	Header aggiuntivi non riservati. Gli header strutturali dell’e-mail sono controllati dall’Engine.
`attachments`	array	No	Allegati regolari o inline/CID.

* È richiesto almeno un destinatario tra to, cc e bcc e almeno un corpo tra html e text. Nell’API HTTP, to/cc/bcc accettano stringa o array e non esiste un limite logico applicativo al numero di destinatari; dimensione della request e risorse dell’host restano limiti pratici. SMTP Submission ha un limite indipendente annunciato da GET /api/v1/info.

PRIVACY DESTINATARI

Privacy predefinita negli invii multi-destinatario

Le liste di destinatari dell’API sono input di routing per l’Engine. Inserire molti indirizzi nello stesso payload non autorizza Ware Send a esporre tale lista ai destinatari.

Default · to_visible=false

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

Default sicuro: to_visible = false

Se to_visible è omesso o false, l’Engine esegue il fan-out interno e materializza una consegna individuale per ogni destinatario. Il messaggio ricevuto mostra soltanto quel destinatario in To:; gli altri to, cc e bcc restano nascosti.

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

Visibilità solo con opt-in esplicito

Solo to_visible:true consente alle liste To e Cc della request di comparire insieme negli header visibili. Usare questa modalità solo quando tutti i partecipanti possono conoscere gli altri indirizzi.

Bcc non è mai visibile

Bcc rimane solo nell’envelope. L’Engine non emette mai un header Bcc visibile, anche con to_visible=true.

Il fan-out è responsabilità dell’Engine

L’API HTTP non impone un limite logico applicativo ai destinatari. L’Engine divide e processa internamente il gruppo accettato. Dimensione della request e risorse dell’host sono limiti pratici; SMTP Submission ha un proprio limite indipendente.

Jobs e destinatari sono metriche diverse

Una request con molti indirizzi resta un job logico ma contiene più destinatari. Per il volume dei destinatari usare accepted_recipients_total e postfix_queued_recipients_total; accepted_total e postfix_queued_total contano i job.

ALLEGATI

Allegati e immagini inline

API v1 resta compatibile con allegati Base64. Dopo l’accettazione, l’Engine persiste il contenuto come Blob e processa l’invio in modo asincrono.

Allegato regolare

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

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

Regole principali

filename e content_base64 sono obbligatori per ogni allegato. Un allegato inline richiede cid valido e corpo HTML. I CID duplicati nello stesso messaggio vengono rifiutati.

AFFIDABILITÀ

Idempotenza e campagne

idempotency_key

Usa una chiave prevedibile per evento logico. Se la stessa richiesta è già stata accettata, Ware Send può restituire il riferimento precedente con duplicate: true senza creare un nuovo lavoro.

campaign_id

Raggruppa l’attività operativa di grandi campagne e consente di seguire accettati, processati, retry e fallimenti nello snapshot dell’Engine.

campaign_report_email

Associa campaign_report_email a campaign_id per ricevere automaticamente riepilogo e report HTML dettagliato di completamento.

Idempotenza in elaborazione

Se un’altra richiesta con la stessa chiave è ancora in consolidamento, l’API può rispondere 409 Conflict. Attendi e consulta o reinvia usando la stessa chiave.

COMPLETAMENTO CAMPAGNA

Report di completamento campagna

Con campaign_report_email e campaign_id, Ware Send segue la campagna fino allo stato terminale dell’Engine e invia un riepilogo HTML stilizzato con un report HTML dettagliato allegato.

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

Regola del campo

Il campo è opzionale; se presente, campaign_id è obbligatorio. Lo stesso campaign_id non può cambiare silenziosamente il destinatario mentre esiste lo stato; usare un ID unico per campagna logica.

Quando viene emesso

Quando tutti i job accettati sono POSTFIX_QUEUED o errori terminali Engine e non arrivano nuovi job durante il quiet period configurato (60 s predefiniti). Lavoro successivo può produrre una nuova revisione.

Cosa certifica

Certifica completamento Ware Send e handoff locale a Postfix, Queue-ID incluso se disponibile. Non è una ricevuta inbox; delivery remoto, defer e bounce richiedono evidenza MTA/DSN.

Cosa riceve il cliente

Il corpo e-mail contiene un riepilogo; l’HTML allegato dettaglia campagna/tenant, job, destinatari, byte, handoff Postfix, errori, retry, Queue-ID, distribuzione per dominio e revisione. Nessun segreto o corpo messaggio.

OSSERVABILITÀ

Stato del messaggio e del motore

Gli endpoint seguenti consentono di osservare l’esecuzione senza accedere direttamente alla VPS.

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

Restituisce l’ultimo stato noto del messaggio indicato.

Esempio

{
  "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 ampio dell’Engine: backlog, worker, tassi di ingresso e uscita, risorse, coda Postfix, stato adattivo, attività recente e campagne.

GET/api/v1/engine/activityBearer

Vista ridotta per monitoraggio frequente: stato adattivo, pendenti, lavori attivi, eventi recenti e throughput.

GET/api/v1/engine/analyticsBearer

Serie temporali e aggregati operativi per throughput, coda, risorse, scheduler, domini e campagne.

ACCEPTEDQUEUEDMATERIALIZINGPOSTFIX_QUEUED

API v1 segue con precisione la responsabilità di Ware Send fino all’accettazione da parte di Postfix. Conferma finale per destinatario, DSN/bounce e stati di consegna remota saranno documentati quando faranno parte del contratto pubblico.

HTTP

Risposte ed errori

HTTP	Significato	Trattamento consigliato
202	Messaggio accettato e persistito.	Conserva message_id e queue_id se devi seguire l’elaborazione.
200	Query riuscita o invio idempotente già accettato.	In caso di duplicato, osserva duplicate: true.
400	JSON o campi non validi.	Correggi il payload. Anche i campi sconosciuti vengono rifiutati.
401	Credenziale assente, non valida o revocata.	Controlla il Bearer token configurato nell’applicazione.
403	Installazione senza licenza operativa.	Contatta il responsabile dell’installazione Ware Send.
409	La chiave di idempotenza è già in elaborazione.	Attendi e riprova usando la stessa chiave.
503	Coda non disponibile o backpressure temporaneo.	Rispetta Retry-After quando presente e riprova con backoff.

Errore di autenticazione

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

SISTEMI LEGACY

SMTP Submission

Per i sistemi legacy che non possono usare un’API HTTP, Ware Send offre SMTP Submission autenticato. SMTP entra nello stesso motore, coda, scheduler, worker e Postfix usati dall’API; non esiste una pipeline di consegna separata.

Disponibile in Engine 1.0.0

SMTP Submission è solo ingresso autenticato per applicazioni. Non è MX inbound, mailbox, POP3, IMAP o webmail; la porta 25 resta nel ruolo MTA/Postfix.

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

Usa l’FQDN dell’installazione con porta 587 + STARTTLS oppure porta 465 + TLS implicito. L’autenticazione è obbligatoria e usa una password SMTP globale dell’installazione, separata dall’API. L’indirizzo canonico derivato dal dominio del cliente (ad esempio, azienda@azienda.com) è solo l’identità predefinita: la stessa password può autenticare qualsiasi indirizzo completo di quel dominio, come contatto@azienda.com, amministrazione@azienda.com o nfe@azienda.com. L’alias breve canonico (azienda) resta disponibile solo per AUTH. Gli altri domini vengono rifiutati e MAIL FROM resta soggetto al dominio mittente autorizzato. Il Bearer token dell’API non autentica SMTP.

Server	`mail.seudominio.com.br`
Porta	`587` / `465`
Sicurezza	`STARTTLS` / `implicit TLS`
Autenticazione	`AUTH PLAIN` / `AUTH LOGIN`
Utente	`azienda@azienda.com`
Password	Password SMTP dedicata consegnata durante installazione o rotazione; non usare il Bearer token ws_live_ dell’API.

TLS è obbligatorio su entrambe le porte

Sulla porta 587, connettiti in SMTP e negozia STARTTLS prima di AUTH. Sulla porta 465, TLS inizia immediatamente all’apertura della connessione. Ware Send non accetta autenticazione SMTP senza cifratura.

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

Cosa significa 250?

Dopo la fine di DATA, Ware Send risponde 250 solo dopo aver persistito il lavoro nella coda durevole. Significa responsabilità assunta, equivalente a HTTP 202 Accepted; non significa consegna finale al destinatario.

Limiti e destinatari

SMTP usa gli stessi limiti di dimensione e destinatari configurati nell’Engine. Consulta GET /api/v1/info. Sono supportati più RCPT TO e il client può riutilizzare una sessione per più messaggi.

BCC e MIME

Il contenuto RFC 5322/MIME viene preservato. I destinatari nascosti devono essere nell’envelope RCPT TO; se un client legacy invia anche Bcc o Resent-Bcc negli header, Ware Send li rimuove prima della consegna per evitare esposizione.

Metadati opzionali

I client SMTP possono inviare X-WareSend-Tenant e X-WareSend-Campaign-ID per associare il messaggio a un contesto operativo e a una campagna.

Idempotenza SMTP

La semantica idempotency_key dell’API non è disponibile in SMTP 1.0.0. Se la connessione cade dopo DATA ma prima che il client riceva 250, l’accettazione può essere ambigua; non assumere deduplicazione automatica tramite Message-ID.

Stesso dataplane dell’API

Dopo l’ammissione, API e SMTP usano la stessa coda e lo stesso percorso di consegna. Non esiste un limite di egress specifico per SMTP. Il throughput numerico dipende dai benchmark dell’installazione e dal comportamento del client SMTP.

GET/api/v1/infoBearer

GET /api/v1/info indica se SMTP Submission è abilitato, host, utente predefinito, auth_domain, username_policy, se è configurata una password, 587/STARTTLS, 465/TLS implicito e meccanismi AUTH.

Scoprire la configurazione

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

Integrazione semplice. Operazione controllata dall’Engine.

L’applicazione invia il messaggio; Ware Send assume persistenza, coda, controllo adattivo e consegna all’MTA in base alla capacità dell’infrastruttura.

Torna a Ware Send