HTTP API Reference

Base URL: http://localhost:8080 (default port)

`GET /v1/health`

Health check endpoint.

Response:

{"status": "ok"}

`GET /v1/check`

Perform DNS health check on a domain.

Parameters:

Parameter	Required	Description
`domain`	Yes	Domain to check

Example:

curl "http://localhost:8080/v1/check?domain=gmail.com"

Response:

{
  "domain": "gmail.com",
  "score": 95,
  "spf": {
    "valid": true,
    "record": "v=spf1 redirect=_spf.google.com"
  },
  "dkim": {
    "valid": true,
    "selector": "google",
    "domain": "gmail.com"
  },
  "dmarc": {
    "valid": true,
    "record": "v=DMARC1; p=reject; sp=reject",
    "policy": "reject"
  },
  "mx": [
    {"host": "gmail-smtp-in.l.google.com", "priority": 5},
    {"host": "alt1.gmail-smtp-in.l.google.com", "priority": 10}
  ],
  "ptr": {
    "valid": false,
    "reason": "no PTR record found"
  }
}

`GET /v1/verify`

SMTP mailbox verification.

Parameters:

Parameter	Required	Description
`email`	Yes	Email address to verify
`bind_ip`	No	Source IP for SMTP connection
`timeout`	No	Timeout (e.g., `30s`, `1m`)
`disposable`	No	`true` to check disposable email providers
`pool`	No	`true` to use IP pool with auto-failover

Example:

curl "http://localhost:8080/v1/verify?email=user@example.com&bind_ip=1.2.3.4"

Response:

{
  "email": "user@example.com",
  "result": "accepted",
  "code": 250,
  "message": "2.1.5 OK",
  "mx_server": "mail.example.com",
  "disposable": false,
  "ip_used": "1.2.3.4"
}

`GET /v1/blacklist`

Check an IP against 29 RBL blacklists.

Parameters:

Parameter	Required	Description
`ip`	Yes	IP address to check

Example:

curl "http://localhost:8080/v1/blacklist?ip=1.2.3.4"

Response:

{
  "ip": "1.2.3.4",
  "total": 29,
  "listed": 0,
  "results": [
    {"blacklist": "Spamhaus ZEN", "listed": false},
    {"blacklist": "SpamCop", "listed": false},
    {"blacklist": "Barracuda", "listed": false}
  ]
}

`GET /v1/report`

Full diagnostic report for a domain.

Parameters:

Parameter	Required	Description
`domain`	Yes	Domain to report

Response:

Combines the output of /v1/check and /v1/blacklist for all MX server IPs.

Peer Endpoints (Multi-Node)

Endpoint	Method	Description
`/v1/peer/register`	POST	Register a peer node
`/v1/peer/peers`	GET	List all registered peers
`/v1/peer/heartbeat`	POST	Heartbeat keepalive
`/v1/peer/geo`	GET	GeoIP lookup (`?ip=1.2.3.4`)

CLI Reference