Ware Send Developer Documentation

SCHNELLSTART

Erster Versand

Verwenden Sie die bei der Ware-Send-Bereitstellung bereitgestellte URL und eine gültige Bearer-Anmeldeinformation.

Base URL

Die Beispiele verwenden https://mail.ihredomain.de. Ersetzen Sie sie durch den für Ihre Installation konfigurierten FQDN.

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

Was bedeutet accepted?

Ware Send hat den Auftrag validiert, in der dauerhaften Queue gespeichert und die Verantwortung für die Verarbeitung übernommen. Das bedeutet nicht, dass der Empfängerserver die Zustellung bereits bestätigt hat.

AUTHENTIFIZIERUNG

Bearer token

Geschützte Endpoints benötigen die Anmeldeinformation im HTTP-Header Authorization.

HTTP Header

Authorization: Bearer <TOKEN>

Im Backend verwenden

Geben Sie die Anmeldeinformation nicht in öffentlichem JavaScript, verteilten Anwendungen oder für Endnutzer zugänglichem Quellcode preis.

Übergabe der Zugangsdaten

Die Bearer-Zugangsdaten werden dem bei der Integration benannten technischen Verantwortlichen oder Entwickler sicher und mit einmaliger Anzeige bereitgestellt.

Neuen Token benötigt?

Fordern Sie neue Zugangsdaten bei DB Ware oder beim autorisierten Verantwortlichen der Ware-Send-Installation an. Der bisherige Token kann nicht wiederhergestellt werden; nach der Umstellung sollte die alte Zugangsdaten widerrufen werden.

ENDPOINTS

Schnellreferenz

POST/api/v1/send

Empfängt und persistiert eine Nachricht zur asynchronen Verarbeitung.

Bearer

GET/api/v1/info

Fähigkeiten und Limits der installierten Engine.

Bearer

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

Fragt den bekannten Status einer akzeptierten Nachricht ab.

Bearer

GET/api/v1/engine/status

Operativer Snapshot von Engine, Queue, Ressourcen und Kampagnen.

Bearer

GET/api/v1/engine/activity

Aktuelle Aktivität und jüngste Engine-Ereignisse.

Bearer

GET/api/v1/engine/analytics

Zeitreihen und operative Aggregate für Durchsatz, Queue, Ressourcen, Scheduler, Domains und Kampagnen.

Bearer

GET/health

Grundzustand des Dienstes.

Öffentlich

GET/ready

Operative Bereitschaft von Lizenz, Queue, Postfix und DKIM.

Öffentlich

NACHRICHT SENDEN

Nachricht senden

Senden Sie UTF-8-JSON an /api/v1/send. Die API validiert, persistiert und antwortet asynchron.

POST/api/v1/sendBearer

PAYLOAD

Sendefelder

Die folgenden Felder bilden den aktuellen öffentlichen API-v1-Vertrag.

Feld	Typ	Pflicht	Beschreibung
`from_name`	string	Nein	Anzeigename des Absenders.
`from_email`	string	Ja	Autorisierte Absenderadresse für die konfigurierte Domain.
`to`	string \| array	Nein	Hauptempfänger. Akzeptiert eine E-Mail-Adresse als String oder mehrere Adressen als Array.
`cc`	string \| array	Nein	CC-Empfänger. Akzeptiert String oder Array.
`bcc`	string \| array	Nein	BCC-Empfänger. Akzeptiert String oder Array und wird niemals in einem sichtbaren Header offengelegt.
`to_visible`	boolean	Nein	Steuert die Sichtbarkeit der Empfänger. Optional; Standard false. false isoliert jeden Empfänger; true erlaubt gemeinsame To/Cc-Header. Bcc wird niemals angezeigt.
`reply_to`	string	Nein	Optionale Reply-To-Adresse.
`subject`	string	Ja	Betreff der Nachricht.
`html`	string	Nein	HTML-Inhalt.
`text`	string	Nein	Nur-Text-Inhalt.
`tenant`	string	Nein	Logische Kennung der Anwendung, des Kunden oder Integrationskontexts.
`campaign_id`	string	Nein	Logische Kennung zum Gruppieren der operativen Aktivität einer Kampagne.
`campaign_report_email`	string	Nein	Optionale E-Mail-Adresse für den Kampagnenabschlussbericht. Erfordert campaign_id und bleibt an diese Kampagne gebunden, solange ihr Status existiert.
`idempotency_key`	string	Nein	Stabiler Schlüssel zur Vermeidung versehentlicher erneuter Übermittlung derselben Anfrage.
`headers`	object	Nein	Zusätzliche nicht reservierte Header. Strukturelle E-Mail-Header werden von der Engine kontrolliert.
`attachments`	array	Nein	Normale oder Inline/CID-Anhänge.

