收件匣

每個代理都有自己的收件匣和唯一的電子郵件地址。收件匣是 AgentSend 中的基本單位。

概覽

收件匣是單一代理的專屬電子郵件地址。您代理發送或接收的每封電子郵件都會通過收件匣。您可以依需求建立任意數量的收件匣 — 每個代理一個、每個客戶一個、每個工作流程一個 — 沒有限制。

預設情況下，收件匣會在 @agentsend.io 網域上配置。如果您希望代理從您自己的網域發送 (e.g. agent@yourcompany.com), see 自訂網域。

ℹ

收件匣彼此隔離。代理只能透過自己的收件匣發送和接收電子郵件 — 無法存取其他收件匣的訊息。

建立收件匣

POST /inboxes

透過發送 POST 請求來建立新的收件匣。兩個主體欄位都是選填的 — 如果您省略 displayName, 收件匣將不帶名稱建立。 If you omit domainId, 地址將在 @agentsend.io.

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",   // 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...

回應包含完整的收件匣物件, 包括自動產生的 address 您可以立即開始使用。

收件匣屬性

每個收件匣物件都有以下欄位：

屬性	類型	描述
`id`	string (uuid)	收件匣的唯一識別碼。在所有 API 呼叫中使用。
`address`	string (email)	分配給此收件匣的完整電子郵件地址, e.g. `a1b2c3@agentsend.io`.
`displayName`	string \| null	收件匣的可讀標籤。在外送電子郵件標頭中顯示為寄件人名稱。
`domainId`	string \| null	與此收件匣關聯的自訂網域 ID。 `null` 代表預設的 `@agentsend.io` 地址。
`status`	string	目前收件匣狀態： `active`, `suspended`, or `deleted`. 只有 `active` 的收件匣才能發送和接收。
`dailySendLimit`	number	此收件匣在 24 小時內可發送的最大電子郵件數量。
`sendsToday`	number	目前 24 小時內已發送的電子郵件數量。於 UTC 午夜重置。
`totalSent`	number	自建立以來從此收件匣發送的所有電子郵件累計數量。
`bounceCount`	number	此收件匣記錄的硬退信數量。高退信率可能觸發暫停。
`complaintCount`	number	此收件匣記錄的垃圾郵件投訴數量。
`createdAt`	string (ISO 8601)	收件匣建立的時間戳記。

自訂網域

預設情況下，每個收件匣都會在 @agentsend.io. 如果您希望代理從您自己的網域發送 — for example agent@support.yourcompany.com — 您可以連接自訂網域並在建立收件匣時傳遞 domainId 。

💡

自訂網域可提高投遞率和品牌信任度。請參閱網域指南來新增和驗證您的網域，然後回到這裡在其上建立收件匣。

列出收件匣

GET /inboxes

擷取帳戶中所有收件匣的分頁列表。使用 limit 和 offset 來翻頁瀏覽結果。

javascript

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

查詢參數	類型	描述
`limit`	number	返回的結果數量。預設為 `20`, max `100`.
`offset`	number	跳過的結果數量。預設為 `0`.

刪除收件匣

DELETE /inboxes/{id}

永久刪除收件匣及所有相關的訊息、對話串和 webhooks。

⚠

此操作是永久性的且無法撤銷。 屬於該收件匣的所有訊息、對話串和 webhook 訂閱將立即刪除。收件匣的電子郵件地址將被釋放並可能被重新分配。

javascript

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

發送限制

每個收件匣都有一個 dailySendLimit 限制其在滾動 24 小時內可發送的電子郵件數量。 sendsToday 欄位告訴您目前視窗中已使用的發送次數。

如果收件匣達到限制，後續的發送請求將返回 429 Too Many Requests 錯誤。視窗於 UTC 午夜重置。

ℹ

在發送大量郵件前監控 sendsToday。如果您的代理需要發送超過預設限制的郵件，請聯繫支援團隊以請求增加帳戶限額。

javascript

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