API Reference

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.

Webhook events: 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

POST/inboxes

The 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.

Body
email_addressstringrequired

The full address. Or send local plus domain_id.

namestringoptional

A display name for the inbox.

from_namestringoptional

The name recipients see on mail sent from it.

receiving'domain' | 'forward'optional

Required only when the domain does not receive mail yet.

Inboxes beyond your plan answer 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

GET/inboxes/:inbox_id

One 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

GET/inboxes

Newest first, as { object: "list", has_more, data }.

Query parameters
limitnumberoptional

1–100. Omit to get every row (up to 1,000).

afterstringoptional

Id of the last row of the previous page.

beforestringoptional

Id 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

PATCH/inboxes/:inbox_id

Change 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

DELETE/inboxes/:inbox_id

Removes 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

POST/inboxes/:inbox_id/labels

Names 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

GET/inboxes/:inbox_id/labels

Every label, by name, with how many threads carry it.

Query parameters
limitnumberoptional

1–100. Omit to get every row (up to 1,000).

afterstringoptional

Id of the last row of the previous page.

beforestringoptional

Id 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

PATCH/inboxes/:inbox_id/labels/:label_id

Change 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

DELETE/inboxes/:inbox_id/labels/:label_id

Takes 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

GET/inboxes/:inbox_id/threads

One page of conversations, most recently active first. Page forward with after (the last thread id).

Query parameters
folderstringoptional

inbox (default), sent, archive, spam or trash.

labelstringoptional

Only threads carrying this label id.

querystringoptional

Search words and operators: from: to: label: has:attachment is:unread is:assigned after:YYYY-MM-DD before:YYYY-MM-DD.

from, tostringoptional

Comma-separated addresses.

start_date, end_dateYYYY-MM-DDoptional

Last activity on or after / before these days.

unreadbooleanoptional

Only unread (true) or read (false) threads.

limit, afternumber, stringoptional

Page 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

GET/inboxes/:inbox_id/threads/search

The 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

GET/inboxes/:inbox_id/threads/:thread_id

One 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

PATCH/inboxes/:inbox_id/threads/:thread_id

Any 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

DELETE/inboxes/:inbox_id/threads/:thread_id

Moves 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

POST/inboxes/:inbox_id/threads/:thread_id/labels

Adds 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

PUT/inboxes/:inbox_id/threads/:thread_id/labels

Makes 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

DELETE/inboxes/:inbox_id/threads/:thread_id/labels/:label_id

Takes 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

GET/inboxes/:inbox_id/threads/:thread_id/emails

Every 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

GET/inboxes/:inbox_id/threads/:thread_id/emails/:email_id

One 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

POST/inboxes/:inbox_id/threads/:thread_id/emails/:email_id/reply

Goes 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.

Body
html, textstringrequired

Your message (one of them).

to, cc, bccstring[]optional

Recipients.

subjectstringoptional

Defaults to "Re: " and the original subject.

reply_allbooleanoptional

Reply to everyone on the message.

attachmentsobject[]optional

As on POST /emails: { filename, content } or { filename, path }.

Sends need a full-access API key. The message goes out from the inbox address through the normal send pipeline — the same quota, suppression and domain checks as 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

POST/inboxes/:inbox_id/threads/:thread_id/emails/:email_id/forward

to is required. The original follows your text, with its received files attached.

Sends need a full-access API key. The message goes out from the inbox address through the normal send pipeline — the same quota, suppression and domain checks as 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

POST/inboxes/:inbox_id/drafts

mode 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.

Body
modestringoptional

compose, reply, reply_all or forward.

email_idstringoptional

The thread email being answered (not for compose).

to, cc, bcc, subject, html, text…optional

The 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

GET/inboxes/:inbox_id/drafts

Unsent messages, most recently edited first.

Query parameters
limitnumberoptional

1–100. Omit to get every row (up to 1,000).

afterstringoptional

Id of the last row of the previous page.

beforestringoptional

Id 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

GET/inboxes/:inbox_id/drafts/:draft_id

One 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

PATCH/inboxes/:inbox_id/drafts/:draft_id

Change 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

DELETE/inboxes/:inbox_id/drafts/:draft_id

Discards 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

POST/inboxes/:inbox_id/drafts/:draft_id/send

Sends the draft and removes it.

Sends need a full-access API key. The message goes out from the inbox address through the normal send pipeline — the same quota, suppression and domain checks as 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

GET/inboxes/:inbox_id/agent

The 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

PATCH/inboxes/:inbox_id/agent

Change any part; the rest is kept.

Body
instructionsstringoptional

Up to 4,000 characters.

actionsstring[]optional

What it may suggest: draft_reply, apply_label, assign, archive, mark_spam, forward.

tone.length0–100optional

0 concise … 100 expanded.

tone.register0–100optional

0 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);