* Mindestens ein Empfänger unter to, cc und bcc sowie mindestens ein Inhalt unter html und text ist erforderlich. In der HTTP API akzeptieren to/cc/bcc String oder Array und es gibt kein anwendungsseitiges logisches Empfängerlimit; Request-Größe und Host-Ressourcen bleiben praktische Grenzen. SMTP Submission besitzt ein unabhängiges Limit, das über GET /api/v1/info gemeldet wird.

EMPFÄNGER-DATENSCHUTZ

Standardmäßig privat bei mehreren Empfängern

Empfängerlisten in der API sind Routing-Eingaben für die Engine. Viele Adressen in einem Payload berechtigen Ware Send nicht dazu, diese Liste gegenüber Empfängern offenzulegen.

Default · to_visible=false

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

Sicherer Standard: to_visible = false

Wenn to_visible fehlt oder false ist, führt die Engine den Fan-out intern durch und erzeugt pro Empfänger eine eigene Zustellung. Die empfangene Nachricht zeigt in To: nur diesen Empfänger; alle anderen to-, cc- und bcc-Adressen bleiben verborgen.

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

Sichtbarkeit nur mit ausdrücklichem Opt-in

Nur to_visible:true erlaubt, die To- und Cc-Listen des Requests gemeinsam in sichtbaren Headern anzuzeigen. Verwenden Sie diesen Modus nur, wenn alle Teilnehmer die anderen Adressen kennen dürfen.

Bcc ist niemals sichtbar

Bcc bleibt ausschließlich im Envelope. Die Engine gibt niemals einen sichtbaren Bcc-Header aus, auch nicht bei to_visible=true.

Fan-out ist Aufgabe der Engine

Die HTTP API hat kein anwendungsseitiges logisches Empfängerlimit. Die Engine teilt die akzeptierte Menge intern auf und verarbeitet sie. Request-Größe und Host-Ressourcen sind praktische Grenzen; SMTP Submission besitzt ein eigenes unabhängiges Limit.

Jobs und Empfänger sind unterschiedliche Metriken

Ein Request mit vielen Adressen ist weiterhin ein logischer Job, enthält aber mehrere Empfänger. Für Empfängervolumen verwenden Sie accepted_recipients_total und postfix_queued_recipients_total; accepted_total und postfix_queued_total zählen Jobs.

ANHÄNGE

Anhänge und Inline-Bilder

API v1 bleibt mit Base64-Anhängen kompatibel. Nach der Annahme persistiert die Engine den Inhalt als Blob und verarbeitet den Versand asynchron.

Normaler Anhang

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

Inline-Bild / 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
  }]
}

Hauptregeln

filename und content_base64 sind pro Anhang erforderlich. Inline-Anhänge benötigen eine gültige cid und einen HTML-Inhalt. Doppelte CIDs in derselben Nachricht werden abgewiesen.

ZUVERLÄSSIGKEIT

Idempotenz und Kampagnen

idempotency_key

Verwenden Sie pro logischem Ereignis einen vorhersehbaren Schlüssel. Wurde dieselbe Anfrage bereits angenommen, kann Ware Send die vorherige Referenz mit duplicate: true zurückgeben, ohne einen neuen Auftrag zu erzeugen.

campaign_id

Gruppiert operative Aktivität großer Kampagnen und ermöglicht die Beobachtung akzeptierter, verarbeiteter, wiederholter und fehlgeschlagener Vorgänge im Engine-Snapshot.

campaign_report_email

campaign_report_email mit campaign_id verknüpfen, um automatisch Abschlusszusammenfassung und detaillierten HTML-Bericht zu erhalten.

Idempotenz in Verarbeitung

Wird eine andere Anfrage mit demselben Schlüssel noch konsolidiert, kann die API 409 Conflict zurückgeben. Warten Sie und fragen Sie erneut ab oder senden Sie mit demselben Schlüssel erneut.

