Hộp Thư

Mỗi agent có hộp thư riêng với một địa chỉ email duy nhất. Hộp thư là đơn vị cơ bản trong AgentSend.

Tổng Quan

Hộp thư là một địa chỉ email riêng cho một agent duy nhất. Mỗi email mà agent của bạn gửi hoặc nhận đều đi qua một hộp thư. Bạn có thể tạo bao nhiêu hộp thư tùy ý — một cho mỗi agent, một cho mỗi khách hàng, một cho mỗi quy trình — không có giới hạn.

Theo mặc định, hộp thư được cấp trên tên miền @agentsend.io. Nếu bạn muốn các agent gửi từ tên miền của riêng bạn (ví dụ agent@yourcompany.com), xem Tên Miền Tùy Chỉnh.

Tạo Hộp Thư

POST /inboxes

Tạo một hộp thư mới bằng cách gửi request POST. Cả hai trường body đều tùy chọn — nếu bạn bỏ qua displayName, hộp thư được tạo mà không có tên hiển thị. Nếu bỏ qua domainId, địa chỉ sẽ được cấp trên @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...

Phản hồi bao gồm toàn bộ đối tượng inbox, bao gồm address được tự động sinh mà bạn có thể sử dụng ngay lập tức.

Thuộc Tính Hộp Thư

Mỗi đối tượng hộp thư có các trường sau:

Tên Miền Tùy Chỉnh

Theo mặc định, mỗi hộp thư có địa chỉ trên @agentsend.io. Nếu bạn muốn các agent gửi từ tên miền của riêng bạn — ví dụ agent@support.yourcompany.com — bạn có thể kết nối tên miền tùy chỉnh và truyền domainId khi tạo hộp thư.

Liệt Kê Hộp Thư

GET /inboxes

Lấy danh sách có phân trang của tất cả hộp thư trong tài khoản của bạn. Sử dụng limit và offset để duyệt qua các trang.

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

Xóa Hộp Thư

DELETE /inboxes/{id}

Xóa vĩnh viễn một hộp thư và tất cả tin nhắn, chuỗi hội thoại, và webhook liên quan.

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

Giới Hạn Gửi

Mỗi hộp thư có dailySendLimit giới hạn số lượng email có thể gửi trong khoảng 24 giờ trượt. Trường sendsToday cho biết bao nhiêu lần gửi đã được sử dụng trong khoảng hiện tại.

Nếu một hộp thư đạt đến giới hạn, các yêu cầu gửi tiếp theo trả về lỗi 429 Too Many Requests. Khoảng thời gian sẽ đặt lại vào nửa đêm 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`);
}