Inbox & Reply Agents
Inbox
| Method | Path | Description |
|---|---|---|
GET | /replies | Flat list of replies. Query: page, limit, q, intent, campaignId, hasReminder |
GET | /replies/threads | Grouped by lead — one row per conversation, newest first |
GET | /replies/summary | Today/yesterday/earlier counts |
GET | /replies/unread-count | Unread replies in the workspace: { messages, conversations } |
GET | /replies/thread/:leadId | Full conversation: every outbound send plus every inbound reply, in order |
POST | /replies/thread/:leadId/read | Mark every reply in the conversation as read. Returns marked |
GET | /replies/attachments/:id | Download a file attached to a message in a conversation |
POST | /replies/uploads | Upload a file for a reply before sending it (raw bytes). Returns { id, filename, size } |
PATCH | /replies/:id/star | Star/unstar |
POST | /replies/:id/draft | AI-draft a response (consumes one AI credit; never sends) |
POST | /replies/:id/send | Send 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/retry | Send again a reply that failed (status: "FAILED"). Returns 202 |
POST | /replies/sent/:id/cancel | Cancel a reply still SCHEDULED. Returns { cancelled: true }; 409 if it already sent or is sending |
POST | /replies/:id/forward | Forward the original message to another address |
GET | /replies/:id/ooo-suggestion | Addresses to send to instead, read from an out-of-office / wrong-person reply: { alternateEmails, returnDate } |
POST | /replies/:id/ooo-forward | Re-send the original campaign email to alternate contact(s) the reply pointed to (see below) |
POST | /replies/:id/intent | Re-classify the conversation’s tag. Body { intent }; returns { intent } |
POST | /replies/:id/mark-handled | Mark a conversation handled without replying ({ handled: false } to undo) |
DELETE | /replies/:id/tag | Clear the conversation’s intent tag, setting the reply back to UNCLASSIFIED |
PATCH | /replies/:id/remind | Set (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, andfrom({ name, address }of who wrote it: the lead, or a colleague answering for them;nullon replies received before 1 Oct 2026).unreadCount: their replies in this conversation nobody has opened yet.answered:truewhen you replied after their latest message.lastAnsweredAtis 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, ornull),attachments,intentClassification,remindAtandstarred. - Your own replies (
kind: "reply") also havebcc,html,attachments,sentBy(HUMAN,APIorAGENT), andstatus:SENDING,SENTorFAILED(with the reason inerror). A reply written to go out later hasstatus: "SCHEDULED"with itsscheduledFortime; a cancelled one is dropped from the conversation. - Campaign emails (
kind: "campaign") also havecampaign.
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:
| Field | Description |
|---|---|
body | Required. The text of the reply |
html | Optional. The formatted version (bold, links, images). body stays the plain-text part |
to | Optional. Up to 20 addresses. Default: whoever wrote the message being answered (the lead, or a colleague who answered for them) |
cc, bcc | Optional. Up to 20 addresses each |
attachments | Optional. Up to 10 files, 20 MB in all: [{ filename, contentType, contentBase64, cid? }] |
uploadIds | Optional. Ids from POST /replies/uploads, sent as attachments. Counted in the same 20 MB |
background | Optional. true returns at once with 202 and sends in the background (see below) |
scheduledFor | Optional. 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:
| Field | Description |
|---|---|
emails | Required. 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
| Method | Path | Description |
|---|---|---|
GET | /ai-settings | Get workspace AI configuration |
PATCH | /ai-settings | Update aiClassificationEnabled, aiDraftEnabled, autoTagOnReply, customInstructions |
Reply agents
| Method | Path | Description |
|---|---|---|
GET | /reply-agents | List reply agents |
POST | /reply-agents | Create one: name, companyName?, companyDomain?, tone?, additionalInfo?, autonomousReplies?, followUpsEnabled?, replyPolicies?, preDraftOnArrival?, replySendWindowStart?, replySendWindowEnd?, replySendTimezone?, minAutoSendConfidence? |
GET / PATCH / DELETE | /reply-agents/:id | Get, update, or delete (PATCH takes the same optional fields) |
GET | /reply-agents/:id/documents | List trained documents |
POST | /reply-agents/:id/documents | Upload a document (filename, mimeType, contentBase64 — PDF/DOCX/TXT, max 10MB) |
DELETE | /reply-agents/:id/documents/:docId | Remove a document |
POST | /reply-agents/:id/search | Preview knowledge-base retrieval for a query |
POST | /reply-agents/:id/website/scan | Start a background crawl of a domain |
GET | /reply-agents/:id/website/scan | Poll crawl progress |
POST | /reply-agents/:id/website/index | Confirm 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.
| Intent | Allowed action values |
|---|---|
INTERESTED, QUESTION, INFORMATIONAL, CONVERSATION, UNCLASSIFIED | AUTO_SEND, DRAFT, IGNORE |
OUT_OF_OFFICE | SCHEDULE, DRAFT, IGNORE |
WRONG_PERSON | REFERRAL, DRAFT, IGNORE |
NOT_INTERESTED | DRAFT, IGNORE |
UNSUBSCRIBE_REQUEST | IGNORE |
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). AddtimeoutHours(1–720) andtimeoutAction(AUTO_SEND|ARCHIVE|NONE, defaultNONE) to auto-send or archive a draft nobody actioned in time.timeoutHours/timeoutActionare valid only withDRAFT.SCHEDULE(OUT_OF_OFFICEonly) — 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 toDRAFT.REFERRAL(WRONG_PERSONonly) — 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.