Email inbox
| Tool | What it does |
|---|---|
inbox_cancel_scheduled | Return one accessible scheduled inbox message to draft state. |
inbox_conversations_search | List inbox conversations using the owner’s tabs, filters and pagination. |
inbox_draft_reply | Save or update an inbox draft without sending it. |
inbox_get_thread | Get one accessible inbox thread, messages, contact and related threads. |
inbox_mark_done | Mark selected or matching accessible inbox threads done. |
inbox_redraft | Regenerate one accessible AI inbox draft through owner billing. |
inbox_reopen | Move selected or matching accessible threads back to Needs action. |
inbox_search | Search accessible inbox email with supported query operators. |
inbox_send | Send or schedule the exact approved inbox message. |
inbox_set_category | Set 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-cancel-scheduled |
| MCP tool | inbox_cancel_scheduled on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
email_message_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
inbox_conversations_search
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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-conversations-search |
| MCP tool | inbox_conversations_search on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | From 1 to any. Default 1. |
tab | string | Yes | ’needs_action’ | ‘done’ | ‘sent’ | ‘drafts’ |
filters | object | No | Composable 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-draft-reply |
| MCP tool | inbox_draft_reply on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
email_message_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
mailbox_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
to | array of string | No | |
cc | array of string | No | Finding #70 — Cc/extra recipients must survive a draft save, not just the primary To |
bcc | array of string | No | §8.8 Bcc recipients — same round-trip rule as Cc: a re-opened draft must not silently lose them |
subject | string | No | Default "". |
body | string | No | Default "". |
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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-get-thread |
| MCP tool | inbox_get_thread on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | From 1 to any. Default 1. |
thread_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
email_message_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
paginate_messages | boolean | No | Opt in to 25-message pages, newest page first; messages within each page remain chronological Default false. |
related_page | integer | No | Opt 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-mark-done |
| MCP tool | inbox_mark_done on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_oids | array of string | No | Up to 20000 items. |
voicemail_oids | array of string | No | Up to 20000 items. |
all_matching | boolean | No | Default false. |
tab | string | No | Only used when all_matching is set Default "needs_action". |
filters | object | No | Composable 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-redraft |
| MCP tool | inbox_redraft on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Can charge credits. At most 1 credits per item. The response’s charge field reports what was charged. |
| Permission | No role permission beyond API access. |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
email_message_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
confirm_overwrite | boolean | No | U26 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-reopen |
| MCP tool | inbox_reopen on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_oids | array of string | No | Up to 20000 items. |
voicemail_oids | array of string | No | Up to 20000 items. |
all_matching | boolean | No | Default false. |
tab | string | No | Only used when all_matching is set Default "needs_action". |
filters | object | No | Composable filter set — every group ANDs together. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
inbox_search
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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-search |
| MCP tool | inbox_search on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-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.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | From 1 to any. Default 1. |
query | string | No | Default "". |
refine_subject | boolean | No | Default true. |
refine_body | boolean | No | Default true. |
refine_contact | boolean | No | Default true. |
refine_addresses | boolean | No | Default 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-send |
| MCP tool | inbox_send on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_oid | string | No | Pattern ^[0-9a-fA-F]{24}$. |
mailbox_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
to | array of string | No | |
cc | array of string | No | |
bcc | array of string | No | §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. |
subject | string | No | Default "". |
body | string | No | Default "". |
send_mode | string | No | ’send’ | ‘send_and_done’ | ‘schedule’ Default "send". |
schedule_at | string | No | |
email_message_oid | string | No | The 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_oid | string | No | GS §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_variables | boolean | No | The 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.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/inbox-set-category |
| MCP tool | inbox_set_category on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
thread_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
category | string | Yes | One 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.