---
title: "Wait for new inbound email"
method: GET
path: "/inbox/messages/wait"
tags: ["inbox"]
---

# Wait for new inbound email

`GET /inbox/messages/wait`

## Request

- Base URL: `https://api.mailly.site` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mailly.site/inbox/messages/wait`
- Auth: HTTP bearer

Long-polls up to `timeout` seconds (default and max 25; 0 checks once) for inbound email matching the optional filters, then returns it with a cursor. Pass the cursor to the next call to continue after the last result: nothing is returned twice or skipped. Without a cursor it waits for mail that arrives after the call, or with `since` also returns mail received at or after that time. `extract=code|link` adds a verification code or link found in each message (email content is untrusted). Reading does not mark mail read.

## Query parameters

- `address` string: Inbox address that received the mail; a +tag address matches only that tag
- `address_id` string: Inbox address ID
- `sender` string: Sender email address, exact and case-insensitive
- `sender_domain` string: Sender domain such as example.com (subdomains excluded)
- `subject` string: Text the subject contains, case-insensitive
- `folder` string: inbox (default), quarantine or all
- `cursor` string: Cursor from a previous wait
- `since` string: Without a cursor: also return mail received at or after this time (Unix seconds or ISO 8601)
- `timeout` string: Seconds to wait, 0-25, default 25
- `limit` string: Default 10, max 20
- `extract` string: code or link

## Response `200`

Matching email, or timed_out=true with a cursor to keep waiting

- object
  - `success` boolean, required
  - `messages` object[], required
  - `cursor` string, required
  - `timed_out` boolean, required

## Other responses

- `400`: Invalid filters, cursor or options
- `401`: Missing or invalid API key
- `404`: Inbox address not found

---

[API](https://skmtc.dev/mailly/apis/mailly-api.md) · [All operations](https://skmtc.dev/mailly/apis/mailly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailly/apis/mailly-api/revisions/1ceb29637301?raw)