Inboxes

Create and manage email inboxes for your AI agents. Each inbox gets a unique email address that can send and receive messages.

ℹ

All API requests require an x-api-key header. Get your key from the dashboard. The base URL for all endpoints is https://api.agentsend.io.

The Inbox Object

All endpoints that return an inbox will include the following fields.

Field	Type	Description
`id`	uuid	Unique identifier for the inbox.
`address`	string	The full email address assigned to this inbox, e.g. `a1b2c3@agentsend.io`.
`displayName`	string	Human-readable name shown in the From header when sending email.
`domainId`	uuid \| null	The ID of a verified custom domain, or `null` when using the shared AgentSend domain.
`status`	string	One of `active`, `suspended`, or `deleted`.
`dailySendLimit`	integer	Maximum number of messages this inbox can send per calendar day.
`sendsToday`	integer	Number of messages sent today (resets at midnight UTC).
`totalSent`	integer	Cumulative count of all messages sent from this inbox.
`bounceCount`	integer	Number of hard bounces recorded against this inbox.
`complaintCount`	integer	Number of spam complaints recorded against this inbox.
`createdAt`	string (ISO 8601)	Timestamp of when the inbox was created.

Inbox object

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 12,
  "totalSent": 1847,
  "bounceCount": 2,
  "complaintCount": 0,
  "createdAt": "2025-03-15T10:22:00Z"
}

Create inbox

POST /inboxes

Provisions a new inbox and assigns it an email address. If no address is provided, a random address on the shared agentsend.io domain is generated. To use a custom domain, pass a verified domainId.

Request body

Parameter	Type	Description
`address`	string	Desired email address (local-part only if using a custom domain, or full address). Optional — auto-generated if omitted.
`displayName`	string	Friendly name shown in the From header. Optional.
`domainId`	uuid	ID of a verified custom domain to assign to this inbox. Optional — defaults to the shared AgentSend domain.

Returns

201 Created with the newly created Inbox object.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

javascript

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",
  }),
});

const inbox = await res.json(); // 201 Created
console.log(inbox.address); // "a1b2c3@agentsend.io"

Response · 201 Created

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 0,
  "totalSent": 0,
  "bounceCount": 0,
  "complaintCount": 0,
  "createdAt": "2025-04-16T09:00:00Z"
}

List inboxes

GET /inboxes

Returns a paginated list of all inboxes in your account, ordered by creation date (most recent first).

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Number of inboxes to return. Maximum `100`.
`offset`	integer	`0`	Number of inboxes to skip before returning results. Use with `limit` for pagination.

Returns

200 OK with a paginated envelope containing an array of Inbox objects.

curl

curl https://api.agentsend.io/inboxes?limit=10&offset=0 \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

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

const { data, total, limit, offset } = await res.json();
console.log(`Showing ${data.length} of ${total} inboxes`);

Response · 200 OK

{
  "data": [
    {
      "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
      "address": "a1b2c3@agentsend.io",
      "displayName": "Support Agent",
      "domainId": null,
      "status": "active",
      "dailySendLimit": 500,
      "sendsToday": 12,
      "totalSent": 1847,
      "bounceCount": 2,
      "complaintCount": 0,
      "createdAt": "2025-03-15T10:22:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Get inbox

GET /inboxes/{id}

Retrieves a single inbox by its ID, including live send counters and health metrics.

Path parameters

Parameter	Type	Description
`id` required	uuid	The ID of the inbox to retrieve.

Returns

200 OK with the Inbox object. Returns 404 Not Found if the inbox does not exist or belongs to a different account.

curl

curl https://api.agentsend.io/inboxes/3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

const inboxId = "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c";

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

console.log(inbox.status);     // "active"
console.log(inbox.sendsToday); // 12

Response · 200 OK

{
  "id": "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c",
  "address": "a1b2c3@agentsend.io",
  "displayName": "Support Agent",
  "domainId": null,
  "status": "active",
  "dailySendLimit": 500,
  "sendsToday": 12,
  "totalSent": 1847,
  "bounceCount": 2,
  "complaintCount": 0,
  "createdAt": "2025-03-15T10:22:00Z"
}

Delete inbox

DELETE /inboxes/{id}

Permanently deletes an inbox and its email address. All messages and threads associated with the inbox are also deleted. This action cannot be undone.

⚠

Deleting an inbox is irreversible. If you only need to pause sending temporarily, consider the inbox status field instead (contact support to suspend an inbox).

Path parameters

Parameter	Type	Description
`id` required	uuid	The ID of the inbox to delete.

Returns

204 No Content on success with an empty response body. Returns 404 Not Found if the inbox does not exist or belongs to a different account.

curl

curl -X DELETE https://api.agentsend.io/inboxes/3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c \
  -H "x-api-key: $AGENTSEND_API_KEY"

javascript

const inboxId = "3a8f1c2d-4e5b-6f7a-8b9c-0d1e2f3a4b5c";

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}`,
  {
    method: "DELETE",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

// 204 No Content — no body to parse
if (res.ok) console.log("Inbox deleted");

← Previous API Overview Next → API: Messages