Inboxes and their domains

An inbox receives mail for your tests. Each one has a domain of its own under waridex.email, and every address under that domain reaches it: the inbox is a catch-all. A suite therefore creates one inbox for a test run and lets every test invent its own recipient.

Creating an inbox

curl -sS https://api.waridex.com/v1/inboxes \
  -H "Authorization: Bearer $WARIDEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "signup", "tags": ["run-42"], "expiresInSeconds": 3600}'

POST /v1/inboxes needs the inbox:create scope and takes:

• name, required: 1 to 100 characters, shown on the dashboard. Names need not be unique.
• tags, optional: up to ten labels, typically the test run. See tags and the per-run purge.
• expiresInSeconds, optional: from one second to one year. When it passes, the inbox stops receiving mail and is deleted with its messages within the hour. Without it the inbox lives until you delete it; its messages still go when the plan’s retention runs out.

You never choose the address. The API makes the inbox’s slug from the name (accents removed, lower case, every run of other characters one hyphen, at most 47 characters) plus a hyphen and six random characters, and answers with it:

Field	Example	Meaning
slug	signup-k3f9x2	the name’s base and a random suffix
domain	signup-k3f9x2.waridex.email	the inbox’s own domain; any address under it reaches the inbox
address	signup@signup-k3f9x2.waridex.email	a ready-made default recipient
catchAll	true	every local part under domain is delivered

A domain is never issued twice, not even after its inbox is deleted, so mail meant for an old inbox can never land in a new one.

What reaches an inbox

Any local part under the inbox’s domain is delivered, plus signs and all: user1@signup-k3f9x2.waridex.email, reset+42@signup-k3f9x2.waridex.email and anything@signup-k3f9x2.waridex.email all land in the same inbox. Every message records the exact recipient in envelopeTo, and the to filter of wait and of the message list matches it exactly, ignoring case.

Anything else is refused while the sender is still connected, so it bounces rather than disappearing: an address under an unknown, deleted or expired inbox’s domain, the bare waridex.email, and a deeper name such as user@x.signup-k3f9x2.waridex.email. A message may be at most 10 MB and have at most 20 recipients, and a workspace takes at most 300 recipients a minute, each address a message is delivered to counting as one; its plan’s monthly quota applies too.

A test can also put a message in an inbox over HTTPS, without sending any mail, which is useful where a network blocks port 25 or a fixture needs a message captured from real mail: see message injection.

Reading an inbox’s mail

Call	Scope	Returns
GET /v1/inboxes	email:read	the workspace’s inboxes, newest first; tag, q (name or domain contains) and paging with limit and offset
GET /v1/inboxes/{id}	email:read	one inbox
GET /v1/inboxes/{id}/messages	email:read	an inbox’s messages, newest first; filters since, subjectContains, from, to
GET /v1/messages	email:read	every message of the workspace, newest first; filters inbox, tag, to, since, subjectContains, from
GET /v1/messages/search	email:read	messages whose subject or sender contains q; filters inbox, tag, to, since
GET /v1/messages/{id}	email:read	a message with its text and HTML bodies, codes, links and attachment list
GET /v1/messages/{id}/raw	email:read	the message exactly as received
GET /v1/messages/{id}/attachments/{partIndex}	email:read	one attachment
POST /v1/inboxes/{id}/messages	email:inject	stores a raw message in the inbox as if it had arrived; see message injection
DELETE /v1/messages/{id}	email:delete	deletes a message
DELETE /v1/inboxes/{id}	inbox:delete	deletes an inbox and its messages

Most tests need none of these: wait returns the message they are waiting for.