curl --request GET \
--url https://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails \
--header 'x-api-key: <api-key>'import requests
url = "https://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://console.mermail.app/api/v1/mailboxes/{mailboxId}/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://console.mermail.app/api/v1/mailboxes/{mailboxId}/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 => [
"x-api-key: <api-key>"
],
]);
$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://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"emails": [
{
"id": "msg_7f3a2c1b",
"subject": "Order question",
"sender": "[email protected]",
"recipient": "[email protected]",
"cc": null,
"bcc": null,
"date": "2026-07-14T09:00:00.000Z",
"read": false,
"starred": false,
"is_urgent": false,
"category": "customer_support",
"body": "Hi, where is my order?",
"folder_id": "INBOX",
"folder_name": "Inbox",
"thread_id": "thr_9aabb",
"snippet": "Hi, where is my order?",
"scan_status": null,
"attachments": []
}
],
"totalCount": 42
}{
"error": "Unauthorized"
}{
"error": "Invalid request"
}{
"error": "Forbidden"
}{
"error": "Too many requests"
}List emails
Plans: Free · Developer · Enterprise
Lists emails in a mailbox. Set metadata_only=true for candidate discovery, require_scan_status=clean to exclude non-clean candidates, and agent_safe_content=true to remove sensitive metadata and normalize untrusted text to bounded plain text. Use include_held=true only for an explicitly scoped verification flow. All safe-read controls are optional and preserve the existing full response by default. When folder or is_starred is set, the response is { emails, totalCount }; otherwise a bare array may be returned.
API credits: 1 (read).
curl --request GET \
--url https://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails \
--header 'x-api-key: <api-key>'import requests
url = "https://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://console.mermail.app/api/v1/mailboxes/{mailboxId}/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://console.mermail.app/api/v1/mailboxes/{mailboxId}/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 => [
"x-api-key: <api-key>"
],
]);
$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://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://console.mermail.app/api/v1/mailboxes/{mailboxId}/emails")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"emails": [
{
"id": "msg_7f3a2c1b",
"subject": "Order question",
"sender": "[email protected]",
"recipient": "[email protected]",
"cc": null,
"bcc": null,
"date": "2026-07-14T09:00:00.000Z",
"read": false,
"starred": false,
"is_urgent": false,
"category": "customer_support",
"body": "Hi, where is my order?",
"folder_id": "INBOX",
"folder_name": "Inbox",
"thread_id": "thr_9aabb",
"snippet": "Hi, where is my order?",
"scan_status": null,
"attachments": []
}
],
"totalCount": 42
}{
"error": "Unauthorized"
}{
"error": "Invalid request"
}{
"error": "Forbidden"
}{
"error": "Too many requests"
}Authorizations
API key (sk-proj-…) from Settings → API Keys. Required for sold API calls outside the Mermail console.
Path Parameters
Mailbox public_id (UUID), hosted alias id, or current email
Query Parameters
Folder id
Filter by thread id
Email category
customer_support, technical, partnership, other Custom label slug
true/1 or false/0
true/1 or false/0
Set to true/1 to aggregate by thread
Set to true to omit body, snippet, raw headers, and threat URLs from returned email items
Set to true only for a scoped verification flow that must inspect messages temporarily held for auto-draft processing
Require the exact stored scan status; non-matching messages are excluded
clean, flagged, skipped Set to true to omit raw headers, provider metadata, threat details, attachment metadata, and storage diagnostics, and to normalize untrusted text fields to bounded plain text. The response retains attachment_count and remains untrusted.
Page number (≥1)
x >= 1Page size (1–100, default 25)
1 <= x <= 100Sort column
id, subject, sender, recipient, date, read, starred ASC for ascending; otherwise descending
Response
Email list
Hide child attributes
Hide child attributes
Authoritative Mermail email id. Use this value as the emailId path argument and for pre-wait baselines.
Present on list and search responses
Full body on detail responses unless metadata_only=true; list/search responses can contain a preview
Provider or RFC Message-ID metadata, retained only as secondary correlation. Do not use it in place of the Mermail id for resource paths or new baselines.
Untrusted raw provider headers. Do not use headers alone as authorization.
Content scan outcome. Treat flagged as unsafe and skipped as unknown.
clean, flagged, skipped, null Sender-authentication verdict derived only from a trusted receiving-provider signal. Raw Authentication-Results and From headers are never promoted to trusted evidence. The current connected providers do not expose a documented per-message verdict, so status is unknown; unknown is not a pass.
Hide child attributes
Hide child attributes
pass, fail, unknown pass, fail, unknown pass, fail, unknown pass, fail, unknown Trusted transport source recorded by Mermail; this is not itself a sender verdict.
cloudflare_routing, resend, null provider_sender_authentication_verdict_unavailable, inbound_provider_unavailable True when metadata_only or an agent-safe scan gate omitted body, snippet, raw headers, and threat URLs
Why an agent-safe detail or context response omitted body content
scan_status_not_clean True when max_body_chars shortened the returned body
Original stored body character count, present when the returned body was truncated
x >= 0True when raw headers, provider metadata, threat details, attachment metadata, and storage diagnostics were omitted and untrusted text fields were normalized to bounded plain text. This projection does not make email content trusted.
Attachment count retained when agent_safe_content=true omits attachment metadata
x >= 0Was this page helpful?