# List emails

Source: https://docs.maylee.app/api-reference/emails/list-emails

`GET https://api.maylee.app/api/v1/emails`

Scope: `read`.

Use this to browse a mailbox or a saved view. For keyword lookup use `/emails/search` instead.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mailboxId` | query | string | no |  |
| `folderType` | query | string | no | Restrict to one folder. Omitted, all folders are considered. One of: `INBOX`, `SENT`, `DRAFTS`, `SPAM`, `TRASH`. |
| `viewId` | query | string | no | Apply a saved view. Get ids from `GET /views`. |
| `filtered` | query | string | no | `only` lists the INBOX emails hidden by inbox filters and by `hideFromInbox` AI labels (the app's "Filtered emails"). The plain INBOX listing never returns them; views are never affected. One of: `only`. |
| `filters` | query | string | no | JSON-encoded filter tree. Max 5 levels, 50 conditions, 500-character values. |
| `search` | query | string | no | Optional keyword filter. Terms shorter than 2 characters are ignored. |
| `cursor` | query | string | no | Opaque cursor from a previous response `nextCursor`. Format is `ISO_DATE\|ID` and is not part of the contract. |
| `limit` | query | integer | no | Page size. Values above 200 are clamped. From 1 to 200. Default: `50`. |

## Example request

```bash
curl -X GET "https://api.maylee.app/api/v1/emails" \
  -H "Authorization: Bearer $MAYLEE_KEY"
```

## Responses

### 200

A page of emails.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hasMore` | boolean | yes |  |
| `items` | array of EmailListItem | yes |  |
| `items[].attachments` | array of Attachment | no | Metadata only. |
| `items[].cc` | array of EmailAddress | no |  |
| `items[].date` | string (date-time) | no |  |
| `items[].folderId` | string | no | Folder the email lives in. |
| `items[].from` | EmailAddress | no |  |
| `items[].hasAttachments` | boolean | no |  |
| `items[].id` | string | no | Maylee id of the email. |
| `items[].inReplyTo` | string or null | no | RFC `In-Reply-To` header. |
| `items[].isDraft` | boolean | no |  |
| `items[].isRead` | boolean | no |  |
| `items[].isStarred` | boolean | no |  |
| `items[].mailboxId` | string | no | Mailbox the email lives in. |
| `items[].messageId` | string | no | RFC `Message-ID` header. Needed to reply in the thread. |
| `items[].references` | array of string | no | RFC `References` header. |
| `items[].snippet` | string | no | Short text preview. |
| `items[].subject` | string | no |  |
| `items[].tags` | array of LabelRef | no | Maylee labels applied to the email, manual and AI. |
| `items[].threadId` | string or null | no | Provider conversation id, when the provider has one. |
| `items[].to` | array of EmailAddress | no |  |
| `items[].waitingForReply` | boolean | no | On an email you sent: Maylee estimates that it still expects an answer. |
| `nextCursor` | string or null | yes | Pass back as `?cursor=` to fetch the next page. `null` on the last page. |

```json
{
  "hasMore": true,
  "items": [
    {
      "attachments": [
        {
          "filename": "brief.pdf",
          "mimeType": "application/pdf",
          "size": 48213
        }
      ],
      "cc": [],
      "date": "2026-08-25T13:47:02.000Z",
      "folderId": "cmfd1a2b3c4d5e6f7g8h9i0j",
      "from": {
        "email": "client@acme.com",
        "name": "Jane Client"
      },
      "hasAttachments": true,
      "id": "cmemx1a2b3c4d5e6f7g8h9i0",
      "inReplyTo": null,
      "isDraft": false,
      "isRead": false,
      "isStarred": false,
      "mailboxId": "cmbx1a2b3c4d5e6f7g8h9i0j",
      "messageId": "<CAF3k9x1@mail.example.com>",
      "references": [],
      "snippet": "Hello, could you send us a quote for the annual plan?",
      "subject": "Quote request",
      "tags": [
        {
          "color": "Blue",
          "id": "cmtgai1b2c3d4e5f6g7h8i9j",
          "isAiLabel": true,
          "name": "Sales"
        }
      ],
      "threadId": "18c2f5a9e7b1d3c4",
      "to": [
        {
          "email": "contact@your-company.com",
          "name": null
        }
      ],
      "waitingForReply": false
    }
  ],
  "nextCursor": "2026-08-25T13:47:02.000Z|cmemx1a2b3c4d5e6f7g8h9i0"
}
```

### 400

Invalid filter tree, or a bound was exceeded.

### 401

Missing, malformed, revoked or expired API key.

### 403

Key lacks the required scope, or outbound sending is not enabled on it.

### 408

Query exceeded the server time limit.

### 429

Per-minute rate limit (`RATE_LIMIT_EXCEEDED`) or monthly quota (`QUOTA_EXCEEDED`) exhausted.

Errors use the format `{ "code", "error", "details" }`: see [Errors](/errors.md).