الرئيسية › المستندات › الرسائل

الرسائل

تمثل الرسائل الرسائل الفردية التي يرسلها أو يستقبلها صندوق بريد. أرسل رسائل HTML غنية، وتتبع حالة التسليم، واقرأ الردود الواردة.

نظرة عامة

الرسالة هي بريد إلكتروني واحد مرتبط بـصندوق بريد. عندما يرسل وكيلك رسالة، يُنشأ رسالة صادرة. عندما يرد شخص أو يرسل إلى عنوان وكيلك، تُنشأ رسالة واردة تلقائياً.

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

ℹ

الرسائل غير قابلة للتعديل بعد إنشائها. لإرسال متابعة، أنشئ رسالة جديدة في نفس المحادثة بتمرير threadId.

إرسال بريد إلكتروني

POST /inboxes/{inboxId}/messages

أرسل بريداً من صندوق بالنشر إلى نقطة نهاية رسائله. المصفوفة to وsubject مطلوبان؛ أما البقية فاختيارية.

جسم الطلب

الحقل النوع الوصف
to مطلوب string[] مصفوفة عناوين المستلمين.
subject مطلوب string سطر موضوع الرسالة.
cc string[] مستلمو CC.
bcc string[] مستلمو BCC. غير مرئيين للمستلمين الآخرين.
bodyText string نص عادي. يُستخدم كبديل عند تقديم bodyHtml أيضاً.
bodyHtml string نص HTML. عند تقديم كل من bodyText وbodyHtml، تُرسل الرسالة كـ multipart/alternative.
threadId string المحادثة المطلوب الرد ضمنها. إذا تُركت، تُنشأ محادثة جديدة.
attachmentIds string[] معرّفات المرفقات المرفوعة مسبقاً المطلوب تضمينها.
javascript 
const res = 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: "Following up on your request",
      bodyText: "Hi, just checking in on your request.",
      bodyHtml: "<p>Hi, just checking in on your request.</p>",
    }),
  }
);

const message = await res.json();
console.log(message.id);     // msg_abc123
console.log(message.delivery); // "email" or "dry-run"
console.log(message.status); // "queued"

خصائص الرسالة

يحتوي كل كائن رسالة تُرجعه API على الحقول التالية.

الخاصية Type Description
id string المعرّف الفريد للرسالة.
inboxId string صندوق البريد الذي تنتمي إليه هذه الرسالة.
threadId string المحادثة التي تُجمَّع فيها هذه الرسالة.
direction string outbound للرسائل التي أرسلها وكيلك؛ inbound للرسائل المستلمة.
fromAddress string عنوان بريد المرسل.
toAddresses string[] المستلمون الرئيسيون.
ccAddresses string[] مستلمو CC.
subject string Email subject line.
bodyText string محتوى نصي عادي.
bodyHtml string محتوى HTML.
delivery string ما إذا كانت البيئة أرسلت بريداً حقيقياً (email) أو حاكته فقط (dry-run).
status string حالة التسليم الحالية. راجع حالة الرسالة أدناه.
attachments object[] مصفوفة كائنات مرفقات تحوي id وfilename وcontentType وsize.
messageIdHeader string قيمة ترويسة Message-ID وفق RFC 5322، تُستخدم للمحادثات في عملاء البريد.
createdAt string طابع زمني ISO 8601 لوقت إنشاء الرسالة.

حالة الرسالة

تمر الرسائل الصادرة بدورة حياة تسليم. تحقق من delivery أولاً لتأكيد ما إذا كانت البيئة أرسلت بريداً حقيقياً أو حاكته فقط، ثم استخدم status أو Webhooks لمتابعة دورة الحياة من جانب المزود.

دورة حياة الصادر

حالات الفشل

الرسائل الواردة

⚠

إذا بلغت رسالة حالة bounced أو complained، تجنب إرسال مزيد من الرسائل إلى ذلك العنوان لحماية سمعة المرسل لديك.

قائمة الرسائل

GET /inboxes/{inboxId}/messages

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

معامل الاستعلام Type Description
limit number عدد الرسائل المطلوب إرجاعها. الافتراضي 20، الحد الأقصى 100.
offset number عدد الرسائل المطلوب تخطيها للترقيم. الافتراضي 0.
status string رشّح حسب الحالة. أحد القيم: queued، sending، sent، delivered، failed، bounced، complained، received.
javascript 
// Fetch the 10 most recent inbound messages
const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages?status=received&limit=10`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data, total } = await res.json();

for (const msg of data) {
  console.log(msg.fromAddress, msg.subject, msg.bodyText);
}
💡

استخدم Webhooks بدلاً من الاستعلام الدوري لتصلك إشعارات فور وصول رسالة جديدة. الاستعلام الدوري بديل جيد للنصوص البسيطة والمهام قصيرة الأمد.

HTML مقابل النص العادي

يدعم AgentSend رسائل النص العادي وHTML وmultipart. استخدم bodyText للنص العادي وbodyHtml لمحتوى HTML.

💡

ضمّن دائماً نسخة bodyText بجانب bodyHtml. يحسّن ذلك قابلية التسليم وسهولة الوصول والتوافق مع عملاء البريد النصي.

حذف الرسائل

DELETE /messages/{id}

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

javascript 
await fetch(`https://api.agentsend.io/messages/${messageId}`, {
  method: "DELETE",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});
⚠

حذف الرسالة نهائي. ينبغي حذف الرسائل الواردة التي هي جزء من محادثة نشطة بحذر، لأن سجل المحادثة سيصبح غير مكتمل.

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