ShazaMail
Temporary Email API for Automated Testing
Automate inbox creation and email assertions with scoped API keys, bounded wait requests, idempotency, and structured message responses.
Product documentation last reviewed: 2026-09-28
Create an isolated inbox for each test run
POST /api/v1/test-inboxes creates an expiring test inbox associated with the authenticated developer account and environment. The request can include ttl_seconds, run_id, external_reference, tags, and purpose. TTL values are bounded between one minute and 24 hours. The response contains the inbox ID, generated email address, environment, timestamps, and optional run metadata.
Query messages or wait for one matching message
GET /api/v1/test-inboxes/:id/messages lists messages for a test inbox, while POST /api/v1/test-inboxes/:id/wait can block for a matching delivery. A successful wait response includes the message ID, sender, recipient, subject, text, received timestamp, extracted verification code when available, category, and Safe View summary. The wait endpoint has a 30-second maximum timeout so CI jobs do not hang indefinitely.
Retrieve one message or its verification code explicitly
The API exposes GET /api/v1/messages/:id for message retrieval and GET /api/v1/messages/:id/verification-code for workflows that only need the extracted code. These endpoints require the appropriate messages:read or verification_codes:read scope. Attachment access is separated into its own scoped endpoint so an API key can be granted only the capabilities a test suite actually requires.
Plan around quotas and idempotent retries
The current developer middleware applies 120 requests per minute and a 10,000-request monthly quota for the Pro API entitlement. Clients should read the returned rate-limit headers, use bounded retries, and include Idempotency-Key on inbox-creation requests that may be replayed by CI infrastructure. This is more reliable than silently issuing duplicate create calls after network errors.
Common questions
What authentication format does the API use?
Developer endpoints expect Authorization: Bearer <API_KEY>. Keys are scoped and may be limited by status, expiration, environment, and usage limits.
How long can a wait request run?
The current wait engine caps a single request at 30 seconds and uses a 20-second default when no timeout is specified.
Can the API be used for production customer mailboxes?
The documented developer endpoints are designed around test inbox resources and automated email verification workflows, not as a general-purpose outbound or permanent mailbox service.