Skip to Content
🚀 Sendbox is live — this documentation is a work in progress.
API ReferenceInbox & Reply Agents

Inbox & Reply Agents

Inbox

MethodPathDescription
GET/repliesFlat list of replies. Query: page, limit, q, intent, campaignId, hasReminder
GET/replies/threadsGrouped by lead — one row per conversation, newest first
GET/replies/summaryToday/yesterday/earlier counts
GET/replies/unread-countUnread replies in the workspace: { messages, conversations }
GET/replies/thread/:leadIdFull conversation: every outbound send plus every inbound reply, in order
POST/replies/thread/:leadId/readMark every reply in the conversation as read. Returns marked
GET/replies/attachments/:idDownload a file attached to a message in a conversation
POST/replies/uploadsUpload a file for a reply before sending it (raw bytes). Returns { id, filename, size }
PATCH/replies/:id/starStar/unstar
POST/replies/:id/draftAI-draft a response (consumes one AI credit; never sends)
POST/replies/:id/sendSend a real reply from the receiving mailbox, with chosen To / Cc / Bcc, formatting and files — or schedule it for later (see below)
POST/replies/sent/:id/retrySend again a reply that failed (status: "FAILED"). Returns 202
POST/replies/sent/:id/cancelCancel a reply still SCHEDULED. Returns { cancelled: true }; 409 if it already sent or is sending
POST/replies/:id/forwardForward the original message to another address
GET/replies/:id/ooo-suggestionAddresses to send to instead, read from an out-of-office / wrong-person reply: { alternateEmails, returnDate }
POST/replies/:id/ooo-forwardRe-send the original campaign email to alternate contact(s) the reply pointed to (see below)
POST/replies/:id/intentRe-classify the conversation’s tag. Body { intent }; returns { intent }
POST/replies/:id/mark-handledMark a conversation handled without replying ({ handled: false } to undo)
DELETE/replies/:id/tagClear the conversation’s intent tag, setting the reply back to UNCLASSIFIED
PATCH/replies/:id/remindSet (remindAt: ISO datetime) or clear (remindAt: null) a follow-up reminder

intent is one of: UNCLASSIFIED, INTERESTED, NOT_INTERESTED, OUT_OF_OFFICE, WRONG_PERSON, UNSUBSCRIBE_REQUEST, QUESTION.

OUT_OF_OFFICE is only for automatic replies: the message has Auto-Submitted, X-Autoreply or Precedence: auto_reply, a subject like “Automatic reply:” or “Out of Office”, or an unmistakable out-of-office phrase in its text. A reply a person wrote is not classified as OUT_OF_OFFICE.

Conversation list

Each row of GET /replies/threads has:

  • latestReply: id, rawBody, intentClassification, receivedAt, remindAt, starred, and from ({ name, address } of who wrote it: the lead, or a colleague answering for them; null on replies received before 1 Oct 2026).
  • unreadCount: their replies in this conversation nobody has opened yet.
  • answered: true when you replied after their latest message. lastAnsweredAt is when.
  • replyCount, lead, mailbox, campaign.

Conversation

GET /replies/thread/:leadId returns lead and messages, oldest first. Each message has direction (inbound or outbound), timestamp, subject, body, mailboxEmail, to and cc.

  • Inbound messages also have from, html (the HTML as received, or null), attachments, intentClassification, remindAt and starred.
  • Your own replies (kind: "reply") also have bcc, html, attachments, sentBy (HUMAN, API or AGENT), and status: SENDING, SENT or FAILED (with the reason in error). A reply written to go out later has status: "SCHEDULED" with its scheduledFor time; a cancelled one is dropped from the conversation.
  • Campaign emails (kind: "campaign") also have campaign.

Addresses are { name, address }. Each attachment is { id, filename, contentType, size }; download it with GET /replies/attachments/:id.

Received files are kept up to 15 MB per file and 25 MB per message. Inline images (such as a signature logo) are skipped.

Answers written directly in Gmail or Outlook are picked up from the mailbox’s Sent folder (IMAP mailboxes) and show in the conversation as your replies, with sentBy: "HUMAN".

Sending a reply

POST /replies/:id/send body:

FieldDescription
bodyRequired. The text of the reply
htmlOptional. The formatted version (bold, links, images). body stays the plain-text part
toOptional. Up to 20 addresses. Default: whoever wrote the message being answered (the lead, or a colleague who answered for them)
cc, bccOptional. Up to 20 addresses each
attachmentsOptional. Up to 10 files, 20 MB in all: [{ filename, contentType, contentBase64, cid? }]
uploadIdsOptional. Ids from POST /replies/uploads, sent as attachments. Counted in the same 20 MB
backgroundOptional. true returns at once with 202 and sends in the background (see below)
scheduledForOptional. A future ISO-8601 time. Writes the reply now and auto-sends it then instead of immediately (see below)

Set cid on an image shown inside html as src="cid:<cid>". It is then sent as an inline image.

