WillItInbox

Developers

API reference

Use WillItInbox API keys to validate recipients, run bulk jobs, generate deliverability test addresses, and fetch owned reports.

Authentication

Create an API key from your account page. Send it as a bearer token. Raw keys are shown once; later you will only see prefix and last characters.

Authorization: Bearer wii_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-RateLimit-Limit: 50000
X-RateLimit-Remaining: 49872
X-RateLimit-Reset: 2026-06-01T00:00:00+00:00
POST/api/v1/validate

Validate one email address. Counts as one validation credit.

curl -X POST "$WILLITINBOX_API_URL/api/v1/validate" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
{
  "email": "[email protected]",
  "status": "valid",
  "sub_status": "mailbox_exists",
  "confidence": 0.95,
  "provider": "google",
  "evidence": {
    "smtp": { "mx_host": "aspmx.l.google.com", "response_code": 250 },
    "catch_all": { "catchall_detected": false }
  }
}
POST/api/v1/validate/batch

Validate up to 100 email addresses in one JSON request.

curl -X POST "$WILLITINBOX_API_URL/api/v1/validate/batch" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["[email protected]","[email protected]"]}'
{
  "results": [...],
  "summary": {
    "total": 2,
    "valid": 1,
    "invalid": 1,
    "risky": 0,
    "catch_all": 0,
    "unknown": 0
  }
}
POST/api/v1/validate/bulk

Upload a CSV with an email column. Optional webhook_url receives a signed completion callback.

curl -X POST "$WILLITINBOX_API_URL/api/v1/validate/bulk?webhook_url=https://example.com/webhooks/willitinbox" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -F "[email protected]"
GET/api/v1/bulk/{job_id}

Poll a bulk validation job. The job is only visible to the API key owner.

{
  "job_id": "abc123",
  "status": "complete",
  "total": 1000,
  "processed": 1000,
  "valid": 812,
  "invalid": 64,
  "risky": 52,
  "catch_all": 41,
  "unknown": 31,
  "download_url": "/api/v1/bulk/abc123/download"
}
GET/api/v1/bulk/{job_id}/download

Download the enriched CSV results for a completed bulk job.

curl -L "$WILLITINBOX_API_URL/api/v1/bulk/$JOB_ID/download" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -o validation-results.csv
POST/api/v1/tests

Generate an owned deliverability test address. Counts as one deliverability test.

{
  "token": "a1b2c3d4",
  "email_address": "[email protected]",
  "instructions": "Send your test email to [email protected]..."
}
GET/api/v1/reports/{token}

Fetch a report generated by the same API key owner. Pending reports return status only.

curl "$WILLITINBOX_API_URL/api/v1/reports/a1b2c3d4" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
POST/api/v1/reports/{token}/share

Create a private share token for a completed or pending owned report. Use DELETE on the same path to revoke.

curl -X POST "$WILLITINBOX_API_URL/api/v1/reports/a1b2c3d4/share" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
GET/api/v1/reports/{token}/pdf

Download a completed report as PDF. Pending reports return report_not_ready.

curl -L "$WILLITINBOX_API_URL/api/v1/reports/a1b2c3d4/pdf" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -o willitinbox-report.pdf
GET/api/v1/usage

Return the API key owner's current plan, usage counters, limits, and recent usage events.

curl "$WILLITINBOX_API_URL/api/v1/usage" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
GET/api/v1/usage/series

Return daily API usage, validation, test, and bulk-row series for dashboards.

{
  "series": [
    { "date": "2026-05-01", "api_calls": 12, "validations": 500, "tests": 2, "bulk_rows": 450 }
  ]
}
POST/api/v1/webhooks

Create a persistent signed webhook endpoint for bulk completion and future event types.

curl -X POST "$WILLITINBOX_API_URL/api/v1/webhooks" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production","url":"https://example.com/webhooks/willitinbox","events":["bulk.completed"]}'
GET/api/v1/webhook-deliveries

List recent webhook delivery attempts, response codes, failures, and delivered timestamps.

curl "$WILLITINBOX_API_URL/api/v1/webhook-deliveries" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
POST/api/v1/webhooks/{id}/test

Send a signed test payload to a persistent webhook endpoint.

curl -X POST "$WILLITINBOX_API_URL/api/v1/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
POST/api/v1/webhook-deliveries/{id}/resend

Create a new delivery attempt from a previous persistent webhook delivery.

curl -X POST "$WILLITINBOX_API_URL/api/v1/webhook-deliveries/$DELIVERY_ID/resend" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
POST/api/v1/domains

Create a monitored domain and receive the TXT record required for ownership verification.

curl -X POST "$WILLITINBOX_API_URL/api/v1/domains" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","schedule":"daily"}'
POST/api/v1/domains/{id}/scan

Run a manual domain scan after the TXT verification token has been published.

curl -X POST "$WILLITINBOX_API_URL/api/v1/domains/$DOMAIN_ID/scan" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
POST/api/v1/dmarc/upload

