Owlat Docs

Öffentliche Endpunkte

Diese Routen sind öffentlich zugänglich und werden üblicherweise über Links in E-Mails oder eingebettete Formulare aufgerufen.

Diese Routen sind öffentlich zugänglich und werden üblicherweise über Links in E-Mails oder eingebettete Formulare aufgerufen.

Health-Check

  • GET /api/v1/health

Tracking

  • GET /t/o/:emailSendId (Öffnungs-Pixel)
  • GET /t/c/:emailSendId/:encodedUrl (Klick-Weiterleitung + Tracking)

Abmeldung

  • POST /unsub/:token (One-Click-Abmeldung nach RFC 8058)
  • GET /unsub/verify/:token (Token validieren und Seitenkontext abrufen)

Präferenzcenter

  • GET /prefs/verify/:token
  • POST /prefs/update/:token

Double Opt-in für Kontakte

  • GET /confirm/doi/verify?token=...
  • POST /confirm/doi?token=...

Formularübermittlung

  • POST /forms/:formId

Kampagnen-Archiv

  • GET /archive/:token — liefert den archivierten HTML-Snapshot einer versendeten Kampagne

Öffentlicher Endpunkt für „Im Browser ansehen“-Links. Liefert den Kampagneninhalt so, wie er zum Sendezeitpunkt aussah.

200 OK — Erfolgs-Bodys verwenden den Action-Mode-Envelope { "ok": true, "data": { ... } }:

{
  "ok": true,
  "data": {
    "html": "<html>...</html>",
    "subject": "Our biggest sale of the year",
    "sentAt": 1741616400000,
    "organizationName": "Acme Inc."
  }
}

sentAt ist ein Unix-Zeitstempel in Millisekunden (eine Zahl), kein ISO-String.

404 Not Found — das Token passt zu keiner archivierten Kampagne. Fehlschläge verwenden den festgelegten Fehler-Envelope:

{
  "error": {
    "category": "not_found",
    "message": "Archive not found",
    "data": { "reason": "archive_not_found" }
  }
}

Das Archiv-Token ist pro Kampagne eindeutig und im „Im Browser ansehen“-Link der E-Mail enthalten. Archiv-Endpunkte sind rate-limitiert und CORS-fähig. Erfolgreiche Antworten setzen Cache-Control: public, max-age=3600.

  • GET /share/:token — liefert den HTML-Snapshot einer freigegebenen Vorschau einer E-Mail-Vorlage

Öffentlicher Endpunkt für ablaufende Freigabelinks, die im E-Mail-Editor erstellt wurden. Liefert den E-Mail-Inhalt so, wie er beim Erstellen des Links aussah. Links laufen nach 48 Stunden ab.

Antworten:

  • 200 OK — gültiger Freigabelink. Erfolgs-Bodys verwenden den Action-Mode-Envelope { "ok": true, "data": { ... } }:
{
  "ok": true,
  "data": {
    "html": "<html>...</html>",
    "subject": "Welcome to our product",
    "previewText": "Here's what you need to know",
    "organizationName": "Acme Inc.",
    "expiresAt": 1742486400000
  }
}

expiresAt ist ein Unix-Zeitstempel in Millisekunden (eine Zahl).

  • 404 Not Found — das Token ist ungültig oder der Link wurde widerrufen. Der festgelegte Fehler-Envelope trägt category: "not_found" und data.reason: "share_link_not_found":
{
  "error": {
    "category": "not_found",
    "message": "Share link not found",
    "data": { "reason": "share_link_not_found" }
  }
}
  • Abgelaufener Link (48-Stunden-Fenster verstrichen) — data.reason ist expired:
{
  "error": {
    "category": "not_found",
    "message": "This share link has expired",
    "data": { "reason": "expired" }
  }
}
Status bei abgelaufenem Link

Der Ablauf-Fall wird auf HTTP 404 (not_found) abgebildet, nicht auf 410 Gone — die Hülle leitet den Status aus der Fehlerkategorie ab und kennt keine Zuordnung zu 410. Unterscheiden Sie anhand von data.reason: "expired" statt anhand des Statuscodes.

Das Freigabe-Token ist eine 24 Zeichen lange Zufallszeichenkette. Endpunkte für Freigabelinks setzen Cache-Control: no-store (anders als das Archiv, das eine Stunde lang cachebar ist), da der Inhalt abläuft.

Eingehende MTA-Callbacks

Diese Routen liegen im selben HTTP-Router, sind aber Server-zu-Server-Callbacks der mitgelieferten MTA- und IMAP-Dienste und keine Browser- oder E-Mail-Link-Abläufe. Sie werden auf Transportebene authentifiziert (Shared Secret / HMAC), allgemeine Clients sollten sie daher nicht aufrufen.

  • POST /webhooks/mta-mailbox — eingehende Postbox-Zustellung (persönliche E-Mail) vom MTA. Siehe Postbox-Architektur.
  • POST /webhooks/mta-verify-credential — Verifizierung von App-Passwörtern für die SMTP-Einlieferung über den MTA und die IMAP/SMTP-Client-Authentifizierung (HMAC-signiert). Siehe Postbox-Architektur.

Der Callback für Bounce-/Beschwerde-/IP-Zustellereignisse POST /webhooks/mta ist auf der Seite Webhooks dokumentiert.

Hinweise

  • CORS ist überall dort aktiviert, wo es für browserbasierte Abläufe erforderlich ist
  • Öffentliche Endpunkte werden pro IP rate-limitiert (empfängerbezogene Token-Endpunkte wie Archiv/Freigabe/Abmeldung werden nach IP+Token geschlüsselt)
  • Tokenbasierte Endpunkte liefern für ungültige/abgelaufene Token strukturiertes JSON zurück
WeiterWebhook-Payloads