API Documentation

Verify a single email

curl "https://emailguard.dev/api/v1/verify?email=test@example.com"   -H "X-API-Key: eg_your_key_here"

JavaScript (fetch)

Works in Node 18+ and the browser — no SDK to install.

const res = await fetch(
  "https://emailguard.dev/api/v1/verify?email=test@example.com",
  { headers: { "X-API-Key": "eg_your_key_here" } }
);
const result = await res.json();
console.log(result.status, result.score); // "deliverable" 85

Python (requests)

import requests

res = requests.get(
    "https://emailguard.dev/api/v1/verify",
    params={"email": "test@example.com"},
    headers={"X-API-Key": "eg_your_key_here"},
)
result = res.json()
print(result["status"], result["score"])  # deliverable 85

Bulk verify — JSON array (Premium+)

curl -X POST "https://emailguard.dev/api/v1/verify"   -H "X-API-Key: eg_your_key_here"   -H "Content-Type: application/json"   -d '{"emails":["a@example.com","b@acme.io"]}'

JavaScript:

const res = await fetch("https://emailguard.dev/api/v1/verify", {
  method: "POST",
  headers: {
    "X-API-Key": "eg_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ emails: ["a@example.com", "b@acme.io"] }),
});
const { count, results } = await res.json();

Python:

import requests

res = requests.post(
    "https://emailguard.dev/api/v1/verify",
    json={"emails": ["a@example.com", "b@acme.io"]},
    headers={"X-API-Key": "eg_your_key_here"},
)
data = res.json()  # {"count": 2, "results": [...]}

Bulk verify — CSV upload (Pro+)

Upload a CSV (any column layout). We scan every cell, de-duplicate the addresses and grade up to 1,000 per call.

# multipart file upload
curl -X POST "https://emailguard.dev/api/v1/verify/csv"   -H "X-API-Key: eg_your_key_here"   -F "file=@contacts.csv"

# or stream a raw CSV body
curl -X POST "https://emailguard.dev/api/v1/verify/csv"   -H "X-API-Key: eg_your_key_here"   -H "Content-Type: text/csv"   --data-binary @contacts.csv

Response

{
  "email": "test@example.com",
  "valid": true,
  "score": 85,
  "status": "deliverable",
  "checks": {
    "syntax": true, "mx": true, "spf": true,
    "dmarc": true, "disposable": false,
    "role": false, "free": false, "catchAll": false
  },
  "mxRecords": ["mx1.example.com"],
  "reason": "Looks deliverable"
}

catchAll flags domains that accept mail for any address (forwarders / accept-all servers) — inferred from MX provider signals, so a valid result there cannot guarantee the specific mailbox exists.status is the deliverability bucket: deliverable (score ≥ 80), risky (50–79) or undeliverable(< 50).

Export your request history

Pull your recent API calls as JSON (default) or CSV for spreadsheets.

curl "https://emailguard.dev/api/dashboard/requests?format=csv"   -H "X-API-Key: eg_your_key_here" -o requests.csv

Webhook callbacks (Premium+)

Register an HTTPS endpoint to receive signed event callbacks. The signing secret is returned once on creation — store it.

# Register a webhook
curl -X POST "https://emailguard.dev/api/v1/webhooks"   -H "X-API-Key: eg_your_key_here"   -H "Content-Type: application/json"   -d '{"url":"https://your-app.com/hooks/emailguard"}'

# List / delete
curl "https://emailguard.dev/api/v1/webhooks" -H "X-API-Key: eg_your_key_here"
curl -X DELETE "https://emailguard.dev/api/v1/webhooks?id=wh_xxxx"   -H "X-API-Key: eg_your_key_here"

Each delivery is a POST signed with HMAC-SHA256. Verify it against the headers X-EmailGuard-Timestamp and X-EmailGuard-Signature (sha256=…) over the string {timestamp}.{rawBody}:

import hmac, hashlib

def verify(secret, timestamp, raw_body, signature_header):
    mac = hmac.new(
        secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={mac}", signature_header)

Embeddable badge

Drop a live SVG badge on your site or README. No key required — it exposes no account data.

<img src="https://emailguard.dev/api/badge" alt="Verified by EmailGuard" />

<!-- optional verification count -->
<img src="https://emailguard.dev/api/badge?count=12500" alt="12.5k verified" />

Versioning & status

The stable major is v1, served under /api/v1. Every response includes X-API-Version and a Deprecation header (false while current). Breaking changes ship under a new path prefix (/api/v2) — v1 keeps working. If a version is ever retired we advertise a Sunset date (RFC 8594) on its responses ahead of time.

A public, no-auth liveness endpoint is available for uptime monitors:

curl "https://emailguard.dev/api/health"
# {"status":"ok","service":"emailguard","apiVersion":"v1","version":"<sha>","timestamp":"..."}