TestLab API

Create isolated QA inboxes, poll messages, extract OTPs and links, and clean up test data from CI pipelines.

Authentication

Create a key inside a TestLab workspace and send it as a Bearer token. The complete token is displayed once. Store it in a CI secret manager, never in client-side JavaScript or source control.

Authorization: Bearer mv_live_your_prefix_your_secret

Create a test inbox

curl -X POST https://mailvator.com/api/v1/inboxes \
  -H "Authorization: Bearer $MAILVATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias":"signup-123"}'

The response includes a private address under the workspace slug. Messages remain visible only to authenticated workspace members and API keys.

Poll for messages

curl "https://mailvator.com/api/v1/messages?inbox=signup-123&limit=20" \
  -H "Authorization: Bearer $MAILVATOR_API_KEY"

Poll with a timeout and exponential backoff. Each summary includes sender, subject, text preview, received time, extracted links and a likely OTP when present.

Fetch one message

GET /api/v1/messages/{messageId}

The detail endpoint returns the stored text body, sanitised HTML text, headers, links and OTP for assertions.

Delete test data

DELETE /api/v1/inboxes/{alias}

Deletion removes the inbox marker and its messages. Private TestLab data otherwise follows the workspace retention period.

OpenAPI specification

Download the machine-readable OpenAPI 3.1 specification for code generation, validation and Postman import.