Unibox

Reply threads from every mailbox, labels and answers. 6 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.

Unibox counts by label, mailbox and campaign

GET/api/v1/unibox/filters

MCP tool get_unibox_filtersRead-only

Returns

allrequirednumber
unreadrequirednumber
unlabeledrequirednumber
labelsrequiredobject[]
mailboxesrequiredobject[]
campaignsrequiredobject[]
aiLabelsrequiredboolean: Whether replies are labeled by AI in this workspace

cURL

curl https://ballast.to/api/v1/unibox/filters \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Reply threads, newest first

GET/api/v1/unibox/threads

Filter by unread, label, mailbox or campaign. Page with `cursor` from the previous answer.

MCP tool list_threadsRead-only

Parameters

viewquery · "all" | "unread"
labelIdquery · string: A label id, or "none" for threads without a label
mailboxIdquery · string
campaignIdquery · string
searchquery · string: Matches the lead's email, name or company, and the subject
cursorquery · string

Returns

threadsrequiredobject[]
nextCursorrequiredstring | null

cURL

curl https://ballast.to/api/v1/unibox/threads \
  -H "Authorization: Bearer $BALLAST_API_KEY"

A thread with every message, the campaign emails and the lead

GET/api/v1/unibox/threads/{id}

MCP tool get_threadRead-only

Parameters

idrequiredpath · string

Returns

idrequiredstring
subjectrequiredstring
snippetrequiredstring
unreadrequiredboolean
lastMessageAtrequiredstring
messagesrequirednumber: Replies and answers, campaign emails not counted
labelrequiredobject | null
labelSourcerequired"ai" | "rules" | "user" | "api" | null
leadrequiredobject
mailboxrequiredobject
campaignrequiredobject | null
labelReasonrequiredstring | null
itemsrequiredobject[]
sequencerequiredobject | null: Where the lead is in the campaign
replyTorequiredstring
replySubjectrequiredstring

cURL

curl https://ballast.to/api/v1/unibox/threads/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Mark a thread read or unread

POST/api/v1/unibox/threads/{id}/read

MCP tool mark_thread_read

Parameters

idrequiredpath · string
unreadboolean

Returns

okrequiredtrue

cURL

curl -X POST https://ballast.to/api/v1/unibox/threads/<id>/read \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unread":true}'

Set or clear a thread's label

POST/api/v1/unibox/threads/{id}/label

The lead gets the label for the thread's campaign and the label's triggers run (suppress, stop in campaign, pause campaign, move to list). null clears it.

MCP tool label_thread

Parameters

idrequiredpath · string
labelIdrequiredstring | null

Returns the same fields as A thread with every message, the campaign emails and the lead.

cURL

curl -X POST https://ballast.to/api/v1/unibox/threads/<id>/label \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labelId":{}}'

Answer a thread

POST/api/v1/unibox/threads/{id}/reply

Sends from the mailbox the conversation is on, in the same thread (In-Reply-To and References), to whoever wrote last. The previous message is quoted below.

MCP tool send_replyNeeds an active planMCP asks to confirm

Parameters

idrequiredpath · string
textrequiredstring

Returns the same fields as A thread with every message, the campaign emails and the lead.

cURL

curl -X POST https://ballast.to/api/v1/unibox/threads/<id>/reply \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<text>"}'

API reference

Unibox

Reply threads from every mailbox, labels and answers. 6 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.

Unibox counts by label, mailbox and campaign

GET/api/v1/unibox/filters

MCP tool get_unibox_filtersRead-only

Returns

allrequirednumber
unreadrequirednumber
unlabeledrequirednumber
labelsrequiredobject[]
mailboxesrequiredobject[]
campaignsrequiredobject[]
aiLabelsrequiredboolean: Whether replies are labeled by AI in this workspace

cURL

curl https://ballast.to/api/v1/unibox/filters \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Reply threads, newest first

GET/api/v1/unibox/threads

Filter by unread, label, mailbox or campaign. Page with `cursor` from the previous answer.

MCP tool list_threadsRead-only

Parameters

viewquery · "all" | "unread"
labelIdquery · string: A label id, or "none" for threads without a label
mailboxIdquery · string
campaignIdquery · string
searchquery · string: Matches the lead's email, name or company, and the subject
cursorquery · string

Returns

threadsrequiredobject[]
nextCursorrequiredstring | null

cURL

curl https://ballast.to/api/v1/unibox/threads \
  -H "Authorization: Bearer $BALLAST_API_KEY"

A thread with every message, the campaign emails and the lead

GET/api/v1/unibox/threads/{id}

MCP tool get_threadRead-only

Parameters

idrequiredpath · string

Returns

idrequiredstring
subjectrequiredstring
snippetrequiredstring
unreadrequiredboolean
lastMessageAtrequiredstring
messagesrequirednumber: Replies and answers, campaign emails not counted
labelrequiredobject | null
labelSourcerequired"ai" | "rules" | "user" | "api" | null
leadrequiredobject
mailboxrequiredobject
campaignrequiredobject | null
labelReasonrequiredstring | null
itemsrequiredobject[]
sequencerequiredobject | null: Where the lead is in the campaign
replyTorequiredstring
replySubjectrequiredstring

cURL

curl https://ballast.to/api/v1/unibox/threads/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Mark a thread read or unread

POST/api/v1/unibox/threads/{id}/read

MCP tool mark_thread_read

Parameters

idrequiredpath · string
unreadboolean

Returns

okrequiredtrue

cURL

curl -X POST https://ballast.to/api/v1/unibox/threads/<id>/read \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unread":true}'

Set or clear a thread's label

POST/api/v1/unibox/threads/{id}/label

The lead gets the label for the thread's campaign and the label's triggers run (suppress, stop in campaign, pause campaign, move to list). null clears it.

MCP tool label_thread

Parameters

idrequiredpath · string
labelIdrequiredstring | null

Returns the same fields as A thread with every message, the campaign emails and the lead.

cURL

curl -X POST https://ballast.to/api/v1/unibox/threads/<id>/label \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labelId":{}}'

Answer a thread

POST/api/v1/unibox/threads/{id}/reply

Sends from the mailbox the conversation is on, in the same thread (In-Reply-To and References), to whoever wrote last. The previous message is quoted below.

MCP tool send_replyNeeds an active planMCP asks to confirm

Parameters

idrequiredpath · string
textrequiredstring

Returns the same fields as A thread with every message, the campaign emails and the lead.

cURL

curl -X POST https://ballast.to/api/v1/unibox/threads/<id>/reply \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<text>"}'