KAMPAGNENABSCHLUSS

Kampagnenabschlussbericht

Mit campaign_report_email und campaign_id verfolgt Ware Send die Kampagne bis zum terminalen Engine-Status und sendet eine formatierte HTML-Zusammenfassung plus einen detaillierten HTML-Anhang.

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

Feldregel

Das Feld ist optional; bei Angabe ist campaign_id erforderlich. Ein bestehender campaign_id darf das Berichtsziel nicht still ändern. Für jede logische Kampagne einen eindeutigen ID verwenden.

Wann der Bericht erstellt wird

Wenn alle akzeptierten Jobs POSTFIX_QUEUED oder terminale Engine-Fehler sind und während der konfigurierten Ruhezeit (Standard 60 s) keine neuen Jobs angenommen wurden. Spätere Jobs können eine neue Revision erzeugen.

Was der Bericht bestätigt

Bestätigt Ware-Send-Abschluss und lokalen Postfix-Handoff inklusive Queue-ID, soweit vorhanden. Kein Inbox-Nachweis; Remote-Zustellung, Defer und Bounce benötigen MTA/DSN-Evidenz.

Was der Kunde erhält

E-Mail mit visueller Zusammenfassung plus HTML-Anhang mit Kampagne/Tenant, Jobs, Empfängern, Bytes, Postfix-Handoff, Fehlern, Retries, Queue-IDs, Domain-Verteilung und Revision. Keine Secrets oder Nachrichteninhalte.

OBSERVABILITY

Nachrichten- und Engine-Status

Mit den folgenden Endpoints können Sie die Ausführung beobachten, ohne direkt auf den VPS zuzugreifen.

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

Liefert den letzten bekannten Zustand der angegebenen Nachricht.

Beispiel

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

Umfassender Engine-Snapshot: Backlog, Worker, Ein- und Ausgangsraten, Ressourcen, Postfix-Queue, adaptiver Zustand, jüngste Aktivität und Kampagnen.

GET/api/v1/engine/activityBearer

Reduzierte Ansicht für häufige Überwachung: adaptiver Zustand, ausstehende Arbeiten, aktive Jobs, jüngste Ereignisse und Throughput.

GET/api/v1/engine/analyticsBearer

Zeitreihen und operative Aggregate für Durchsatz, Queue, Ressourcen, Scheduler, Domains und Kampagnen.

ACCEPTEDQUEUEDMATERIALIZINGPOSTFIX_QUEUED

API v1 verfolgt die Verantwortung von Ware Send präzise bis zur Annahme durch Postfix. Endgültige Empfängerbestätigung, DSN/Bounce und Remote-Zustellungsstatus werden dokumentiert, sobald sie Teil des öffentlichen Vertrags sind.

HTTP

Antworten und Fehler

HTTP	Bedeutung	Empfohlene Behandlung
202	Nachricht angenommen und persistiert.	Speichern Sie message_id und queue_id, wenn Sie die Verarbeitung verfolgen müssen.
200	Erfolgreiche Abfrage oder bereits angenommener idempotenter Versand.	Bei Duplikaten auf duplicate: true achten.
400	Ungültiges JSON oder ungültige Felder.	Korrigieren Sie den Payload. Unbekannte Felder werden ebenfalls abgewiesen.
401	Anmeldeinformation fehlt, ist ungültig oder widerrufen.	Prüfen Sie den in der Anwendung konfigurierten Bearer token.
403	Installation ohne operative Lizenz.	Wenden Sie sich an die für die Ware-Send-Installation zuständige Person.
409	Idempotenzschlüssel wird bereits verarbeitet.	Warten Sie und versuchen Sie es mit demselben Schlüssel erneut.
503	Queue nicht verfügbar oder temporärer Backpressure.	Beachten Sie Retry-After, wenn vorhanden, und wiederholen Sie mit Backoff.

Authentifizierungsfehler

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

LEGACY-SYSTEME

SMTP Submission

Für Altsysteme ohne HTTP-API-Unterstützung bietet Ware Send authentifiziertes SMTP Submission. SMTP nutzt denselben Engine-, Queue-, Scheduler-, Worker- und Postfix-Pfad wie die API; es gibt keine separate Delivery-Pipeline.

