Emails

List emails

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.

get/v1/emails

Request

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

Query parameters

cursorstring

Opaque cursor from a previous response’s meta.nextCursor.

limitnumber
Example:50
mailboxstring
Example:jane@acme.com,sales@acme.com

Filter by mailbox address, comma-separated. Addresses you do not own are ignored.

campaignIdstring
Example:c1f3b0a2-6d4e-4f8b-9a1c-2e5d7f0a3b6c
threadIdstring
Example:13a265fd-f0f2-b1d1-d6fc-154e483183e7

Return only emails in this conversation. Pass a threadId exactly as returned - it is opaque.

leadIdstring
Example:9d4e2f10-5b6a-4c73-8e19-0f2a7c4d8b31
isUnreadboolean
Example:true

Filter by read state. Emails that are not part of a conversation have no read state and match neither true nor false.

type'sent' | 'received'
Example:received
folder'inbox' | 'untracked' | 'important' | 'snoozed' | 'archived'
Example:inbox

Return only emails whose conversation is in this folder - the same folders your team sees in the dashboard. inbox: campaign conversations someone replied to. untracked: conversations outside any campaign. important, snoozed, archived: as flagged in the dashboard - important spans the other folders. An email that belongs to no conversation is in no folder and matches none of these.

searchstring
Example:pricing question

Full-text search over subject, preview text and sender address. Supports quoted phrases, OR and -exclude.

latestOfThreadboolean
Example:true

Return one email per conversation: the most recent one that matches the rest of your filters. A cheap conversation-style view without fetching whole threads.

The filters are applied first, then the newest survivor of each conversation is kept – so latestOfThread=true&type=received gives you the last email each contact sent you, even in conversations you have already replied to. An email that belongs to no conversation is a conversation of one and is always kept.

sincestring
Example:2026-07-01T00:00:00.000Z
untilstring
Example:2026-07-14T00:00:00.000Z
sortOrder'asc' | 'desc'

Order by received date. Defaults to newest first.

Response

Example response

{
  "data": [
    {
      "id": "8c5a1e07-2b93-4d6f-a0e8-7c4b9d1f2a36",
      "threadId": "13a265fd-f0f2-b1d1-d6fc-154e483183e7",
      "messageId": "<CAF=abc123@mail.gmail.com>",
      "mailbox": {
        "id": "3f1c2b7e-9a4d-4c8e-b1f6-5d2a7e0c3b94",
        "email": "jane@acme.com"
      },
      "from": {
        "email": "john@prospect.io",
        "name": "John Carter"
      },
      "to": [
        "jane@acme.com"
      ],
      "cc": [],
      "bcc": [],
      "subject": "Re: Pricing question",
      "snippet": "Thanks for the details, this works for us.",
      "isUnread": true,
      "type": "received",
      "campaignId": "c1f3b0a2-6d4e-4f8b-9a1c-2e5d7f0a3b6c",
      "leadId": "9d4e2f10-5b6a-4c73-8e19-0f2a7c4d8b31",
      "receivedAt": "2026-07-13T09:24:11.000Z",
      "sentAt": "2026-07-13T09:24:09.000Z"
    }
  ],
  "meta": {
    "hasMore": true,
    "nextCursor": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0"
  }
}

Changes