Quickstart: curl

This quickstart runs a whole email test against https://api.waridex.com from a shell: it creates an inbox tagged with the run, makes an address under the inbox’s domain, waits for a message to that address with the code extracted, and deletes the run’s inboxes. The same four calls work from any test framework that can make an HTTP request.

You need curl (7.76 or later, for --fail-with-body), jq, and an API key of your workspace with the scopes email:read, inbox:create and inbox:delete. A new key on the dashboard’s API keys page starts with exactly those; step 4’s injection call needs email:inject ticked beside them.

1. Set up the shell

export WARIDEX_API_KEY="wx_..."   # the key the dashboard showed you once
API="https://api.waridex.com"
RUN="run-$(date +%s)"             # one tag per test run; in CI, use the run's id

A tag is 1 to 64 letters, digits, dots, hyphens or underscores, starting and ending with a letter or digit.

2. Create an inbox with a tag

INBOX=$(curl -sS --fail-with-body "$API/v1/inboxes" \
  -H "Authorization: Bearer $WARIDEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"signup\", \"tags\": [\"$RUN\"]}")
echo "$INBOX"

The API answers 201 Created with the inbox. It made the inbox’s slug from the name and a random suffix, and the slug is the inbox’s own domain:

{
  "id": "0199a3c4-5b7e-7d21-9f0a-3c5e8b1d2f47",
  "name": "signup",
  "slug": "signup-k3f9x2",
  "domain": "signup-k3f9x2.waridex.email",
  "address": "signup@signup-k3f9x2.waridex.email",
  "catchAll": true,
  "tags": ["run-1790000000"],
  "createdAt": "2026-09-23T10:15:00.123+00:00"
}

3. Read its domain and make an address

INBOX_ID=$(jq -r .id <<< "$INBOX")
DOMAIN=$(jq -r .domain <<< "$INBOX")
ADDRESS="user1@$DOMAIN"
echo "$ADDRESS"

Every address under the domain reaches the inbox, so each test of the run can use its own, such as user1@…, user2@… or reset+42@…. address in the response is a ready-made default if one is enough.

4. Send the email

Make the app under test send its email to $ADDRESS: sign up with it, or ask for a password reset. To try the quickstart without an app, send a message with a six-digit code in it, such as “Your verification code is 482913”, from your own mail account to the address.

Where no mail can leave the machine — many home and cloud networks block port 25 — put the message in the inbox over HTTPS instead. The call takes the message as it would follow SMTP’s DATA, and needs a key with the email:inject scope:

printf 'From: Example <no-reply@example.com>\r\nTo: %s\r\nSubject: Your verification code\r\nMessage-ID: <sample-1@example.com>\r\n\r\nYour verification code is 482913.\r\n' "$ADDRESS" \
  | curl -sS --fail-with-body "$API/v1/inboxes/$INBOX_ID/messages" \
      -H "Authorization: Bearer $WARIDEX_API_KEY" \
      -H "Content-Type: message/rfc822" \
      --data-binary @-

The message is stored through the same pipeline as mail from port 25, so the wait below returns it with its code extracted; it is marked source: Api and has no SPF or DKIM result. See message injection.

5. Wait for it

curl -sS --fail-with-body -G "$API/v1/inboxes/$INBOX_ID/wait" \
  -H "Authorization: Bearer $WARIDEX_API_KEY" \
  --data-urlencode "to=$ADDRESS" \
  -d extract=otp \
  -d timeoutSeconds=60 \
  | jq -r .extraction.code

The call returns as soon as a message to $ADDRESS is in the inbox, or at once if it already is. to keeps the wait to that one recipient, so tests sharing the inbox never take each other’s mail. With extract=otp the response carries the extraction result beside the message; shortened, it reads:

{
  "message": {
    "id": "0199a3c4-8e2f-7b90-a1c4-5d6e7f809a1b",
    "subject": "Your verification code",
    "from": "Example <no-reply@example.com>",
    "envelopeTo": "user1@signup-k3f9x2.waridex.email",
    "receivedAt": "2026-09-23T10:15:04.512+00:00"
  },
  "extraction": {
    "type": "otp",
    "found": true,
    "code": "482913",
    "confidence": 0.9,
    "method": "heuristic",
    "warnings": []
  }
}

If no matching message arrives within timeoutSeconds (at most 60), the API answers 408 wait.timeout and lists what did arrive meanwhile; call wait again to keep waiting. If a message arrived but no code could be found in it, the API answers 422 extract.not_found with every candidate it considered. Both are explained in wait and extraction and pinned patterns.

6. Delete the run’s inboxes

curl -sS --fail-with-body -X DELETE "$API/v1/inboxes?tag=$RUN" \
  -H "Authorization: Bearer $WARIDEX_API_KEY"

{ "tag": "run-1790000000", "deletedInboxes": 1, "deletedMessages": 1 }

Every inbox carrying the tag goes, with its mail. A tag no inbox carries answers 200 with zeros, so a teardown step can run twice. Put this call where your suite tears down, so it runs whether the tests passed or not.

Next

Inboxes and their domainsNames, expiry and what reaches an inbox.

WaitEvery filter and what the response holds.

Tiers, quotas and retentionHow much mail a workspace receives and how long it is kept.