# Pagination

> Cursor pagination on email lists and search, sorting, and the reference lists that are returned in full.

Source: https://docs.maylee.app/pagination

`GET /emails` and `GET /emails/search` return pages:

```json
{
  "items": [],
  "nextCursor": "2026-08-12T10:30:00.000Z|cmemx1a2b3c4d5e6f7g8h9i0",
  "hasMore": true
}
```

Pass `nextCursor` back as `?cursor=` to fetch the next page. It is `null` on the last page, never absent, so you do not have to tell "no next page" from "missing field". **Treat the cursor as opaque**: its format is not part of the contract.

```bash
curl -G https://api.maylee.app/api/v1/emails \
  -H "Authorization: Bearer $MAYLEE_KEY" \
  --data-urlencode 'folderType=INBOX' \
  --data-urlencode 'cursor=2026-08-12T10:30:00.000Z|cmemx1a2b3c4d5e6f7g8h9i0'
```

A loop that reads a whole folder:

```js
let cursor = null
do {
  const params = new URLSearchParams({ folderType: 'INBOX', limit: '200' })
  if (cursor) params.set('cursor', cursor)
  const response = await fetch(`https://api.maylee.app/api/v1/emails?${params}`, {
    headers: { Authorization: `Bearer ${process.env.MAYLEE_KEY}` },
  })
  const page = await response.json()
  for (const email of page.items) {
    // ...
  }
  cursor = page.nextCursor
} while (cursor)
```

## Page size

`?limit=` sets the page size: 50 by default, 200 at most. A larger value is brought down to 200, and an unreadable one (`abc`, `0`) falls back to 50 instead of failing.

## Sorting

Lists are ordered by date, most recent first. Search results are ordered by relevance, then by date. There is no parameter to change the order.

## Lists returned in full

Reference lists are short by nature and are **not** paginated: `GET /mailboxes`, `GET /labels`, `GET /views`, `GET /ai-label-rules`, `GET /filters` and `GET /auto-forward-rules` return `{ "items": [] }` only, without `nextCursor` or `hasMore`. `GET /drafts` accepts `?limit=` and returns the most recent drafts up to that limit.