For large files, upload them first with POST /replies/uploads while the reply is being written, then send their ids in uploadIds. The send then only sends the email. The upload body is the raw file with Content-Type: application/octet-stream; the file name goes in the X-Filename header (URL-encoded) and its type in X-Content-Type. An upload that is never sent is removed after a day.

curl -X POST https://api.sendboxes.tech/v1/replies/uploads \ -H "Authorization: Bearer sb_live_..." \ -H "Content-Type: application/octet-stream" \ -H "X-Filename: Pitch%20Deck.pdf" -H "X-Content-Type: application/pdf" \ --data-binary @"Pitch Deck.pdf"
curl -X POST https://api.sendboxes.tech/v1/replies/REPLY_ID/send \ -H "Authorization: Bearer sb_live_..." -H "Content-Type: application/json" \ -d '{ "body": "Thanks Sam, Tuesday works.", "to": ["[email protected]"], "cc": ["[email protected]"] }'

Returns { sent, sentReplyId, sentAt } once the mail server has accepted the reply. Attachments over 20 MB in all return 413.

With "background": true the request does not wait for the mail server, which can take up to a minute to accept a large attachment. It returns 202 with { queued, status: "SENDING", sentReplyId }. The reply shows in the conversation right away with status: "SENDING", then SENT, or FAILED with the reason in error. A failed reply is never sent again on its own: send it again with POST /replies/sent/:id/retry. A reply still SENDING after 10 minutes shows as FAILED and can be retried. The dashboard always sends this way.

Through an API key (and so over MCP), a reply can only go to people already in the conversation. Any other address in to, cc or bcc returns 403. In the dashboard you can address anyone.

Scheduling a reply for later

Add scheduledFor (a future ISO-8601 time) to POST /replies/:id/send to write the reply now and have it sent automatically at that time — a scheduled follow-up. Nothing is delivered immediately: the reply is stored with status: "SCHEDULED" and a background job (which runs every minute) sends it when the time arrives. The response is 202 with { scheduled: true, status: "SCHEDULED", scheduledFor, sentReplyId }. A scheduledFor in the past returns 400.

A scheduled reply does not count the conversation as answered until it actually goes out, so the “needs a reply” nudge and answered stay as they were. It shows in the conversation with status: "SCHEDULED" and its scheduledFor.

Cancel it before it goes out with POST /replies/sent/:id/cancel (the sentReplyId from the send response), which returns { cancelled: true }. Once the reply has started sending or has already sent, cancelling returns 409.

curl -X POST https://api.sendboxes.tech/v1/replies/REPLY_ID/send \ -H "Authorization: Bearer sb_live_..." -H "Content-Type: application/json" \ -d '{ "body": "Following up on the below.", "scheduledFor": "2026-10-20T09:00:00Z" }'

Out-of-office and wrong-person replies

When a reply is an out-of-office autoreply or says you reached the wrong person, two endpoints help you reach the right contact instead.

GET /replies/:id/ooo-suggestion reads the reply and returns { alternateEmails, returnDate } — the addresses it names (a personal address, a colleague to contact, the OOO cover contact) and any return date it mentions. Use it to confirm who to send to before forwarding. Either field may be empty when nothing is found.

POST /replies/:id/ooo-forward re-sends the original campaign email — the exact copy the lead received, from the same mailbox that sent it — to the alternate contact(s). Body:

FieldDescription
emailsRequired. 1–10 addresses to send the campaign copy to. De-duplicated

Each target is checked against the suppression list and skipped if blocked; an address that fails to send is also skipped. The response is { sent, skipped }, where skipped is [{ email, reason }]. If nothing was sent (all suppressed or failed), or the reply has no original campaign email to reproduce, it returns 422. Each send is recorded in the conversation as a sent reply. This sends real email and cannot be undone — confirm the recipients first.

curl -X POST https://api.sendboxes.tech/v1/replies/REPLY_ID/ooo-forward \ -H "Authorization: Bearer sb_live_..." -H "Content-Type: application/json" \ -d '{ "emails": ["[email protected]"] }'

Re-tagging a conversation

POST /replies/:id/intent sets the conversation’s intent tag by hand when the automatic classification was wrong, or to restore one cleared by accident. Body { intent } — one of the intent values listed under Inbox. It detaches the lead tag the old intent had attached, sets the new intent, and attaches the matching lead tag; UNCLASSIFIED just clears, the same as DELETE /replies/:id/tag. Returns { intent }.

AI settings

MethodPathDescription
GET/ai-settingsGet workspace AI configuration
PATCH/ai-settingsUpdate aiClassificationEnabled, aiDraftEnabled, autoTagOnReply, customInstructions

Reply agents