Verfügbar in Engine 1.0.0

SMTP Submission ist nur authentifizierter Anwendungseingang. Es ist kein eingehender MX, keine Mailbox, kein POP3, IMAP oder Webmail; Port 25 bleibt Aufgabe von MTA/Postfix.

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

Verwenden Sie den FQDN der Installation mit Port 587 + STARTTLS oder Port 465 + implizitem TLS. Die Authentifizierung ist verpflichtend und verwendet ein installationsweit gültiges SMTP-Passwort, getrennt von der API. Die aus der Kundendomäne abgeleitete kanonische Adresse (z. B. firma@firma.com) ist nur die Standardidentität: Dasselbe Passwort kann jede vollständige Mailbox dieser Domäne authentifizieren, etwa kontakt@firma.com, buchhaltung@firma.com oder nfe@firma.com. Der kanonische Kurzalias (firma) bleibt nur für AUTH verfügbar. Andere Domänen werden abgewiesen und MAIL FROM bleibt auf die autorisierte Absenderdomäne beschränkt. API-Bearer-Token authentifizieren SMTP nicht.

Server	`mail.seudominio.com.br`
Port	`587` / `465`
Sicherheit	`STARTTLS` / `implicit TLS`
Authentifizierung	`AUTH PLAIN` / `AUTH LOGIN`
Benutzer	`firma@firma.com`
Passwort	Eigenes SMTP-Passwort, das bei Bereitstellung oder Rotation übergeben wird; verwenden Sie nicht das API-Bearer-Token ws_live_.

TLS ist auf beiden Ports verpflichtend

Auf Port 587 wird zunächst SMTP verbunden und vor AUTH STARTTLS ausgehandelt. Auf Port 465 beginnt TLS sofort beim Verbindungsaufbau. Ware Send akzeptiert keine SMTP-Authentifizierung ohne Verschlüsselung.

SMTP-Ablauf

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

Was bedeutet 250?

Nach Abschluss von DATA sendet Ware Send 250 erst, nachdem der Auftrag dauerhaft in der Queue gespeichert wurde. Das bedeutet übernommene Verantwortung, entsprechend HTTP 202 Accepted; es bedeutet nicht die endgültige Zustellung an den Empfänger.

Limits und Empfänger

SMTP verwendet dieselben Größen- und Empfängerlimits wie der Engine. Prüfen Sie GET /api/v1/info. Mehrere RCPT TO werden unterstützt und eine Sitzung kann für mehrere Nachrichten wiederverwendet werden.

BCC und MIME

RFC 5322/MIME-Inhalte bleiben erhalten. Blindempfänger müssen im RCPT-TO-Envelope stehen; sendet ein Altsystem zusätzlich Bcc oder Resent-Bcc als Header, entfernt Ware Send diese Header vor der Zustellung, um Offenlegung zu verhindern.

Optionale Metadaten

SMTP-Clients können X-WareSend-Tenant und X-WareSend-Campaign-ID senden, um eine Nachricht einem Betriebskontext und einer Kampagne zuzuordnen.

SMTP-Idempotenz

Die idempotency_key-Semantik der API steht in SMTP 1.0.0 nicht zur Verfügung. Bricht die Verbindung nach DATA, aber vor dem Empfang von 250 ab, kann die Annahme aus Client-Sicht unklar sein; keine automatische Deduplizierung per Message-ID annehmen.

Derselbe Dataplane wie die API

Nach der Annahme verwenden API und SMTP dieselbe Queue und denselben Zustellpfad. Es gibt kein SMTP-spezifisches Egress-Limit. Numerischer Throughput hängt von Installationsbenchmarks und Client-Verhalten ab.

GET/api/v1/infoBearer

GET /api/v1/info zeigt an, ob SMTP Submission aktiviert ist, außerdem Host, Standardbenutzer, auth_domain, username_policy, ob ein Passwort konfiguriert ist, 587/STARTTLS, 465/implizites TLS und die AUTH-Mechanismen.

Konfiguration ermitteln

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

Einfache Integration. Betrieb durch die Engine gesteuert.

Die Anwendung übermittelt die Nachricht; Ware Send übernimmt Persistenz, Queueing, adaptive Steuerung und Übergabe an den MTA entsprechend der Infrastrukturkapazität.

Zurück zu Ware Send