المرفقات

ارفع الملفات وأرفقها بالرسائل الصادرة. تُخزَّن الرسائل الواردة ذات المرفقات تلقائياً ويمكن الوصول إليها عبر API.

نظرة عامة

يتعامل AgentSend مع المرفقات في الاتجاهين. للبريد الصادر، ارفع الملف أولاً للحصول على معرّف مرفق، ثم مرّر ذلك المعرّف عند إرسال الرسالة. للبريد الوارد، تُخزَّن أي مرفقات أدرجها المرسل تلقائياً وتظهر في كائن الرسالة — دون أي عمل إضافي.

تُخزَّن المرفقات بأمان وتُقدَّم عبر روابط مُوقَّعة مسبقاً وقصيرة الأمد. تنتهي صلاحية روابط التنزيل بعد ساعة واحدة — اجلب رابطاً جديداً من API عند الحاجة للوصول إلى ملف.

رفع مرفق

أرسل طلب POST إلى /attachments مع الملف كـmultipart/form-data. تُرجع الاستجابة كائن مرفق بـid يمكنك استخدامه عند إرسال الرسالة.

curl
curl -X POST https://api.agentsend.io/attachments \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -F "file=@/path/to/report.pdf"
javascript
const form = new FormData();
form.append("file", fileBlob, "report.pdf");

const res = await fetch("https://api.agentsend.io/attachments", {
  method: "POST",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  body: form,
});

const attachment = await res.json();
console.log(attachment.id); // e.g. "att_a1b2c3d4"

خصائص المرفق

يحتوي كل كائن مرفق على الحقول التالية:

الحقل النوع الوصف
id string المعرّف الفريد للمرفق (بادئة att_).
filename string اسم الملف الأصلي كما رُفع أو استُلم.
contentType string نوع MIME، مثل application/pdf أو image/png.
size number حجم الملف بالبايتات.
url string رابط تنزيل مُوقَّع مسبقاً. تنتهي صلاحيته بعد ساعة.
createdAt string طابع زمني ISO 8601 لوقت تخزين المرفق.

إرفاق بالرسائل

مرّر مصفوفة attachmentIds في جسم الرسالة عند الإرسال. يمكنك الإشارة إلى عدة مرفقات في رسالة واحدة.

javascript
// 1. Upload the file
const form = new FormData();
form.append("file", fileBlob, "invoice.pdf");
const { id: attachmentId } = await fetch("https://api.agentsend.io/attachments", {
  method: "POST",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  body: form,
}).then(r => r.json());

// 2. Send the message with the attachment
await fetch(`https://api.agentsend.io/inboxes/${inboxId}/messages`, {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: ["customer@example.com"],
    subject: "Your invoice",
    bodyText: "Please find your invoice attached.",
    attachmentIds: [attachmentId],
  }),
});

استرجاع المرفقات

اجلب مرفقاً واحداً حسب معرّفه بـGET /attachments/{id}. تتضمن الاستجابة url جديداً مُوقَّعاً مسبقاً يمكنك استخدامه لتنزيل الملف.

javascript
const attachment = await fetch(
  `https://api.agentsend.io/attachments/${attachmentId}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
).then(r => r.json());

// Download the file using the presigned URL
const fileData = await fetch(attachment.url).then(r => r.arrayBuffer());

المرفقات الواردة

عندما يصل بريد وارد بمرفقات، يخزّن AgentSend كل ملف تلقائياً. سيتضمن كائن الرسالة مصفوفة attachments — يحتوي كل عنصر على البيانات الوصفية اللازمة لتحديد الملف وتنزيله.

json — inbound message (excerpt)
{
  "id": "msg_xyz",
  "subject": "Here's the contract",
  "attachments": [
    {
      "id": "att_a1b2c3",
      "filename": "contract.pdf",
      "contentType": "application/pdf",
      "size": 204800
    }
  ]
}

لتنزيل مرفق وارد، مرّر id الخاص به إلى GET /attachments/{id} لاستلام رابط تنزيل مُوقَّع مسبقاً كما هو موضح في قسم استرجاع المرفقات أعلاه.

حدود الحجم

الحد الأقصى لحجم المرفق الواحد هو 25 ميجابايت. ينطبق هذا على الرفع والمرفقات الواردة — تُهمَل الملفات التي تتجاوز هذا الحد في البريد الوارد وتُضاف ملاحظة اقتطاع إلى الرسالة.

تفرض كثير من خوادم البريد المستقبِلة حدود حجم خاصة بها للمرفقات (عادة 10–25 ميجابايت). أبقِ المرفقات صغيرة أو ارتبط بملفات مستضافة خارجياً للحصول على أفضل قابلية تسليم.