Docs

Node, Python, and CLI helpers for email testing workflows.

Use dependency-light Node and Python clients plus CLI commands for validation, sandbox capture, report access, webhook verification, and CI checks.

Open developer guideOpen email sandbox

Current SDK shape

The SDKs are package-ready but intentionally dependency-light. Treat them as starter clients for common workflows, including sandbox projects, captured messages, webhook verification, wait helpers, and CI threshold checks.

  • Node client: sdks/node/index.mjs using fetch.
  • Python client: sdks/python/willitinbox.py using the standard library.
  • CLI entrypoints support validate, test create, report get, webhook verify, sandbox wait, and sandbox check.
  • Use the API reference as the source of truth for the full /api/v1 surface.

When to use an SDK

Use an SDK when you want typed-ish helpers and consistent error handling. Use the CLI when CI needs a simple exit code for sandbox checks. Use direct HTTP when you need a language that does not have a first-party client yet.

REST API

Authenticated /api/v1 endpoints cover validation, bulk jobs, test inboxes, reports, webhooks, domains, DMARC, provider reputation, and usage.

SDKs

Dependency-light Node and Python clients include validation, reports, sandbox helpers, webhook verification, and wait/check workflows.

CLI

The package-ready CLI can validate addresses, fetch reports, verify webhooks, wait for sandbox messages, and run sandbox threshold checks.

Webhooks

Bulk completion and monitoring workflows can POST signed events to your own endpoint for automation.

Developer lifecycle

One email QA workflow from local code to production

A useful developer stack should preserve evidence as email moves from local development into staging and the real sender path. WillItInbox connects capture, inspection, validation, deliverability reports, and asynchronous automation without treating a sandbox result as proof of production delivery.

1. Capture

Send local or staging messages into an authenticated sandbox project and inspect the rendered message or retained MIME source.

2. Analyze

Run the captured message through deliverability analysis, or send the final production-path message to a generated test inbox.

3. Enforce

Use CLI exit codes, API responses, reports, and signed webhooks to gate releases or create review tasks.

Choose the right surface

Sandbox, API, SDK, webhook, or real-message test?

Choose the surface that matches the evidence and timing your workflow needs. Sandbox capture helps during development, APIs and SDKs automate repeatable checks, webhooks report asynchronous outcomes, and real-message tests inspect the final production sender path.

SurfaceBest useImportant limit
Email sandboxCapture and inspect development or staging messages safely.Capture evidence does not reproduce the complete production sender path.
REST APIIntegrate validation, tests, reports, bulk jobs, and operational evidence.Clients must handle authentication, quotas, retries, and inconclusive results.
Node/Python helpersUse common workflows with consistent request and error handling.The API reference remains the source of truth for the complete surface.
Signed webhooksReceive asynchronous completion and delivery events.Consumers must verify signatures and make processing idempotent.
Real-message testInspect the message produced by the actual ESP, domain, and sending path.Technical evidence cannot guarantee universal inbox placement.

CI policy

Fail releases on deterministic defects, not every warning

A stable CI policy distinguishes hard technical failures from contextual warnings. Persist the report or message identifier so developers can inspect the evidence behind a failed check instead of debugging an unexplained score.

Fail

Malformed MIME, broken authentication, missing required headers, capture errors, or a score below an explicitly owned threshold.

Review

Content, reputation, placement, and provider warnings that need campaign or sender context.

Retry

Rate limits, temporary provider responses, delayed analysis, or webhook transport failures with bounded backoff.

Integration design

Design API checks around business decisions

Do not call the API only to display a score. Store the evidence needed for the next decision: suppress, segment, retry, block a release, warn a sender, open an audit task, or notify the domain owner.

  • Use validation endpoints before accepting or importing recipients.
  • Use test inbox and report endpoints for release QA around important templates.
  • Use webhooks for bulk completion and future monitoring events.

Reliability

Handle quota, retries, and inconclusive results explicitly

A production integration should treat validation and deliverability evidence as state. Persist job ids, report tokens, response codes, webhook delivery ids, and final policy decisions. Retry transport failures, but do not blindly retry provider policy blocks.

API surfaceUse it forStore
ValidationSignup, import, enrichment, outbound hygienestatus, sub_status, confidence, evidence
BulkCSV list hygiene and CRM cleanupjob id, summary, download URL, policy decision
ReportsTemplate QA and release checkstoken, score, critical findings, PDF/share link
WebhooksAsync completion and alertsevent, signature result, delivery status

Related

Email sandbox

Capture development messages, inspect source, and run reusable CI checks.

API reference

Review authenticated endpoints, request shapes, errors, and quotas.

Webhook documentation

Verify HMAC signatures and process asynchronous events safely.

SDK and CLI docs

Use Node, Python, and command-line helpers for common workflows.

Developers use case

See how this workflow applies to teams running developer testing, sdks, webhooks, and ci/cd.

Deliverability Qa CI/CD Willitinbox API guide

Read the supporting guide for practical context around developer testing, sdks, webhooks, and ci/cd.

Validation API example

Review request and response patterns for single validation, bulk verification, suppression, and webhook flows.

Pricing

Compare validation volume, monitoring, API access, reporting, and workspace limits by plan.

FAQ

Can a sandbox prove production deliverability?

No. A sandbox verifies message generation, source, rendering, and configured checks. Run a real-message test through the production sender path before relying on the result.

How should webhook consumers handle duplicate deliveries?

Verify the signature, store a stable delivery or event identifier, and make processing idempotent before returning success.

Should CI fail on every warning?

No. Fail CI for deterministic critical issues such as broken authentication, missing required headers, or malformed payloads. Warnings should usually create human-review tasks.

Where should I start as a developer?

Start with email validation API example, then read SDK docs and webhooks.