Zum Hauptinhalt springen
CaptainDNS
✦NEU·Status-Pages, verknüpft mit Ihren Monitors. White-Label, eigene Domain, RSS, Abonnenten.Live-Demo ansehen

Changelog der Public API

Diese Seite listet die wichtigsten Änderungen der CaptainDNS Public API. Nicht brechende Ergänzungen (neue Endpunkte, neue optionale Felder) werden hier ohne formelle Ankündigung dokumentiert. Breaking Changes werden mindestens 30 Tage vor dem Deployment angekündigt, hier und per E-Mail an aktive Schlüsselinhaber.

Versionierungsregeln

  • Rückwärtskompatibilität: das Hinzufügen optionaler Felder und neuer Endpunkte bricht keine bestehenden Clients.
  • Deprecations: ein abgekündigtes Feld oder ein abgekündigter Endpunkt bleibt mindestens 6 Monate nach der Ankündigung funktionsfähig.
  • Brüche: Breaking Changes werden 30 Tage im Voraus angekündigt und unter einer neuen versionierten URL (z. B. /public/v2/*) deployt. Die V1-URL bleibt während der Migrationsperiode erreichbar.
  • Versionsidentifikator: die OpenAPI-Spezifikation trägt eine eigene Versionsnummer (info.version). Die Major-Nummer folgt der versionierten URL, die Minor-Nummer folgt den rückwärtskompatiblen Ergänzungen.

Version 0.3.1 - 2026-05-19

Hinzugefügt

  • POST /public/v1/dmarc/validate: Antwort jetzt mit Scoring und Empfehlungen angereichert. Neue optionale Felder: state, score, score_band, verdict_headline, verdict_sub, score_factors, score_breakdown, recommendations, passed_checks, parsed_tags. Der bestehende Vertrag (DMARCAnalysis auf Root-Ebene) bleibt strikt erhalten. Kosten unverändert (1 Credit), Scope unverändert (mail:read).

Version 0.3.0 - 2026-04-14

Geändert

  • Webhook-Payload: jetzt mit schema_version: "2". Neue Felder event_id, delivery_id, attempt. User-Agent ist jetzt CaptainDNS-Webhook/2.0.
  • Neue Header bei jedem POST: X-CaptainDNS-Event-ID, X-CaptainDNS-Delivery-ID, X-CaptainDNS-Attempt (Format n/6), X-CaptainDNS-Event-Type. Die bestehenden Header X-CaptainDNS-Signature und X-CaptainDNS-Timestamp bleiben unverändert.
  • Wiederholungsstrategie: wenn dein Endpoint 5xx, 408, 429 oder einen Timeout/Netzwerkfehler zurückgibt, werden 6 Versuche mit Backoff 10s, 1min, 10min, 1h, 6h, 24h durchgeführt. Andere 4xx-Antworten gehen sofort in failed_permanent ohne Wiederholung.
  • Stabile event_id über alle Versuche und manuelle Wiederholungen: empfohlener Deduplizierungsschlüssel auf Empfängerseite.

Version 0.2.0 - 2026-04-09

Hinzugefügt

  • 51 öffentliche Endpunkte unter /public/v1/* für DNS, Mail, Web und Text:
    • DNS: resolve, resolve/propagation, dnssec/check, ip/whois, ip/nslookup, ip/netmask, rdap/lookup, domain/dns-check.
    • Mail: spf/lookup, spf/validate, dkim/lookup, dkim/validate, dmarc/lookup, dmarc/validate, dmarc/generate, dmarcbis/check, dmarcbis/migrate, dmarc/report/analyze, bimi/lookup, bimi/validate, bimi/logo/lookup, mta-sts/lookup, tls-rpt/lookup, dane/lookup, blacklist/ip, smtp/check, mail/header-audit, mail/header-analyze, mail/domain-check, deliverability/score, certificates/csr/parse, certificats/bimi/parse, certificats/bimi/lookup.
    • Web: url/check, page/crawl-check, phishing/check.
    • Text: text/lower, text/upper, text/stats, text/slug, text/base64/encode, text/base64/decode, text/password/generate, text/urlencode, text/urldecode, text/json/format, text/json/to-yaml, text/yaml/format, text/yaml/to-json, text/hash, text/regex/test.
  • Verwaltung von API-Schlüsseln über das CaptainDNS-Dashboard: Auflisten, Erstellen, Widerrufen, Rotieren und Usage-Abfrage.
  • OpenAPI-Schema PublicAPIError mit 10 kanonischen Codes für alle Fehler der Public API.
  • Stripe-Style Idempotency-Key-Header, 24-Stunden-Replay, 409 IDEMPOTENCY_CONFLICT bei abweichendem Body.
  • Header X-Credits-Limit/Remaining/Consumed bei jeder erfolgreichen Antwort.
  • Header RateLimit-Policy, X-RateLimit-Limit, X-RateLimit-Remaining (Letzteres wird nur bei einer 429-Ablehnung gesetzt).
  • Header X-Request-Id bei jeder Antwort zur Erleichterung des Supports.
  • 5 Abrechnungspläne: Free, Starter, Pro, Business, Enterprise mit Kontingenten und Overage pro Tier.
  • Opt-in-Überschreitungsabrechnung mit konfigurierbarem monatlichem Budgetlimit im Dashboard.
  • Notification Channels (Webhooks, Slack) im Profil-Dashboard, mit optionaler HMAC-SHA256-Signatur und 22 Ereignistypen. Siehe die dedizierte Seite.

In V1 nicht enthalten

  • Per Schlüssel signierte Public-API-Webhooks (Tabelle webhook_endpoints), um Konto-Ereignisse an deine Systeme zu pushen.

Auf dem Laufenden bleiben

  • CaptainDNS-Blog: wichtige Releases werden in eigenen Beiträgen auf captaindns.com/de/blog veröffentlicht.
  • E-Mail: aktive Schlüsselinhaber erhalten eine automatische Benachrichtigung bei jedem Breaking Change.
  • Diese Seite: jede Ergänzung oder Korrektur wird hier chronologisch rückwärts festgehalten.
  • OpenAPI-Spezifikation: das Feld info.version wird bei jedem Release hochgezählt. Die Überwachung dieses Wertes ermöglicht automatische Neugenerierungen deiner SDKs.

Nächster Schritt: zurück zum Quickstart, um mit der Integration zu beginnen, oder die OpenAPI-Referenz für alle Schemas im Detail erkunden.