MethodPathDescription
GET/reply-agentsList reply agents
POST/reply-agentsCreate one: name, companyName?, companyDomain?, tone?, additionalInfo?, autonomousReplies?, followUpsEnabled?, replyPolicies?, preDraftOnArrival?, replySendWindowStart?, replySendWindowEnd?, replySendTimezone?, minAutoSendConfidence?
GET / PATCH / DELETE/reply-agents/:idGet, update, or delete (PATCH takes the same optional fields)
GET/reply-agents/:id/documentsList trained documents
POST/reply-agents/:id/documentsUpload a document (filename, mimeType, contentBase64 — PDF/DOCX/TXT, max 10MB)
DELETE/reply-agents/:id/documents/:docIdRemove a document
POST/reply-agents/:id/searchPreview knowledge-base retrieval for a query
POST/reply-agents/:id/website/scanStart a background crawl of a domain
GET/reply-agents/:id/website/scanPoll crawl progress
POST/reply-agents/:id/website/indexConfirm which discovered pages to actually train on

tone is one of: PROFESSIONAL, FRIENDLY, CASUAL, FORMAL.

Reply policy

replyPolicies is a JSON object keyed by reply intent; each value is { action, timeoutHours?, timeoutAction? }. It controls what autonomy does per intent. Omit it (or send null) to keep the default behavior: with autonomousReplies on, the agent sends INTERESTED, QUESTION, INFORMATIONAL, CONVERSATION and UNCLASSIFIED, and ignores the rest.

IntentAllowed action values
INTERESTED, QUESTION, INFORMATIONAL, CONVERSATION, UNCLASSIFIEDAUTO_SEND, DRAFT, IGNORE
OUT_OF_OFFICESCHEDULE, DRAFT, IGNORE
WRONG_PERSONREFERRAL, DRAFT, IGNORE
NOT_INTERESTEDDRAFT, IGNORE
UNSUBSCRIBE_REQUESTIGNORE
  • AUTO_SEND — compose and send unattended (still subject to the usual safety gate and, if set, the reply send window).
  • DRAFT — compose and park for a human (shows in the inbox as a ready draft). Add timeoutHours (1–720) and timeoutAction (AUTO_SEND | ARCHIVE | NONE, default NONE) to auto-send or archive a draft nobody actioned in time. timeoutHours / timeoutAction are valid only with DRAFT.
  • SCHEDULE (OUT_OF_OFFICE only) — read the return date from the auto-responder and schedule the reply for it; no parseable date, a past date, or one more than 60 days out falls back to DRAFT.
  • REFERRAL (WRONG_PERSON only) — send a short “who is the right person?” note.
  • IGNORE — do nothing.

The allow-list is enforced by the API — a request that, say, sets UNSUBSCRIBE_REQUEST to AUTO_SEND or NOT_INTERESTED to AUTO_SEND is rejected with 400. These floors exist because auto-replying to an opt-out or a “no” damages sending reputation, and auto-replying to an out-of-office immediately starts a mail loop.

{ "autonomousReplies": true, "replyPolicies": { "INTERESTED": { "action": "AUTO_SEND" }, "QUESTION": { "action": "DRAFT", "timeoutHours": 24, "timeoutAction": "AUTO_SEND" }, "OUT_OF_OFFICE": { "action": "SCHEDULE" }, "WRONG_PERSON": { "action": "REFERRAL" }, "NOT_INTERESTED": { "action": "IGNORE" } }, "replySendWindowStart": 9, "replySendWindowEnd": 18, "replySendTimezone": "Asia/Kolkata" }
curl -X PATCH https://api.sendboxes.tech/v1/reply-agents/AGENT_ID \ -H "Authorization: Bearer sb_live_..." \ -H "Content-Type: application/json" \ -d '{"replyPolicies":{"INTERESTED":{"action":"AUTO_SEND"},"OUT_OF_OFFICE":{"action":"SCHEDULE"}},"preDraftOnArrival":true}'

Draft on arrival. preDraftOnArrival: true makes the agent prepare a draft reply for every eligible new reply and park it for approval, without sending — even when autonomousReplies is off. Each draft costs one AI credit.

Reply send window. replySendWindowStart / replySendWindowEnd are hours 0–23 in replySendTimezone (an IANA name, e.g. Asia/Kolkata); outside the window an AUTO_SEND reply is held until it reopens. A window that wraps midnight (start > end, e.g. 20→6) is supported. Leave the pair unset to send any time. Drafts and scheduled out-of-office replies are never held by the window.

Confidence gate. minAutoSendConfidence is an integer 0–100 (or null = off, the default). When set, an AUTO_SEND or REFERRAL reply whose AI confidence falls below it is held as a parked DRAFT for a human instead of being sent — a shaky answer never goes out unattended. DRAFT, SCHEDULE and IGNORE are unaffected.

Wrong-person capture. When a WRONG_PERSON reply resolves to REFERRAL and the inbound message names a referred email address, the agent also captures that contact as a new lead in your workspace (deduplicated by email) alongside sending the referral note — so the right person is not lost. For the manual equivalent in the inbox, see the MCP tools send_to_alternate and suggest_alternate_recipients.