\n

ShazaMail

Developer Email Testing for Automated Workflows

Use scoped API keys and deterministic test inboxes to automate signup, password-reset, transactional-email, and OTP flows.

Product documentation last reviewed: 2026-09-28

The REST API is built around test inbox resources

The developer API is mounted under /api/v1 and uses Bearer API-key authentication with explicit scopes. A test run can create a temporary inbox with POST /api/v1/test-inboxes, tag it with a run ID or external reference, inspect messages, retrieve a specific message, and delete the inbox when the run is finished. Test inbox creation also supports an Idempotency-Key header so a retried CI request does not need to create duplicate resources.

Wait for the message instead of using arbitrary sleep timers

POST /api/v1/test-inboxes/:id/wait performs an immediate message lookup and can then wait for delivery with a bounded timeout of up to 30 seconds. Matchers include sender, recipient, subject_contains, subject_equals, verification-code presence, category, received_after, and internet_message_id. This lets a test wait for the event it actually needs instead of assuming that email will arrive after a fixed delay.

API access is scoped, metered, and rate limited

Developer keys are checked by prefix and constant-time secret verification, can expire, and carry explicit scopes such as test_inboxes:write or messages:read. The current Pro entitlement defines 10,000 API requests per month, while the developer middleware enforces a 120 requests-per-minute limit. Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers so clients can adapt without guessing.

Webhooks complement polling for asynchronous workflows

The API includes endpoints to create, inspect, update, delete, rotate secrets for, and test webhooks. Resource events such as test inbox creation can be dispatched asynchronously. For automated testing, the wait endpoint is useful inside a single test run, while webhooks are better suited to systems that need a push-style notification when mail-related events occur.

Common questions

Do developer requests use the normal browser login session?

No. The developer API expects an Authorization: Bearer API_KEY header and enforces API-key scopes independently of the browser session.

What happens when the per-minute API limit is exceeded?

The API returns HTTP 429 with Retry-After plus rate-limit headers that describe the current limit and reset window.

Is the TypeScript SDK published to npm?

ShazaMail contains TypeScript SDK interfaces in the product codebase, but this page documents the REST API directly and does not require an npm package.