Trang Chủ › Tài Liệu › Tài Liệu API › Hộp Thư

Hộp Thư

Tạo và quản lý hộp thư email cho các AI agent của bạn. Mỗi hộp thư có một địa chỉ email duy nhất có thể gửi và nhận tin nhắn.

ℹ

Tất cả yêu cầu API yêu cầu header x-api-key. Lấy key từ bảng điều khiển. URL cơ sở cho tất cả endpoint là https://api.agentsend.io.

Đối Tượng Hộp Thư

Tất cả endpoint trả về một hộp thư sẽ bao gồm các trường sau.

Trường Kiểu Mô tả
id uuid Định danh duy nhất của inbox.
address string The full email address assigned to this inbox, e.g. a1b2c3@agentsend.io.
displayName string Dễ đọc 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 Số lượng tối đa messages this inbox can send per calendar day.
sendsToday integer Số lượng messages sent today (resets at midnight UTC).
totalSent integer Cumulative count of all messages sent from this inbox.
bounceCount integer Số lượng hard bounces recorded against this inbox.
complaintCount integer Số lượng spam complaints recorded against this inbox.
createdAt string (ISO 8601) Dấu thời gian khi inbox được tạo.
Đối tượng Hộp Thư 
{
  "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"
}

Tạo hộp thư

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.

Nội dung yêu cầu

Tham số Kiểu Mô tả
address string Desired email address (local-part only if using a custom domain, or full address). Tùy chọn — tự động sinh nếu bỏ qua.
displayName string Friendly name shown in the From header. Tùy chọn.
domainId uuid ID of a verified custom domain to assign to this inbox. Tùy chọn — defaults to the shared AgentSend domain.

Trả về

201 Created kèm đối tượng Hộp Thư mới được tạo.

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"
Phản hồi · 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"
}

Liệt kê hộp thư

GET /inboxes

Trả về danh sách có phân trang of all inboxes in your account, ordered by creation date (most recent first).

Tham số truy vấn

Parameter Type Default Description
limit integer 20 Số lượng inboxes to return. Maximum 100.
offset integer 0 Số lượng inboxes to skip before returning results. Use with limit for pagination.

Trả về

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`);
Phản hồi · 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
}

Lấy hộp thư

GET /inboxes/{id}

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

Tham số đường dẫn

Tham số Kiểu Mô tả
id bắt buộc uuid The ID of the inbox to retrieve.

Trả về

200 OK with đối tượng Hộp Thư. 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
Phản hồi · 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"
}

Xóa hộp thư

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

Tham số đường dẫn

Tham số Kiểu Mô tả
id bắt buộc uuid The ID of the inbox to delete.

Trả về

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");
← Trước API Overview