Wait

wait is the call a test makes after it has made the app under test send an email. It returns the first matching message that has not been returned before, at once if one is already in the inbox, otherwise the moment one arrives. With extract=otp or extract=link the response also carries the code or link, so the test needs no polling loop and no parsing.

curl -sS -G "https://api.waridex.com/v1/inboxes/$INBOX_ID/wait" \
  -H "Authorization: Bearer $WARIDEX_API_KEY" \
  --data-urlencode "to=user1@signup-k3f9x2.waridex.email" \
  --data-urlencode "subjectContains=verification" \
  -d extract=otp

GET /v1/inboxes/{id}/wait needs the email:read scope. Each API key may make 60 wait calls a minute, an allowance the authenticator’s own holding calls share.

Parameters

Parameter	Default	Meaning
timeoutSeconds	30	how long to hold the request, from 1 to 60 seconds
to	none	the exact recipient, ignoring case. Tests that share one inbox each wait on their own address; without to the first match wins
subjectContains	none	the subject contains this text, ignoring case
from	none	the sender, from the From header or the envelope, contains this text, ignoring case
since	none	only messages received after this time (ISO 8601, such as 2026-09-23T10:15:00Z)
unread	true	only messages no earlier wait has returned; false also returns ones that were
extract	none	otp for a code, link for a link, none for the message alone
minLength, maxLength	4, 8	with extract=otp: the length a code must have
pattern	none	with extract=otp: your own regular expression, which replaces the stored candidates; see extraction
linkContains	none	with extract=link: the link contains this text, ignoring case
includeBody	false	also return the text and HTML bodies

Matching messages are returned oldest first. With unread=true, a message returned to one wait is never returned to another, so two waits on the same inbox never receive the same message: the second keeps waiting for the next one.

The response

{
  "message": {
    "id": "0199a3c4-8e2f-7b90-a1c4-5d6e7f809a1b",
    "inboxId": "0199a3c4-5b7e-7d21-9f0a-3c5e8b1d2f47",
    "receivedAt": "2026-09-23T10:15:04.512+00:00",
    "from": "Example <no-reply@example.com>",
    "to": "user1@signup-k3f9x2.waridex.email",
    "subject": "Your verification code",
    "envelopeFrom": "no-reply@example.com",
    "envelopeTo": "user1@signup-k3f9x2.waridex.email",
    "messageId": "<20260923101503.4f2a@example.com>",
    "sizeBytes": 4817,
    "hasAttachments": false,
    "source": "Smtp",
    "returnedByWaitAt": "2026-09-23T10:15:04.530+00:00",
    "spfResult": "pass",
    "dkimResult": "pass",
    "codes": [
      {
        "code": "482913",
        "confidence": 0.9,
        "method": "heuristic",
        "part": "text",
        "context": "Your verification code is 482913.",
        "rank": 0
      }
    ],
    "links": [],
    "attachments": []
  },
  "extraction": {
    "type": "otp",
    "found": true,
    "code": "482913",
    "confidence": 0.9,
    "method": "heuristic",
    "candidates": [
      {
        "code": "482913",
        "confidence": 0.9,
        "method": "heuristic",
        "part": "text",
        "context": "Your verification code is 482913.",
        "rank": 0
      }
    ],
    "links": [],
    "warnings": []
  }
}

message holds the message’s index fields, the codes and links found in it when it arrived, and its attachment list; text and html are added with includeBody=true, with bodyTruncated: true beside them where a part ran past the two million characters a response carries of each. spfResult and dkimResult record the sender’s SPF and DKIM checks for diagnosis only: mail is received whatever they say. source says how the message entered: Smtp for mail received on port 25, Api for one a test injected, which has neither result. Fields without a value are left out. extraction is present with extract=otp or extract=link: code or link is the answer, and candidates lists every code considered, best first. The extraction page explains the fields.

When it does not return a message

• Nothing arrived in time: 408 wait.timeout. The problem names the address waited on and lists in received the messages that arrived meanwhile without matching, which usually shows the near miss. Call wait again to keep waiting; a message that arrives between the two calls is not lost.
• A message arrived, but nothing could be extracted: 422 extract.not_found, with the message’s id, subject and sender, every candidate with the reason it lost, and the start of the body. The message is not marked as returned, so a second wait with other extraction settings finds it again.
• The inbox does not exist in the key’s workspace: 404 inbox.not_found.

Waiting for longer than 60 seconds is a loop of calls: each one returns at once when the message is already there.