Inboxes
Shared inboxes over the API: inboxes, labels, threads and their emails, drafts and the AI agent settings.
An inbox is one address on a domain you can send from. Mail to it is kept as threads (conversations) that you can file in folders (inbox, archive, spam, trash), label and assign to a teammate. Each thread's messages stay under Emails too — deleting a thread or an inbox never deletes the mail.
Reads need an API key with read access; changes and sends need a full-access key (a sending-only key cannot reach inbox mail). Errors use the usual { statusCode, name, message } shape; inbox errors add a code such as receiving_choice_required or address_taken.
inbox.created, inbox.updated, inbox.deleted, inbox.email.received, inbox.email.sent, inbox.thread.created, inbox.thread.assigned, inbox.thread.unassigned, inbox.thread.folder.updated, inbox.thread.labels.updated, inbox.draft.created, inbox.draft.updated, inbox.draft.deleted and inbox.draft.sent. Each carries the object as this page shows it. Mail flagged as spam on arrival is filed silently.Create inbox
/inboxesThe domain must be verified for sending. When it does not receive mail yet, say how the inbox should receive: domain turns receiving on (add the MX record from the domain page), forward gives the inbox an address to forward an existing mailbox to.
email_addressstringrequiredThe full address. Or send local plus domain_id.
namestringoptionalA display name for the inbox.
from_namestringoptionalThe name recipients see on mail sent from it.
receiving'domain' | 'forward'optionalRequired only when the domain does not receive mail yet.
402 inbox_limit_reached with the usual limit details, unless pay-as-you-go is on.{
"object": "inbox",
"id": "inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a",
"address": "support@example.com",
"name": "Customer support",
"from_name": "Ada from Support",
"view_mode": "list",
"domain_id": "4dd369bc-aa82-4ff3-97de-514ae3000ee0",
"domain": "example.com",
"receiving": "ready",
"forward_address": null,
"unread": 3,
"drafts": 1,
"last_received_at": "2026-11-20T09:14:00.000Z",
"created_at": "2026-11-01T12:00:00.000Z"
}const res = await fetch('https://www.senddart.com/api/inboxes', {
method: 'POST',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"email_address": "support@example.com",
"name": "Customer support",
"from_name": "Ada from Support"
}),
});
const data = await res.json();
console.log(data);Retrieve inbox
/inboxes/:inbox_idOne inbox, with its unread and draft counts.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);List inboxes
/inboxesNewest first, as { object: "list", has_more, data }.
limitnumberoptional1–100. Omit to get every row (up to 1,000).
afterstringoptionalId of the last row of the previous page.
beforestringoptionalId of the first row of the next page. Not with after.
const res = await fetch('https://www.senddart.com/api/inboxes', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Update inbox
/inboxes/:inbox_idChange name, from_name or view_mode (list, grouped or board). Answers the updated inbox.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"name": "Support",
"from_name": "Ada from Support"
}),
});
const data = await res.json();
console.log(data);Delete inbox
/inboxes/:inbox_idRemoves the inbox with its threads, labels and drafts. Answers { object: "inbox", id, deleted: true }.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a', {
method: 'DELETE',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Create label
/inboxes/:inbox_id/labelsNames are unique per inbox, ignoring case. color is one of gray, red, orange, amber, green, teal, blue, violet or pink (default gray).
{ "object": "inbox_label", "id": "lbl_5c2e9a1d7b4f8e3c6a0d2b9f1e4c", "inbox_id": "inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a", "name": "Urgent", "color": "red", "threads": 0 }const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/labels', {
method: 'POST',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"name": "Urgent",
"color": "red"
}),
});
const data = await res.json();
console.log(data);List labels
/inboxes/:inbox_id/labelsEvery label, by name, with how many threads carry it.
limitnumberoptional1–100. Omit to get every row (up to 1,000).
afterstringoptionalId of the last row of the previous page.
beforestringoptionalId of the first row of the next page. Not with after.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/labels', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Update label
/inboxes/:inbox_id/labels/:label_idChange name and/or color. Answers the label.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/labels/lbl_5c2e9a1d7b4f8e3c6a0d2b9f1e4c', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"color": "orange"
}),
});
const data = await res.json();
console.log(data);Delete label
/inboxes/:inbox_id/labels/:label_idTakes the label off every thread; the threads stay.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/labels/lbl_5c2e9a1d7b4f8e3c6a0d2b9f1e4c', {
method: 'DELETE',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);List threads
/inboxes/:inbox_id/threadsOne page of conversations, most recently active first. Page forward with after (the last thread id).
folderstringoptionalinbox (default), sent, archive, spam or trash.
labelstringoptionalOnly threads carrying this label id.
querystringoptionalSearch words and operators: from: to: label: has:attachment is:unread is:assigned after:YYYY-MM-DD before:YYYY-MM-DD.
from, tostringoptionalComma-separated addresses.
start_date, end_dateYYYY-MM-DDoptionalLast activity on or after / before these days.
unreadbooleanoptionalOnly unread (true) or read (false) threads.
limit, afternumber, stringoptionalPage size (1–100, default 20) and cursor.
{ "object": "list", "has_more": false, "data": [{
"object": "inbox_thread",
"id": "thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d",
"inbox_id": "inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a",
"subject": "Refund for order 1041",
"snippet": "Hi, I was charged twice for…",
"participants": [{ "a": "carol@example.org", "n": "Carol" }],
"folder": "inbox",
"unread": true,
"assignee": null,
"messages": 2,
"sent_only": false,
"has_attachments": false,
"has_draft": false,
"labels": [{ "id": "lbl_5c2e9a1d7b4f8e3c6a0d2b9f1e4c", "name": "Billing", "color": "amber" }],
"column": null,
"last_message_at": "2026-11-20T09:14:00.000Z",
"trashed_at": null
}] }const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads?folder=inbox&limit=20', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Search threads
/inboxes/:inbox_id/threads/searchThe same list and parameters. A search or a label looks across Inbox, Sent and Archive unless folder is spam or trash.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/search?query=invoice&from=carol@example.org&start_date=2026-09-01&limit=2', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Retrieve thread
/inboxes/:inbox_id/threads/:thread_idOne conversation. Its messages are under …/emails.
{
"object": "inbox_thread",
"id": "thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d",
"inbox_id": "inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a",
"subject": "Refund for order 1041",
"snippet": "Hi, I was charged twice for…",
"participants": [{ "a": "carol@example.org", "n": "Carol" }],
"folder": "inbox",
"unread": true,
"assignee": null,
"messages": 2,
"sent_only": false,
"has_attachments": false,
"has_draft": false,
"labels": [{ "id": "lbl_5c2e9a1d7b4f8e3c6a0d2b9f1e4c", "name": "Billing", "color": "amber" }],
"column": null,
"last_message_at": "2026-11-20T09:14:00.000Z",
"trashed_at": null
}const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Update thread
/inboxes/:inbox_id/threads/:thread_idAny of folder, read (or unread) and assignee (a teammate's address, or null to unassign). Answers the thread.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"read": true,
"folder": "archive"
}),
});
const data = await res.json();
console.log(data);Delete thread
/inboxes/:inbox_id/threads/:thread_idMoves the thread to Trash (kept 30 days) and answers deleted: false, folder: "trash"; a thread already in Trash is removed for good (deleted: true).
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d', {
method: 'DELETE',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Add thread labels
/inboxes/:inbox_id/threads/:thread_id/labelsAdds labels of this inbox. Answers the thread.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d/labels', {
method: 'POST',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"labels": ["lbl_5c2e9a1d7b4f8e3c6a0d2b9f1e4c"]
}),
});
const data = await res.json();
console.log(data);Set thread labels
/inboxes/:inbox_id/threads/:thread_id/labelsMakes these the thread's only labels; [] clears them.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d/labels', {
method: 'PUT',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"labels": ["lbl_5c2e9a1d7b4f8e3c6a0d2b9f1e4c"]
}),
});
const data = await res.json();
console.log(data);Remove thread label
/inboxes/:inbox_id/threads/:thread_id/labels/:label_idTakes one label off the thread. Answers the thread.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d/labels/lbl_5c2e9a1d7b4f8e3c6a0d2b9f1e4c', {
method: 'DELETE',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);List thread emails
/inboxes/:inbox_id/threads/:thread_id/emailsEvery message of the thread, oldest first, with direction (in / out), addresses, html, text, attachments and, for mail you sent, its delivery status. source_id is the message's id under Emails.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d/emails', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Retrieve thread email
/inboxes/:inbox_id/threads/:thread_id/emails/:email_idOne message of the thread.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d/emails/msg_2a7f4c9e1d6b3a8f5c0e2d7b9a4f', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Reply to thread email
/inboxes/:inbox_id/threads/:thread_id/emails/:email_id/replyGoes to the sender — everyone on the message with reply_all: true — unless you pass to. It keeps the conversation together in the recipient's mail client and quotes the original.
html, textstringrequiredYour message (one of them).
to, cc, bccstring[]optionalRecipients.
subjectstringoptionalDefaults to "Re: " and the original subject.
reply_allbooleanoptionalReply to everyone on the message.
attachmentsobject[]optionalAs on POST /emails: { filename, content } or { filename, path }.
POST /emails — and is filed in the conversation. Send an Idempotency-Key header to make a retry safe.{ "object": "email", "id": "0b4f8a1c-6d2e-4f9a-b3c7-1e5d9a2f6b8c", "inbox_id": "inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a", "thread_id": "thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d" }const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d/emails/msg_2a7f4c9e1d6b3a8f5c0e2d7b9a4f/reply', {
method: 'POST',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"text": "Refund issued for order 1041.",
"cc": ["billing@example.com"]
}),
});
const data = await res.json();
console.log(data);Forward thread email
/inboxes/:inbox_id/threads/:thread_id/emails/:email_id/forwardto is required. The original follows your text, with its received files attached.
POST /emails — and is filed in the conversation. Send an Idempotency-Key header to make a retry safe.const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/threads/thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d/emails/msg_2a7f4c9e1d6b3a8f5c0e2d7b9a4f/forward', {
method: 'POST',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"to": ["colleague@example.org"],
"text": "Can you take this one?"
}),
});
const data = await res.json();
console.log(data);Create draft
/inboxes/:inbox_id/draftsmode is compose (default), reply, reply_all or forward; the last three answer email_id, a thread email. A message has one open answer at a time: asking again returns it.
modestringoptionalcompose, reply, reply_all or forward.
email_idstringoptionalThe thread email being answered (not for compose).
to, cc, bcc, subject, html, text…optionalThe message so far. Recipients are checked when it is sent.
attachmentsobject[]optional{ filename, content (base64), content_type }; up to 3 MB in total.
{
"object": "inbox_draft",
"id": "idr_9b4e1c7a3f8d2e6b5c0a1f9d4e7b",
"inbox_id": "inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a",
"mode": "reply",
"thread_id": "thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d",
"reply_to_id": "msg_2a7f4c9e1d6b3a8f5c0e2d7b9a4f",
"to": ["carol@example.org"], "cc": [], "bcc": [],
"subject": "Re: Refund for order 1041",
"html": "<p>Refund issued.</p>",
"text": "",
"attachments": [],
"author": "ada@example.com",
"updated_at": "2026-11-20T09:20:00.000Z"
}const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/drafts', {
method: 'POST',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"to": ["carol@example.org"],
"subject": "Your order",
"html": "<p>Hello</p>"
}),
});
const data = await res.json();
console.log(data);List drafts
/inboxes/:inbox_id/draftsUnsent messages, most recently edited first.
limitnumberoptional1–100. Omit to get every row (up to 1,000).
afterstringoptionalId of the last row of the previous page.
beforestringoptionalId of the first row of the next page. Not with after.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/drafts', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Retrieve draft
/inboxes/:inbox_id/drafts/:draft_idOne draft.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/drafts/idr_9b4e1c7a3f8d2e6b5c0a1f9d4e7b', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Update draft
/inboxes/:inbox_id/drafts/:draft_idChange any of to, cc, bcc, subject, html, text. Answers the draft.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/drafts/idr_9b4e1c7a3f8d2e6b5c0a1f9d4e7b', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"subject": "Refund issued for order 1041"
}),
});
const data = await res.json();
console.log(data);Delete draft
/inboxes/:inbox_id/drafts/:draft_idDiscards it.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/drafts/idr_9b4e1c7a3f8d2e6b5c0a1f9d4e7b', {
method: 'DELETE',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Send draft
/inboxes/:inbox_id/drafts/:draft_id/sendSends the draft and removes it.
POST /emails — and is filed in the conversation. Send an Idempotency-Key header to make a retry safe.{ "object": "email", "id": "0b4f8a1c-6d2e-4f9a-b3c7-1e5d9a2f6b8c", "inbox_id": "inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a", "thread_id": "thr_8d1e4b2c7a9f3e6d5c0b1a2f4e7d" }const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/drafts/idr_9b4e1c7a3f8d2e6b5c0a1f9d4e7b/send', {
method: 'POST',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Retrieve agent settings
/inboxes/:inbox_id/agentThe inbox's AI agent settings. They shape the replies the agent suggests when someone asks for one; the agent never acts on its own.
{
"object": "inbox_agent",
"inbox_id": "inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a",
"instructions": "Answer refund questions. Hand legal questions to a person.",
"actions": ["draft_reply", "apply_label"],
"tone": { "length": 30, "register": 20 },
"available_actions": ["draft_reply", "apply_label", "assign", "archive", "mark_spam", "forward"],
"updated_at": "2026-11-20T09:30:00.000Z"
}const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/agent', {
method: 'GET',
headers: { 'Authorization': 'Bearer mb_xxxxxxxxx' },
});
const data = await res.json();
console.log(data);Update agent settings
/inboxes/:inbox_id/agentChange any part; the rest is kept.
instructionsstringoptionalUp to 4,000 characters.
actionsstring[]optionalWhat it may suggest: draft_reply, apply_label, assign, archive, mark_spam, forward.
tone.length0–100optional0 concise … 100 expanded.
tone.register0–100optional0 professional … 100 casual.
const res = await fetch('https://www.senddart.com/api/inboxes/inb_3f9c2a7d1e4b8c6a0f5d2e9b7c1a/agent', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer mb_xxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"instructions": "Answer refund questions. Hand legal questions to a person.",
"actions": ["draft_reply", "apply_label"],
"tone": { "length": 30, "register": 20 }
}),
});
const data = await res.json();
console.log(data);