Waiting | MailBench SMTP

Wait for a message

GET/v1/inboxes/{id}/messages/wait

Returns the newest message matching the filters in full, immediately if one already exists, otherwise as soon as one arrives. Subscribes before it first looks, so an email that lands in between is not missed.

Use since to ignore mail from earlier test runs. If nothing arrives in time the answer is 404 with code wait_timeout.

Path parameters

idstringrequired
Inbox ID.

Query parameters

qstring
Search. Free text matches subject, sender, recipients and body. Also supports from:, to:, subject:, is:unread, is:read, is:tagged, tag:name, has:attachment, larger:1m, after:/before:, negation with - or !, and "exact phrases".
fromstring
Sender contains this text.
tostring
Any recipient contains this text.
subjectstring
Subject contains this text.
sincestring (date-time)
Only messages received at or after this time.
timeoutnumber
Seconds to wait. Defaults to 20, capped at 30.
Default 20.

Returns

idstringrequired
inbox_idstringrequired
received_atstring (date-time)required
envelope_fromstringrequired
The SMTP MAIL FROM.
recipientsarray of stringsrequired
The SMTP RCPT TO addresses, including Bcc.
fromstringrequired
The From header.
tostringrequired
The To header.
subjectstringrequired
message_idstringrequired
The Message-ID header.
sizeintegerrequired
Size in bytes.
has_textbooleanrequired
has_htmlbooleanrequired
attachment_countintegerrequired
link_countintegerrequired
tlsbooleanrequired
Whether the sender used TLS.
parse_errorstring
Set when the message is not valid MIME. Parts may be missing.
readbooleanrequired
tagsarray of stringsrequired
textstring
htmlstring
linksarray of stringsrequired
headersobject
attachmentsarray of objectsrequired
Child attributes
- indexintegerrequired
- filenamestringrequired
- content_typestringrequired
- sizeintegerrequired
- urlstringrequired
  Path to download it (needs your API key).
- thumb_urlstring
  Path to a thumbnail, for images.
raw_urlstringrequired
Path to the raw .eml.
html_urlstring
Path to the HTML body, when there is one.
filesobjectrequired
Signed, expiring URLs a browser can open without an Authorization header.
Child attributes
- rawstring (uri)required
- htmlstring (uri)
- attachmentsarray of stringsrequired
- thumbnailsarray of strings
- expires_atstring (date-time)required
list_unsubscribeobject
Parsed List-Unsubscribe headers, when present.
Child attributes
- headerstring
- header_poststring
- linksarray of strings
- errorsstring

Errors

400The request was malformed or a value was invalid.

401Missing or invalid API key.

404No inbox, or no matching message within the timeout (`wait_timeout`).

429Too many requests. Wait `Retry-After` seconds.

curl / JavaScript / Python

curl "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/wait" \
  -H "Authorization: Bearer $API_KEY"

const res = await fetch("https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/wait", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/inboxes/box_g3bekcev4z7i4psq/messages/wait",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]

Response 200

{
  "success": true,
  "data": {
    "id": "msg_htumcicppd26jek6",
    "inbox_id": "box_g3bekcev4z7i4psq",
    "received_at": "2026-10-12T10:00:00Z",
    "envelope_from": "noreply@app.test",
    "recipients": [
      "sam@example.org"
    ],
    "from": "App <noreply@app.test>",
    "to": "Sam <sam@example.org>",
    "subject": "Welcome aboard",
    "message_id": "<8f2c1a@app.test>",
    "size": 1432,
    "has_text": true,
    "has_html": true,
    "attachment_count": 0,
    "link_count": 2,
    "tls": true,
    "parse_error": "string",
    "read": false,
    "tags": [
      "billing"
    ],
    "text": "Click https://app.test/verify/abc123 to confirm your address.",
    "html": "<p>Click <a href=\"https://app.test/verify/abc123\">here</a>.</p>",
    "links": [
      "https://app.test/verify/abc123"
    ],
    "headers": {},
    "attachments": [
      {
        "index": 0,
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "size": 48211,
        "url": "string",
        "thumb_url": "string"
      }
    ],
    "raw_url": "/v1/messages/msg_htumcicppd26jek6/raw",
    "html_url": "/v1/messages/msg_htumcicppd26jek6/html",
    "files": {
      "raw": "https://example.com/hook",
      "html": "<p>Click <a href=\"https://app.test/verify/abc123\">here</a>.</p>",
      "attachments": [
        "https://example.com/hook"
      ],
      "thumbnails": [
        "https://example.com/hook"
      ],
      "expires_at": "2026-10-12T10:00:00Z"
    },
    "list_unsubscribe": {
      "header": "string",
      "header_post": "string",
      "links": [
        "https://app.test/verify/abc123"
      ],
      "errors": "string"
    }
  }
}