Pagination

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

{
  "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.

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:

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 sizeCopy Anchor Link

?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.

SortingCopy Anchor Link

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 fullCopy Anchor Link

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.