curl --request GET \
--url https://api.mailbeast.ai/v1/emails \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.mailbeast.ai/v1/emails"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.mailbeast.ai/v1/emails', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mailbeast.ai/v1/emails",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.mailbeast.ai/v1/emails"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mailbeast.ai/v1/emails")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mailbeast.ai/v1/emails")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "8c5a1e07-2b93-4d6f-a0e8-7c4b9d1f2a36",
"threadId": "13a265fd-f0f2-b1d1-d6fc-154e483183e7",
"messageId": "<[email protected]>",
"mailbox": {
"id": "3f1c2b7e-9a4d-4c8e-b1f6-5d2a7e0c3b94",
"email": "[email protected]"
},
"from": {
"email": "[email protected]",
"name": "John Carter"
},
"to": [
"[email protected]"
],
"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",
"subsequence": {
"id": "5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c",
"name": "Interested - book a call"
},
"hasAttachments": false,
"receivedAt": "2026-07-13T09:24:11.000Z",
"sentAt": "2026-07-13T09:24:09.000Z"
}
],
"meta": {
"hasMore": true,
"nextCursor": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0"
}
}{
"error": {
"type": "invalid_request_error",
"code": "validation_failed",
"message": "One or more fields are invalid.",
"status": 400,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f",
"details": [
"name should not be empty"
]
}
}{
"error": {
"type": "authentication_error",
"code": "unauthenticated",
"message": "Missing or invalid API key.",
"status": 401,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}{
"error": {
"type": "authorization_error",
"code": "permission_denied",
"message": "This API key is missing the required scope.",
"status": 403,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}{
"error": {
"type": "rate_limit_error",
"code": "rate_limited",
"message": "Too many requests. Retry after the interval in the Retry-After header.",
"status": 429,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f",
"retryAfter": 30
}
}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.
curl --request GET \
--url https://api.mailbeast.ai/v1/emails \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.mailbeast.ai/v1/emails"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.mailbeast.ai/v1/emails', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mailbeast.ai/v1/emails",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.mailbeast.ai/v1/emails"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mailbeast.ai/v1/emails")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mailbeast.ai/v1/emails")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "8c5a1e07-2b93-4d6f-a0e8-7c4b9d1f2a36",
"threadId": "13a265fd-f0f2-b1d1-d6fc-154e483183e7",
"messageId": "<[email protected]>",
"mailbox": {
"id": "3f1c2b7e-9a4d-4c8e-b1f6-5d2a7e0c3b94",
"email": "[email protected]"
},
"from": {
"email": "[email protected]",
"name": "John Carter"
},
"to": [
"[email protected]"
],
"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",
"subsequence": {
"id": "5b2f3c4d-6e7f-4a81-9b0c-1d2e3f4a5b6c",
"name": "Interested - book a call"
},
"hasAttachments": false,
"receivedAt": "2026-07-13T09:24:11.000Z",
"sentAt": "2026-07-13T09:24:09.000Z"
}
],
"meta": {
"hasMore": true,
"nextCursor": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0"
}
}{
"error": {
"type": "invalid_request_error",
"code": "validation_failed",
"message": "One or more fields are invalid.",
"status": 400,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f",
"details": [
"name should not be empty"
]
}
}{
"error": {
"type": "authentication_error",
"code": "unauthenticated",
"message": "Missing or invalid API key.",
"status": 401,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}{
"error": {
"type": "authorization_error",
"code": "permission_denied",
"message": "This API key is missing the required scope.",
"status": 403,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f"
}
}{
"error": {
"type": "rate_limit_error",
"code": "rate_limited",
"message": "Too many requests. Retry after the interval in the Retry-After header.",
"status": 429,
"requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f",
"retryAfter": 30
}
}Authorizations
Query Parameters
Filter by mailbox address, comma-separated. Addresses you do not own are ignored.
Return only emails whose conversation is in this folder - the same folders your team sees in the dashboard. inbox: campaign conversations someone replied to. A delivery failure notice (bounce) counts as a reply only until the lead is marked as bounced, so a conversation of a bounced lead with no real reply is not in inbox. 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.
inbox, untracked, important, snoozed, archived "inbox"
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.
true