curl -X GET "https://api.wirebox.sh/api/v1/mailboxes/eva/messages?limit=20" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
from wirebox import Wirebox
with Wirebox() as wirebox:
eva = wirebox.get_identity("eva")
for msg in eva.iter_emails():
print(f"[{msg.from_address}] {msg.subject}: {msg.snippet}")
import { Wirebox } from "@wirebox-sh/sdk";
const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const { messages } = await eva.listMessages({ limit: 20 });
for (const msg of messages) {
console.log(`[${msg.from}] ${msg.subject}: ${msg.snippet}`);
}
wirebox mail list --identity eva
{
"messages": [
{
"id": "msg_01J8ABC123XYZ",
"thread_id": "thrd_01J8XYZ987ABC",
"direction": "inbound",
"from": "alex@example.com",
"to": ["eva@wireboxmail.com"],
"subject": "Question regarding my API quota",
"snippet": "Hi Eva, how can I increase my monthly quota?",
"is_read": false,
"is_starred": false,
"has_attachments": false,
"created_at": "2026-09-11T12:00:00Z"
}
],
"next_cursor": null,
"has_more": false
}
Mail
List & Search Messages
List email message summaries in a mailbox, or search them by relevance.
GET
/
api
/
v1
/
mailboxes
/
{email_address}
/
messages
curl -X GET "https://api.wirebox.sh/api/v1/mailboxes/eva/messages?limit=20" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
from wirebox import Wirebox
with Wirebox() as wirebox:
eva = wirebox.get_identity("eva")
for msg in eva.iter_emails():
print(f"[{msg.from_address}] {msg.subject}: {msg.snippet}")
import { Wirebox } from "@wirebox-sh/sdk";
const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const { messages } = await eva.listMessages({ limit: 20 });
for (const msg of messages) {
console.log(`[${msg.from}] ${msg.subject}: ${msg.snippet}`);
}
wirebox mail list --identity eva
{
"messages": [
{
"id": "msg_01J8ABC123XYZ",
"thread_id": "thrd_01J8XYZ987ABC",
"direction": "inbound",
"from": "alex@example.com",
"to": ["eva@wireboxmail.com"],
"subject": "Question regarding my API quota",
"snippet": "Hi Eva, how can I increase my monthly quota?",
"is_read": false,
"is_starred": false,
"has_attachments": false,
"created_at": "2026-09-11T12:00:00Z"
}
],
"next_cursor": null,
"has_more": false
}
Path Parameters
string
required
Full mailbox address (
eva@wireboxmail.com) or local agent handle (eva).Query Parameters
integer
default:"50"
Number of messages to return (1–100).
boolean
Filter by read state:
true returns read messages, false returns unread messages.Response
object[]
Message summaries ordered by
created_at descending.string
Unique message identifier (
msg_ prefix).string
Conversation thread this message belongs to.
string
inbound or outbound.string
Sender email address.
string[]
Recipient email addresses.
string
Subject line.
string
Short preview of the message body.
boolean
Whether the message has been read.
boolean
Whether the message is starred.
boolean
Whether the message has attachments.
string
ISO 8601 creation timestamp.
string | null
Pagination cursor. Reserved for future use; currently always
null.boolean
Whether more messages are available. Reserved for future use; currently always
false.curl -X GET "https://api.wirebox.sh/api/v1/mailboxes/eva/messages?limit=20" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
from wirebox import Wirebox
with Wirebox() as wirebox:
eva = wirebox.get_identity("eva")
for msg in eva.iter_emails():
print(f"[{msg.from_address}] {msg.subject}: {msg.snippet}")
import { Wirebox } from "@wirebox-sh/sdk";
const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const { messages } = await eva.listMessages({ limit: 20 });
for (const msg of messages) {
console.log(`[${msg.from}] ${msg.subject}: ${msg.snippet}`);
}
wirebox mail list --identity eva
{
"messages": [
{
"id": "msg_01J8ABC123XYZ",
"thread_id": "thrd_01J8XYZ987ABC",
"direction": "inbound",
"from": "alex@example.com",
"to": ["eva@wireboxmail.com"],
"subject": "Question regarding my API quota",
"snippet": "Hi Eva, how can I increase my monthly quota?",
"is_read": false,
"is_starred": false,
"has_attachments": false,
"created_at": "2026-09-11T12:00:00Z"
}
],
"next_cursor": null,
"has_more": false
}
Search Messages
Runs a full-text search across the mailbox — subject, body, sender, and snippet — and returns matches ranked by relevance. Each result uses the same message shape as the list endpoint, plus ahighlight fragment around the best match when available.
Path Parameters
string
required
Full mailbox address (
eva@wireboxmail.com) or local agent handle (eva).Query Parameters
string
required
Search terms. Required — an empty query returns
400 invalid_request.integer
default:"50"
Maximum number of matches to return (1–100).
Response
object[]
Matching messages, ranked by relevance.
object[]
The same array as
items, kept for compatibility with the list endpoint.integer
Number of matches returned.
- Each result includes
highlightandhighlights.textwhen the search engine can produce a highlighted fragment; substring fallback matches omit them. - MCP clients can run the same search with the
wirebox_mail_searchtool — see the MCP.
curl -X GET "https://api.wirebox.sh/api/v1/mailboxes/eva/search?q=invoice%20overdue&limit=10" \
-H "Authorization: Bearer $WIREBOX_API_KEY"
from wirebox import Wirebox
with Wirebox() as wirebox:
eva = wirebox.get_identity("eva")
for match in eva.search_messages(q="invoice overdue", limit=10):
print(f"[{match.from_address}] {match.subject}")
print(match.highlight or match.snippet)
import { Wirebox } from "@wirebox-sh/sdk";
const wirebox = new Wirebox();
const eva = await wirebox.getIdentity("eva");
const { messages, count } = await eva.searchMessages({ q: "invoice overdue", limit: 10 });
for (const match of messages) {
console.log(`[${match.from}] ${match.subject}`);
console.log(match.highlight ?? match.snippet);
}
wirebox mail search --identity eva --query "invoice overdue" --limit 10
{
"items": [
{
"id": "msg_01J8ABC123XYZ",
"thread_id": "thrd_01J8XYZ987ABC",
"direction": "inbound",
"from": "alex@example.com",
"from_address": "alex@example.com",
"to": ["eva@wireboxmail.com"],
"to_addresses": ["eva@wireboxmail.com"],
"subject": "Question regarding my API quota",
"snippet": "Hi Eva, invoice #1042 is now overdue.",
"highlight": "Hi Eva, <b>invoice</b> #1042 is now <b>overdue</b>.",
"highlights": {
"text": ["Hi Eva, <b>invoice</b> #1042 is now <b>overdue</b>."]
},
"is_read": false,
"is_starred": false,
"has_attachments": false,
"created_at": "2026-09-11T12:00:00Z"
}
],
"messages": [
{
"id": "msg_01J8ABC123XYZ",
"thread_id": "thrd_01J8XYZ987ABC",
"direction": "inbound",
"from": "alex@example.com",
"from_address": "alex@example.com",
"to": ["eva@wireboxmail.com"],
"to_addresses": ["eva@wireboxmail.com"],
"subject": "Question regarding my API quota",
"snippet": "Hi Eva, invoice #1042 is now overdue.",
"is_read": false,
"is_starred": false,
"has_attachments": false,
"created_at": "2026-09-11T12:00:00Z"
}
],
"count": 1,
"next_cursor": null,
"has_more": false
}