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

أنشئ وأدر صناديق البريد لوكلاء الذكاء الاصطناعي. يحصل كل صندوق على عنوان بريد إلكتروني فريد يمكنه إرسال الرسائل واستقبالها.

ℹ

تتطلب جميع طلبات API ترويسة x-api-key. احصل على مفتاحك من لوحة التحكم. العنوان الأساسي لجميع نقاط النهاية هو https://api.agentsend.io.

كائن Inbox

ستتضمن جميع نقاط النهاية التي تُرجع صندوقاً الحقول التالية.

الحقل	النوع	الوصف
`id`	uuid	المعرّف الفريد لصندوق البريد.
`address`	string	عنوان البريد الكامل المُعيَّن لهذا الصندوق، مثل `a1b2c3@agentsend.io`.
`displayName`	string	اسم مقروء يُعرض في ترويسة From عند إرسال البريد.
`domainId`	uuid \| null	معرّف نطاق مخصص تم التحقق منه، أو `null` عند استخدام نطاق AgentSend المشترك.
`status`	string	إحدى القيم: `active` أو `suspended` أو `deleted`.
`dailySendLimit`	integer	العدد الأقصى للرسائل التي يمكن للصندوق إرسالها في اليوم التقويمي.
`sendsToday`	integer	عدد الرسائل المرسلة اليوم (يُعاد التعيين عند منتصف ليل UTC).
`totalSent`	integer	العدد التراكمي لكل الرسائل المرسلة من هذا الصندوق.
`bounceCount`	integer	عدد الارتدادات الحادة المسجلة ضد هذا الصندوق.
`complaintCount`	integer	عدد شكاوى البريد المزعج المسجلة ضد هذا الصندوق.
`createdAt`	string (ISO 8601)	طابع زمني لوقت إنشاء الصندوق.

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"
}

إنشاء صندوق

POST /inboxes

يجهّز صندوقاً جديداً ويعيّن له عنوان بريد. إذا لم يُقدَّم address، يُولَّد عنوان عشوائي على نطاق agentsend.io المشترك. لاستخدام نطاق مخصص، مرّر domainId الذي تم التحقق منه.

جسم الطلب

المعامل	النوع	الوصف
`address`	string	عنوان البريد المطلوب (الجزء المحلي فقط إذا كنت تستخدم نطاقاً مخصصاً، أو العنوان الكامل). اختياري — يُولَّد تلقائياً إذا تُرك.
`displayName`	string	اسم ودي يظهر في ترويسة From. اختياري.
`domainId`	uuid	معرّف نطاق مخصص تم التحقق منه لتخصيصه للصندوق. اختياري — الافتراضي هو نطاق AgentSend المشترك.

يُرجع

201 Created مع كائن Inbox المنشأ حديثاً.

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"
}

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

GET /inboxes

تُرجع قائمة مقسَّمة إلى صفحات لجميع الصناديق في حسابك، مرتَّبة حسب تاريخ الإنشاء (الأحدث أولاً).

معاملات الاستعلام

المعامل	Type	الافتراضي	Description
`limit`	integer	`20`	عدد الصناديق المطلوب إرجاعها. الحد الأقصى `100`.
`offset`	integer	`0`	عدد الصناديق المطلوب تخطيها قبل إرجاع النتائج. استخدمه مع `limit` للترقيم.

يُرجع

200 OK مع مظروف مقسَّم يحتوي مصفوفة كائنات Inbox.

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 /inboxes/{id}

يسترجع صندوقاً واحداً حسب معرّفه، بما في ذلك عدّادات الإرسال الحية ومقاييس الصحة.

معاملات المسار

Parameter	Type	Description
`id` مطلوب	uuid	معرّف الصندوق المطلوب استرجاعه.

Returns

200 OK مع كائن Inbox. تُرجع 404 Not Found إذا لم يكن الصندوق موجوداً أو يخص حساباً آخر.

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 /inboxes/{id}

يحذف الصندوق وعنوان بريده نهائياً. كما تُحذف جميع الرسائل والمحادثات المرتبطة بالصندوق. لا يمكن التراجع عن هذا الإجراء.

⚠

حذف الصندوق لا رجعة فيه. إذا كنت تحتاج فقط إلى إيقاف الإرسال مؤقتاً، فكّر في حقل status بدلاً من ذلك (تواصل مع الدعم لتعليق صندوق).

معاملات المسار

Parameter	Type	Description
`id` مطلوب	uuid	معرّف الصندوق المطلوب حذفه.

Returns

204 No Content عند النجاح بجسم استجابة فارغ. تُرجع 404 Not Found إذا لم يكن الصندوق موجوداً أو يخص حساباً آخر.

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

← السابق نظرة عامة على API التالي → API: الرسائل