صناديق البريد

يحصل كل وكيل على صندوق بريد خاص به بعنوان بريد إلكتروني فريد. صناديق البريد هي الوحدة الأساسية في AgentSend.

نظرة عامة

صندوق البريد هو عنوان بريد إلكتروني مخصص لوكيل واحد. كل رسالة يرسلها أو يستقبلها وكيلك تمر عبر صندوق بريد. يمكنك إنشاء أي عدد من صناديق البريد — واحد لكل وكيل، أو لكل عميل، أو لكل سير عمل — لا توجد قيود.

افتراضياً، يتم تجهيز صناديق البريد على نطاق @agentsend.io. إذا أردت أن يرسل وكلاؤك من نطاقك الخاص (مثل agent@yourcompany.com)، راجع النطاقات المخصصة.

إنشاء صندوق بريد

POST /inboxes

أنشئ صندوق بريد جديد بإرسال طلب POST. كلا الحقلين في الجسم اختيار‌ي — إذا تركت displayName، يُنشأ الصندوق بدونه. إذا تركت domainId، يُجهَّز العنوان على @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...

تتضمن الاستجابة كائن صندوق البريد الكامل، بما في ذلك address المُولَّد تلقائياً والذي يمكنك استخدامه فوراً.

خصائص صندوق البريد

يحتوي كل كائن صندوق بريد على الحقول التالية:

النطاقات المخصصة

افتراضياً، يحصل كل صندوق على عنوان على @agentsend.io. إذا أردت أن يرسل وكلاؤك من نطاقك الخاص — مثلاً agent@support.yourcompany.com — يمكنك ربط نطاق مخصص وتمرير domainId عند إنشاء الصندوق.

قائمة صناديق البريد

GET /inboxes

احصل على قائمة مقسَّمة إلى صفحات لجميع صناديق البريد في حسابك. استخدم limit وoffset للتنقل بين الصفحات.

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

حذف صندوق بريد

DELETE /inboxes/{id}

يحذف صندوق البريد نهائياً مع جميع الرسائل والمحادثات و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

حدود الإرسال

لكل صندوق dailySendLimit يحدد عدد الرسائل التي يمكن إرسالها خلال نافذة 24 ساعة المتجددة. يخبرك الحقل sendsToday بعدد عمليات الإرسال المستخدمة في النافذة الحالية.

إذا بلغ الصندوق حده، تُرجع طلبات الإرسال التالية خطأ 429 Too Many Requests. تُعاد النافذة عند منتصف ليل 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`);
}