---
title: "List messages"
description: "What has arrived, newest first, metadata only. This is the call to poll."
url: "https://nextmail.sh/docs/api/temp-mail/messages"
area: "API"
category: "Disposable inboxes"
---

# List messages

What has arrived, newest first, metadata only. This is the call to poll.

`GET /temp-mail/inboxes/{id}/messages`

## GET /temp-mail/inboxes/{id}/messages

What has arrived, newest first, metadata only. This is the call to poll.

## The inbox token

**shell**

```
export OE=https://api.nextmail.sh
export INBOX="Authorization: Bearer oe_inbox_kQ8v…"
```

Every call below carries the token `POST /temp-mail/inboxes` returned, in the same `Authorization: Bearer` header an API key uses. The address itself authorises nothing, and that separation is the point of the feature rather than a formality: a disposable address is handed to the party you are keeping at arm’s length the moment it is issued.

> The token alone decides which inbox a call reads. The id in the path is not checked against it, so a caller juggling two inboxes has to keep each token with its own id.

## Example

A page holds up to 50 messages: `limit` is 1 to 50 and optional, and when `hasMore` is true, `nextCursor` goes back as `cursor` for the next page, so nothing that arrived is hidden. A page can hold fewer than `limit`, even none, while `hasMore` is still true, because mail to other addresses on the pool is read and dropped. The lease comes back on the same response, so a poller does not need a second call to know when to stop.

**curl**

```
curl "$OE/temp-mail/inboxes/tinb_octopus-signup/messages?limit=25" -H "$INBOX"
```

**Response**

```
{
  "object": "list",
  "data": [
    {
      "object": "temp_message",
      "id": "thr_4b81c07d2fa9418e93c6a13f",
      "from": { "name": "Acme", "email": "no-reply@acme.com" },
      "to": "octopus-signup@freemailaddress.com",
      "subject": "Confirm your email",
      "snippet": "Your code is 481923…",
      "spam": false,
      "seen": false,
      "attachmentCount": 0,
      "sizeBytes": 8241,
      "receivedAt": "2026-09-01T10:31:04.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "expiresAt": "2026-09-01T12:00:00.000Z"
}
```

> `snippet` is the first 400 characters of the body as text, which is usually the whole reason the inbox exists. A confirmation code is generally visible without opening anything.

> `spam` is what the shared heuristic thought. It is a flag and nothing else: nothing was filed away, moved or suppressed, and the message is in this list either way.

> `seen` mirrors the unread state of the message in the mailbox that runs the pool. Nothing on these routes changes it, retrieving a message included.

> A `limit` outside 1 to 50 or a `cursor` over 512 characters is 422 `invalid_parameter`, and while the pool cannot be read the answer is 503 `not_configured`.

## Reference

- [`GET /temp-mail/inboxes/{id}/messages`](https://nextmail.sh/docs/api/reference/temp-mail#get-temp-mail-inboxes-id-messages): full reference