المرفقات
ارفع الملفات وأرفقها بالرسائل الصادرة. تُخزَّن الرسائل الواردة ذات المرفقات تلقائياً ويمكن الوصول إليها عبر API.
نظرة عامة
يتعامل AgentSend مع المرفقات في الاتجاهين. للبريد الصادر، ارفع الملف أولاً للحصول على معرّف مرفق، ثم مرّر ذلك المعرّف عند إرسال الرسالة. للبريد الوارد، تُخزَّن أي مرفقات أدرجها المرسل تلقائياً وتظهر في كائن الرسالة — دون أي عمل إضافي.
تُخزَّن المرفقات بأمان وتُقدَّم عبر روابط مُوقَّعة مسبقاً وقصيرة الأمد. تنتهي صلاحية روابط التنزيل بعد ساعة واحدة — اجلب رابطاً جديداً من API عند الحاجة للوصول إلى ملف.
رفع مرفق
أرسل طلب POST إلى /attachments مع الملف كـmultipart/form-data. تُرجع الاستجابة كائن مرفق بـid يمكنك استخدامه عند إرسال الرسالة.
curl -X POST https://api.agentsend.io/attachments \ -H "x-api-key: $AGENTSEND_API_KEY" \ -F "file=@/path/to/report.pdf"
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 في جسم الرسالة عند الإرسال. يمكنك الإشارة إلى عدة مرفقات في رسالة واحدة.
// 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 جديداً مُوقَّعاً مسبقاً يمكنك استخدامه لتنزيل الملف.
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 — يحتوي كل عنصر على البيانات الوصفية اللازمة لتحديد الملف وتنزيله.
{
"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 ميجابايت). أبقِ المرفقات صغيرة أو ارتبط بملفات مستضافة خارجياً للحصول على أفضل قابلية تسليم.