Email: الإرسال
إرسال بريد إلكتروني واحد أو أكثر، مع إمكانية إرفاق ملفات، باستخدام واجهة برمجة تطبيقات Mersal.
أرسل بريدًا إلكترونيًا واحدًا أو أكثر في طلب واحد، مع دعم اسم مرسل مخصص، وعنوان رد، وجدولة، ومرفقات ملفات.
النقطة الطرفية
المصادقة
يتطلب مفتاح API الشخصي الخاص بك عبر ترويسة Api-key (أو بديل api_key في معامل الرابط/نص الطلب). راجع المصادقة.
معاملات الطلب
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
contact | array | نعم | مصفوفة المستلمين. يجب أن تحتوي على عنصر واحد على الأقل. |
contact.*.email | string | نعم | عنوان البريد الإلكتروني للمستلم. يجب أن يكون بريدًا صالحًا. |
contact.*.subject | string | نعم | سطر موضوع البريد الإلكتروني. |
contact.*.message | string | نعم | نص البريد الإلكتروني. يدعم HTML. |
contact.*.gateway_identifier | string | لا | معرّف UID لبوابة بريد إلكتروني محددة للإرسال عبرها. إذا تم تمريره، يجب أن يشير إلى بوابة بريد إلكتروني نشطة في حسابك. احذف هذا الحقل لاستخدام بوابة البريد الافتراضية/النشطة في حسابك. |
contact.*.sender_name | string | لا | اسم عرض مخصص للمرسل. |
contact.*.reply_to_email | string | لا | عنوان الرد الخاص بالبريد الإلكتروني. |
contact.*.schedule_at | string | لا | جدولة التسليم لوقت لاحق، بصيغة Y-m-d H:i:s. احذف هذا الحقل للإرسال الفوري. |
attachments | array | لا | مصفوفة الملفات المراد إرفاقها. الأنواع المسموح بها: pdf, doc, docx, xls, xlsx, csv, txt, png, jpg, jpeg, gif, zip, rar, svg, webp. تخضع لحدود المرفقات المهيأة في حسابك (الحد الأقصى لعدد الملفات وحجمها). |
مثال على الطلب
curl -X POST https://mersal.it/api/email/send \
-H "Api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact": [
{
"email": "[email protected]",
"subject": "Your July invoice is ready",
"message": "<p>Hi there, your invoice for July is attached.</p>",
"sender_name": "Mersal Billing",
"reply_to_email": "[email protected]"
}
],
"attachments": []
}'<?php
$response = Http::withHeaders([
'Api-key' => 'YOUR_API_KEY',
'Content-Type' => 'application/json',
])->post('https://mersal.it/api/email/send', [
'contact' => [
[
'email' => '[email protected]',
'subject' => 'Your July invoice is ready',
'message' => '<p>Hi there, your invoice for July is attached.</p>',
'sender_name' => 'Mersal Billing',
'reply_to_email' => '[email protected]',
],
],
'attachments' => [],
]);
$data = $response->json();<?php
$payload = [
'contact' => [
[
'email' => '[email protected]',
'subject' => 'Your July invoice is ready',
'message' => '<p>Hi there, your invoice for July is attached.</p>',
'sender_name' => 'Mersal Billing',
'reply_to_email' => '[email protected]',
],
],
'attachments' => [],
];
$ch = curl_init('https://mersal.it/api/email/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Api-key: YOUR_API_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch("https://mersal.it/api/email/send", {
method: "POST",
headers: {
"Api-key": process.env.MERSAL_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
contact: [
{
email: "[email protected]",
subject: "Your July invoice is ready",
message: "<p>Hi there, your invoice for July is attached.</p>",
sender_name: "Mersal Billing",
reply_to_email: "[email protected]",
},
],
attachments: [],
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://mersal.it/api/email/send",
headers={"Api-key": os.environ["MERSAL_API_KEY"]},
json={
"contact": [
{
"email": "[email protected]",
"subject": "Your July invoice is ready",
"message": "<p>Hi there, your invoice for July is attached.</p>",
"sender_name": "Mersal Billing",
"reply_to_email": "[email protected]",
}
],
"attachments": [],
},
)
data = response.json()مثال على الاستجابة
{
"success": true,
"message": "Email queued successfully",
"data": {
"contact": [
{
"email": "[email protected]",
"status": "queued"
}
]
}
}عند فشل التحقق من صحة البيانات، تُرجع Mersal الحالة 422:
{
"success": false,
"message": "Validation failed",
"errors": {
"contact.0.email": ["The contact.0.email must be a valid email address."]
}
}إرفاق الملفات
إذا كنت بحاجة إلى إرسال مرفقات، أرسل attachments كرفع ملفات multipart بدلاً من مصفوفة فارغة. تحقق من إعدادات Gateways في حسابك لمعرفة الحد الأقصى المهيأ لعدد الملفات وحجمها قبل الاعتماد على المرفقات في بيئة الإنتاج.
تحسين وصول البريد
لضمان وصول رسائلك لصندوق الوارد وليس الـ Spam، فعّل توقيع DKIM ونطاق التتبع الخاص بك — الشرح الكامل في إعداد DKIM ونطاقات التتبع.
الأخطاء
أكثر حالات الفشل شيوعًا هي مفتاح API مفقود أو غير صالح، أو اشتراك منتهي الصلاحية، أو خطأ تحقق 422 في contact أو attachments، أو gateway_identifier لا يشير إلى بوابة بريد إلكتروني نشطة. راجع الأخطاء ورموز الحالة للمرجع الكامل.
