---
title: "List emails"
method: GET
path: "/v1/emails"
tags: ["Emails"]
---

# List emails

`GET /v1/emails`

## Request

- Base URL: `https://api.mailbeast.ai`
- URL: `https://api.mailbeast.ai/v1/emails`
- Auth: HTTP bearer

List emails across your mailboxes, newest first. Results carry a `snippet` preview but never the message body; fetch a single email to read it. Filter by mailbox, campaign, conversation, lead, read state, direction, folder, date, or full-text search.

Requires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`.

## Query parameters

- `cursor` string
- `limit` number
- `mailbox` string
- `campaignId` string
- `threadId` string
- `leadId` string
- `isUnread` boolean
- `type` 'sent' | 'received'
- `folder` 'inbox' | 'untracked' | 'important' | 'snoozed' | 'archived'
- `search` string
- `latestOfThread` boolean
- `since` string
- `until` string
- `sortOrder` 'asc' | 'desc'

## Response `200`

- EmailListApiResponseDto
  - `data` EmailApiDto[], required
    - `id` string, required
    - `threadId` string, nullable, required: Conversation this email belongs to. `null` when the email is not part of a conversation. An opaque identifier: pass it back as-is, do not parse or construct it.
    - `messageId` string, nullable, required: RFC 5322 Message-ID as set by the sending server.
    - `mailbox` EmailMailboxDto, required
      - `id` string, required
      - `email` string, required
    - `from` EmailParticipantDto, required
      - `email` string, required
      - `name` string, nullable, required
    - `to` string[], required
    - `cc` string[], required
    - `bcc` string[], required
    - `subject` string, required
    - `snippet` string, nullable, required: Short preview of the message. Always present in list results.
    - `isUnread` boolean, nullable, required: Read state. `null` when the email is not part of a conversation and therefore has no read state, which is not the same as read.
    - `type` 'sent' | 'received', required
    - `campaignId` string, nullable, required
    - `leadId` string, nullable, required
    - `hasAttachments` boolean, required
    - `receivedAt` string, date-time, required
    - `sentAt` string, date-time, nullable, required
  - `meta` EmailListMetaDto, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required: Pass as `?cursor=` for the next page; `null` on the last page.

## Other responses

- `400`: The request body or parameters failed validation.
- `401`: Missing or invalid API key.
- `403`: The key lacks a required scope, or the plan does not include API access.
- `429`: Rate limit exceeded - retry after the interval in the Retry-After header.

---

[API](https://skmtc.dev/mailbeast/apis/mailbeast-public-api.md) · [All operations](https://skmtc.dev/mailbeast/apis/mailbeast-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailbeast/apis/mailbeast-public-api/revisions/6440ce0738a4?raw)