Upload a DMARC aggregate XML, gzip, zip, or EML report for parsed source and alignment analytics.

curl -X POST "$WILLITINBOX_API_URL/api/v1/dmarc/upload" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -F "[email protected]"
GET/api/v1/dmarc/summary

Return aggregate DMARC volume, alignment, disposition, unknown-source, and recent-report metrics.

curl "$WILLITINBOX_API_URL/api/v1/dmarc/summary" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
GET/api/v1/dmarc/sources

List sending sources ordered by failed DMARC volume, then total volume.

curl "$WILLITINBOX_API_URL/api/v1/dmarc/sources" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
PATCH/api/v1/dmarc/sources/{source_ip}

Label a known sending source so future dashboards separate approved senders from unknown traffic.

curl -X PATCH "$WILLITINBOX_API_URL/api/v1/dmarc/sources/192.0.2.10" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_name":"Google Workspace","owner_name":"Ops","service_type":"workspace","unresolved":false}'
POST/api/v1/dmarc/mailboxes

Beta: store encrypted IMAP settings for mailbox-based DMARC report ingestion.

curl -X POST "$WILLITINBOX_API_URL/api/v1/dmarc/mailboxes" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_address":"[email protected]","imap_host":"imap.example.com","imap_username":"[email protected]","imap_password":"app-password"}'
POST/api/v1/dmarc/mailboxes/{id}/ingest

Beta: poll a configured DMARC mailbox and ingest XML/gzip/zip attachments through the same parsedmarc pipeline.

curl -X POST "$WILLITINBOX_API_URL/api/v1/dmarc/mailboxes/$MAILBOX_ID/ingest" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
GET/api/v1/dmarc/timeseries

Return daily DMARC total, aligned, failed, SPF-aligned, DKIM-aligned, and disposition counts.

curl "$WILLITINBOX_API_URL/api/v1/dmarc/timeseries" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
GET/api/v1/dmarc/reports/{id}/rows

Inspect normalized report rows. Optional filters include source_ip, disposition, aligned, failed, and limit.

curl "$WILLITINBOX_API_URL/api/v1/dmarc/reports/$REPORT_ID/rows?failed=true" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
GET/api/v1/dmarc/alerts

List open DMARC alerts created from monitored-domain aggregate report ingestion.

curl "$WILLITINBOX_API_URL/api/v1/dmarc/alerts" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
PATCH/api/v1/dmarc/alerts/{id}

Acknowledge or resolve a DMARC alert.

curl -X PATCH "$WILLITINBOX_API_URL/api/v1/dmarc/alerts/$ALERT_ID" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved"}'
POST/api/v1/notification-channels

Beta: create a webhook, Slack, Discord, or email destination record for alert routing.

curl -X POST "$WILLITINBOX_API_URL/api/v1/notification-channels" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"DMARC alerts","channel_type":"slack","target":"https://hooks.slack.com/services/..."}'
POST/api/v1/placement-tests

Beta: create a diagnostic inbox placement test from configured seed inboxes. This does not perform warmup or engagement.

curl -X POST "$WILLITINBOX_API_URL/api/v1/placement-tests" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"May newsletter"}'
POST/api/v1/seed-inboxes

Beta admin: add an encrypted IMAP seed inbox for diagnostic inbox placement tests.

curl -X POST "$WILLITINBOX_API_URL/api/v1/seed-inboxes" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gmail","email_address":"[email protected]","imap_host":"imap.gmail.com","imap_username":"[email protected]","imap_password":"app-password"}'
POST/api/v1/placement-tests/{id}/poll

Beta: poll configured seed inboxes over IMAP and classify inbox, spam, promotions/updates, missing, or delayed.

curl -X POST "$WILLITINBOX_API_URL/api/v1/placement-tests/$TEST_ID/poll" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"
GET/api/v1/workspaces

Internal beta: return workspace and client/project foundations for agency-style account separation.

curl "$WILLITINBOX_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $WILLITINBOX_API_KEY"

Client examples

// Node.js
const baseUrl = process.env.WILLITINBOX_API_URL;
const apiKey = process.env.WILLITINBOX_API_KEY;

const res = await fetch(baseUrl + "/api/v1/validate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "[email protected]" }),
});
const result = await res.json();
# Python
import os, requests

res = requests.post(
    f"{os.environ['WILLITINBOX_API_URL']}/api/v1/validate",
    headers={"Authorization": f"Bearer {os.environ['WILLITINBOX_API_KEY']}"},
    json={"email": "[email protected]"},
    timeout=30,
)
result = res.json()

Webhooks

Bulk jobs POST completion payloads to persistent webhook endpoints and optional ad-hoc webhook URLs. WillItInbox sends X-WillItInbox-Signature using HMAC SHA-256 over the raw JSON body.

X-WillItInbox-Event: bulk.completed
X-WillItInbox-Signature: sha256=<hex-hmac>

Error format

API errors include a stable code for client handling.

{
  "detail": {
    "code": "quota_exceeded",
    "message": "Monthly quota exceeded.",
    "feature": "validations"
  }
}