Skip to Content
Tools referenceEmail inbox

Email inbox

ToolWhat it does
inbox_cancel_scheduledReturn one accessible scheduled inbox message to draft state.
inbox_conversations_searchList inbox conversations using the owner’s tabs, filters and pagination.
inbox_draft_replySave or update an inbox draft without sending it.
inbox_get_threadGet one accessible inbox thread, messages, contact and related threads.
inbox_mark_doneMark selected or matching accessible inbox threads done.
inbox_redraftRegenerate one accessible AI inbox draft through owner billing.
inbox_reopenMove selected or matching accessible threads back to Needs action.
inbox_searchSearch accessible inbox email with supported query operators.
inbox_sendSend or schedule the exact approved inbox message.
inbox_set_categorySet or clear one inbox thread’s category.

inbox_cancel_scheduled

Return one accessible scheduled inbox message to draft state.

Cancel an email that is currently scheduled to send later, before it goes out. The message is flipped back to an editable draft — content and recipients are preserved, nothing is lost.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-cancel-scheduled
MCP toolinbox_cancel_scheduled on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
email_message_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

List inbox conversations using the owner’s tabs, filters and pagination.

Search/filter the team’s email conversations by queue tab (needs_action/done/sent/drafts), mailbox, category, read state, sequence, contact stage/contact, source, or date range. For free-text search across subject/body/contact/addresses, use inbox_search instead — that is a separate endpoint.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-conversations-search
MCP toolinbox_conversations_search on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
pageintegerNoFrom 1 to any. Default 1.
tabstringYes’needs_action’ | ‘done’ | ‘sent’ | ‘drafts’
filtersobjectNoComposable filter set — every group ANDs together.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

inbox_draft_reply

Save or update an inbox draft without sending it.

Save or update a reply/compose draft — recipients, subject, body — without sending it. Pass an existing email_message_oid to update that draft in place, or omit it to create a new one on a given mailbox/thread.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-draft-reply
MCP toolinbox_draft_reply on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
thread_oidstringNoPattern ^[0-9a-fA-F]{24}$.
email_message_oidstringNoPattern ^[0-9a-fA-F]{24}$.
mailbox_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
toarray of stringNo
ccarray of stringNoFinding #70 — Cc/extra recipients must survive a draft save, not just the primary To
bccarray of stringNo§8.8 Bcc recipients — same round-trip rule as Cc: a re-opened draft must not silently lose them
subjectstringNoDefault "".
bodystringNoDefault "".

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

inbox_get_thread

Get one accessible inbox thread, messages, contact and related threads.

Get a full email conversation: every message in the thread (sender, recipient, subject, body), the linked contact’s compact profile, and other threads with the same contact. Use to read a conversation before drafting a reply or answering a question about it.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-get-thread
MCP toolinbox_get_thread on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
pageintegerNoFrom 1 to any. Default 1.
thread_oidstringNoPattern ^[0-9a-fA-F]{24}$.
email_message_oidstringNoPattern ^[0-9a-fA-F]{24}$.
paginate_messagesbooleanNoOpt in to 25-message pages, newest page first; messages within each page remain chronological Default false.
related_pageintegerNoOpt in to a 25-conversation page of related links From 1 to any.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

inbox_mark_done

Mark selected or matching accessible inbox threads done.

Mark one or more conversations as Done, moving them out of the Needs action queue. A pure local status flip — Prospeo never writes this back to the real mailbox — fully reversible with inbox_reopen at any time.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-mark-done
MCP toolinbox_mark_done on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
thread_oidsarray of stringNoUp to 20000 items.
voicemail_oidsarray of stringNoUp to 20000 items.
all_matchingbooleanNoDefault false.
tabstringNoOnly used when all_matching is set Default "needs_action".
filtersobjectNoComposable filter set — every group ANDs together.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

inbox_redraft

Regenerate one accessible AI inbox draft through owner billing.

