Documentazione della API pubblica CaptainDNS

Vuoi interrogare le diagnosi DNS, mail è web di CaptainDNS dal tuo stack? L'API pubblica espone 18 endpoint selezionati, protetti da chiave è misurati in crediti. Questa guida ti porta dal primo curl a un'integrazione pronta per la produzione.

Cosa ottieni

• 18 endpoint accuratamente selezionati: risoluzione DNS, verifica SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT, blacklist, SMTP, deliverability, URL check, page crawl è rilevamento phishing.
• Chiavi API nei formati cdns_live_... e cdns_test_..., ciascuna con scope è ruotabili senza interruzione.
• Token bucket per chiave è limitatore per IP per attutire i picchi.
• Idempotenza in stile Stripe, finestra di 24 ore, riproduce la risposta memorizzata.
• Tariffazione in crediti: un lookup semplice costa 1 credito, un deliverability score ne costa 25.
• Overage fatturato a inizio mese per i piani a pagamento che superano la loro quota.

URL base

https://api.captaindns.com/public/v1

Tutte le rotte sono HTTPS. Il sito www.captaindns.com ospita la dashboard è il portale di documentazione, api.captaindns.com ospita l'API vera è propria.

Avvio rapido in cinque minuti

Creare una chiave API

Accedi alla dashboard CaptainDNS, apri Account > API keys, clicca sul pulsante per una nuova chiave. Scegli un nome, un ambiente (live o test), gli scope necessari è una data di scadenza opzionale. Il segreto in chiaro viene mostrato una sola volta: copialo nel tuo gestore di segreti prima di chiudere il dialogo.

Lanciare la prima richiesta

curl -X POST https://api.captaindns.com/public/v1/resolve \
  -H "Authorization: Bearer cdns_live_a3f2XK7mN9QrVtZ4yP1sH6eL8cF2dB5aR3gW7kJxM" \
  -H "Content-Type: application/json" \
  -d '{"qname":"captaindns.com","qtype":"A"}'

La risposta contiene i record richiesti è tre famiglie di header che guidano il client:

RateLimit-Policy: "default";q=60;w=60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-Credits-Limit: 50000
X-Credits-Remaining: 49998
X-Credits-Consumed: 1
X-Request-Id: req_a1b2c3d4

Gestire gli errori

Tutti gli errori condividono lo stesso involucro JSON:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota reached for the current plan",
  "details": {
    "tier": "starter",
    "limit": 50000,
    "current": 50000
  },
  "request_id": "req_a1b2c3d4"
}

I codici più frequenti sono descritti nella guida agli errori. Presta particolare attenzione a RATE_LIMITED (429) e QUOTA_EXCEEDED (403): il primo si risolve con un backoff, il secondo richiede un cambio di piano o l'attesa della fine del mese.

Automatizzare con l'idempotenza

Tutte le richieste POST accettano un header Idempotency-Key. Ogni replay identico nelle 24 ore restituisce la risposta originale, con X-Idempotent-Replay: true. Perfetto per i retry di rete sul client. Consulta la guida all'idempotenza.

Mappa della documentazione

• Autenticazione: formato della chiave, allowlist IP, rotazione, revoca.
• Scope: dettaglio di dns:read, mail:read, mail:write, web:read.
• Crediti: costo per endpoint, quote per piano, fatturazione overage.
• Rate limiting: token bucket per chiave, backoff raccomandato.
• Idempotenza: replay POST, TTL 24 h, hash del body.
• Errori: tabella completa dei codici è azioni correttive.
• Riferimento OpenAPI: specifica interattiva di ogni endpoint.
• Webhook: in arrivo con la V2.
• Changelog: storico delle versioni è breaking change.

Principi operativi

Mai chiamate dal browser: il tuo frontend utente chiama il tuo backend, che a sua volta chiama la API pubblica CaptainDNS. E una regola di sicurezza: il segreto non deve mai uscire dal tuo server.

Osservabilita al primo posto: l'header X-Request-Id viene restituito a ogni risposta. Viene loggato lato CaptainDNS è può essere usato per aprire un ticket di supporto.

Strumenti CaptainDNS correlati

Gli stessi diagnostici sono disponibili come strumenti web, utili per verificare a mano l'output della tua integrazione:

• DMARC checker per confrontare visivamente la policy rilevata.
• SPF checker con validazione del numero di lookup.
• DNSSEC checker con tracciamento della catena dalla root.
• Blacklist check aggregato su oltre 90 RBL.

Pronto a programmare? Leggi autenticazione è poi rate limiting prima del primo deploy in produzione.