Inboxes

Each agent gets its own inbox with a unique email address. Inboxes are the fundamental unit in AgentSend.

Overview

An inbox is a dedicated email address for a single agent. Every email your agent sends or receives flows through an inbox. You can create as many inboxes as you need — one per agent, one per customer, one per workflow — there are no limits.

By default, inboxes are provisioned on the @agentsend.io domain. If you want your agents to send from your own domain (e.g. agent@yourcompany.com), see Custom Domains.

Creating an Inbox

POST /inboxes

Create a new inbox by sending a POST request. Both body fields are optional — if you omit displayName, the inbox is created without one. If you omit domainId, the address is provisioned on @agentsend.io.

const res = await fetch("https://api.agentsend.io/inboxes", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    displayName: "Support Agent",   // optional
    domainId: "dom_abc123",         // optional — omit for @agentsend.io
  }),
});

const inbox = await res.json();
console.log(inbox.address); // e.g. a1b2c3@agentsend.io
console.log(inbox.id);      // e.g. inb_7x9kQm2Np...

The response includes the full inbox object, including the auto-generated address you can start using immediately.

Inbox Properties

Every inbox object has the following fields:

Custom Domains

By default, every inbox gets an address on @agentsend.io. If you want your agents to send from your own domain — for example agent@support.yourcompany.com — you can connect a custom domain and pass the domainId when creating an inbox.

Listing Inboxes

GET /inboxes

Retrieve a paginated list of all inboxes in your account. Use limit and offset to page through results.

const res = await fetch(
  "https://api.agentsend.io/inboxes?limit=20&offset=0",
  {
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const { data, total } = await res.json();
// data  — array of inbox objects
// total — total count across all pages

for (const inbox of data) {
  console.log(inbox.address, inbox.status, inbox.sendsToday);
}

Deleting an Inbox

DELETE /inboxes/{id}

Permanently deletes an inbox and all associated messages, threads, and webhooks.

await fetch(`https://api.agentsend.io/inboxes/${inboxId}`, {
  method: "DELETE",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});
// Returns 204 No Content on success

Send Limits

Each inbox has a dailySendLimit that caps how many emails it can send in a rolling 24-hour window. The sendsToday field tells you how many sends have been used in the current window.

If an inbox reaches its limit, subsequent send requests return a 429 Too Many Requests error. The window resets at midnight UTC.

const inbox = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
).then(r => r.json());

const remaining = inbox.dailySendLimit - inbox.sendsToday;
if (remaining <= 0) {
  console.log("Daily send limit reached. Try again after midnight UTC.");
} else {
  console.log(`${remaining} sends remaining today`);
}