Regenerate an AI-drafted reply with a fresh generation from the same inbound message, thread context, and the reply rule’s guidance. Charges 1 credit only if generation actually succeeds — a hard failure is refunded automatically, never billed.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-redraft
MCP toolinbox_redraft on https://mcp.prospeo.io
EffectChanges data.
CreditsCan charge credits. At most 1 credits per item. The response’s charge field reports what was charged.
PermissionNo role permission beyond API access.
ConfirmationRecommended: MCP clients should confirm with the user before calling.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
email_message_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
confirm_overwritebooleanNoU26 regen-lock: required True once the draft has been manually edited Default false.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

inbox_reopen

Move selected or matching accessible threads back to Needs action.

Move one or more Done conversations back to Needs action. A pure local status flip, undoing inbox_mark_done at any time.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-reopen
MCP toolinbox_reopen on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
thread_oidsarray of stringNoUp to 20000 items.
voicemail_oidsarray of stringNoUp to 20000 items.
all_matchingbooleanNoDefault false.
tabstringNoOnly used when all_matching is set Default "needs_action".
filtersobjectNoComposable filter set — every group ANDs together.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

Search accessible inbox email with supported query operators.

Free-text search across the team’s visible email conversations — subject, body, contact name, and email addresses. Supports inline ‘key:value’ operators for precise filtering.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-search
MCP toolinbox_search on https://mcp.prospeo.io
EffectReads data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationPage-based: page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
pageintegerNoFrom 1 to any. Default 1.
querystringNoDefault "".
refine_subjectbooleanNoDefault true.
refine_bodybooleanNoDefault true.
refine_contactbooleanNoDefault true.
refine_addressesbooleanNoDefault true.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

inbox_send

Send or schedule the exact approved inbox message.

Send an email from a connected mailbox — a brand-new message, a reply on an existing thread, or consuming a pending draft. Sends immediately through the real mail provider and cannot be recalled, so always confirm recipients and content with the user first. Supports send now, send-and-mark-done, or schedule for later.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-send
MCP toolinbox_send on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationRecommended: MCP clients should confirm with the user before calling.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
thread_oidstringNoPattern ^[0-9a-fA-F]{24}$.
mailbox_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
toarray of stringNo
ccarray of stringNo
bccarray of stringNo§8.8 single-email view Bcc recipients. Blind by design: DNC-checked and put on the envelope, but never added to the thread’s participant set.
subjectstringNoDefault "".
bodystringNoDefault "".
send_modestringNo’send’ | ‘send_and_done’ | ‘schedule’ Default "send".
schedule_atstringNo
email_message_oidstringNoThe draft (AI or user) being consumed by this send — RR §5.3: sending flips it to SENT in place instead of leaving a phantom DRAFT row. Pattern ^[0-9a-fA-F]{24}$.
saved_person_oidstringNoGS §6.2 — the contact this email’s {{variables}} resolve against on a FRESH compose, which has no thread to derive one from. A reply ignores it and uses the thread’s own contact instead. Pattern ^[0-9a-fA-F]{24}$.
allow_empty_variablesbooleanNoThe rep saw the empty-variable warning at send time and chose to send anyway — those slots render BLANK rather than holding the send. Never braces on either branch. Default false.

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

inbox_set_category

Set or clear one inbox thread’s category.

Manually set (or clear, via the ‘UNCATEGORIZED’ sentinel) a conversation’s reply category, overriding the AI classification permanently.

EndpointPOST https://api.prospeo.io/api/v2/tools/inbox-set-category
MCP toolinbox_set_category on https://mcp.prospeo.io
EffectChanges data.
CreditsFree, uses no credits.
PermissionNo role permission beyond API access.
ConfirmationNot needed.
PaginationReturns one page.

Request

Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.

ParameterTypeRequiredDescription
thread_oidstringYesMongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$.
categorystringYesOne of the 5 locked ReplyCategory values, or the ‘UNCATEGORIZED’ sentinel (C-8) which clears Category/CategorySource back to unset

Response

{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.

Last updated on