رسائل واجهة API
أرسل البريد الإلكتروني والرسائل النصية ورسائل WhatsApp باسم مؤسستك، واستخدم مفتاح منع التكرار لإعادة المحاولة ضمن حدود الاحتفاظ الموثقة، وتابع نتيجة كل رسالة على حدة أو في تقرير.
يرد طلب الإرسال الناجح عادةً بالحالة 202 Accepted مع معرّف الرسالة وحالتها. قبول الطلب لا يعني تسليم المزوّد للرسالة: يتطلب الإرسال تفعيل التسليم الصادر، وتشغيل مستهلكي القناة، وضبط مزوّدها. لا يوجد وقت تسليم مضمون. في عمليات النشر التي تعطل التسليم الصادر، لا يعني قبول الطلب أن رسالة ستُرسل. يتكون المعرّف من msg_ متبوعاً بـ 32 محرفاً سداسياً عشرياً، ويمكن استخدامه لمعرفة النتيجة هنا أو في إشعار ويب.
202 تم القبول
{
"status": "success",
"data": { "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60", "status": "queued" },
"errors": null
}
إرسال بريد إلكتروني
يُرسل البريد من إحدى هويات المرسل التي تحققت منها مؤسستك، بمحتوى HTML خاص أو منشأ من أحد قوالب البريد الإلكتروني.
- اسم
to- النوع
- string[]
- وصف
اختياري عندما يوفّر
ccأوbccالمستلمين. قدّم من 1 إلى 50 إدخال عنوان إجمالاً عبرtoوccوbcc؛ ويمكن غياب أي قائمة منفردة أو تركها فارغة. يُرفض الإجمالي الفارغ علىto.
- اسم
cc- النوع
- string[]
- وصف
عناوين ترويسة Cc. تتلقى محتوى البريد نفسه الذي يتلقاه بقية المستلمين.
- اسم
bcc- النوع
- string[]
- وصف
عناوين قائمة تسليم Bcc. لا تُخفى Bcc من سجلات رسائل المرسِل أو webhooks الخاصة به.
- اسم
from- النوع
- string
- وصف
عنوان هوية تم التحقق منها، أو أي عنوان ضمن هوية نطاق تم التحقق منها. عند حذفه، يلزم وجود المرسل الأساسي المتحقق منه للمؤسسة؛ ولا يُرجع إلى هوية متحقق منها أخرى. عندما ترسل Oblic باسم هوية، يكون عنوان «من» الظاهر اسماً مستعاراً على نطاق الإرسال المضبوط لدى Oblic وليس عنوان الهوية.
- اسم
fromName- النوع
- string
- وصف
اسم المرسل، بحد أقصى 255 محرفاً، من دون
<أو>أو"أو فاصل سطر. عند حذفه يُستخدم اسم العرض للهوية. تضيف Oblic العبارةvia Oblicعند الإرسال باسم الهوية.
- اسم
replyTo- النوع
- string
- وصف
العنوان الذي تُرسل إليه الردود. عندما ترسل Oblic باسم هوية، تذهب الردود إلى العنوان الأصلي المتحقق منه ما لم يستبدله
replyTo.
- اسم
subject- النوع
- string
- وصف
بحد أقصى 1,023 محرفاً. مطلوب مع
html. معtemplateId، يُستخدم موضوع القالب إن لم تقدم موضوعاً.
- اسم
html- النوع
- string
- وصف
محتوى HTML للبريد، ويُرسل كما تقدمه. قدم
htmlأوtemplateId، ولا تقدم كليهما.
- اسم
text- النوع
- string
- وصف
نسخة نصية بسيطة تُرسل بجانب HTML لبرامج البريد التي تعرض النص. مع
templateId، تُملأ مواضع{{name}}منvariablesكما كُتبت، من دون تهريب.
- اسم
templateId- النوع
- string
- وصف
معرّف قالب البريد المراد إرساله، ويتكون من 18 حرفاً ورقماً من ASCII.
- اسم
variables- النوع
- object
- وصف
مع
templateId، قيمة لكل موضع{{name}}في القالب: بحد أقصى 100، وكل قيمة سلسلة لا تتجاوز 10,000 محرف. تطابق الأسماء دون اعتبار لحالة الأحرف. تُهرّب القيمة عند إدراجها في HTML، ولذلك يظهر النص المرسل بالشكل<b>كنص<b>.
- اسم
attachments- النوع
- object[]
- وصف
حتى 10 ملفات، كل منها بصيغة
{"fileName": …, "content": …}مع بايتات الملف بترميز base64، وبإجمالي لا يتجاوز 10 MB. يمكن قبول ملفات مثل أرشيفات ZIP وCSV وICS؛ وتُرفض الامتدادات التي يرفضها SES والمحتويات التنفيذية المكتشفة. تحتفظ عمليات رفع الحملات بقائمة السماح المنفصلة الخاصة بها.
- اسم
metadata- النوع
- object
- وصف
سلاسل نصية خاصة بك حسب المفتاح، مثل معرّف الطلب أو المستأجر، تُعاد مع الرسالة وكل إشعار ويب لها ولا تُرسل إلى المستلمين. راجع البيانات الوصفية.
تتلقى قوائم المستلمين الثلاث المحتوى نفسه. تظهر عناوين To وCc في ترويسات المستلمين؛ وتظل عناوين Bcc ظاهرة في قائمة رسائل المرسِل وwebhooks الخاصة به. لا يسجّل دفتر العمليات دور To/Cc/Bcc لكل مستلم.
تتطلب هذه القوائم إصدارات متوافقة من API ومرسِل Functions. فعّل المرسِل المحدّث قبل API أو بالتزامن معه. فحص المرفقات بوابة منفصلة تتطلب التهيئة؛ ولا يثبت القبول أن الملف فُحص أو أنه خالٍ من البرمجيات الضارة.
بريد إلكتروني بمحتوى HTML خاص
curl -X POST https://api.oblic.app/external/v1/messages/email \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-1042-confirmation' \
-d '{
"from": "orders@example.com",
"fromName": "Example Store",
"to": ["asha@example.org"],
"subject": "Your order is confirmed",
"html": "<p>Thank you for your order.</p>"
}'
بريد إلكتروني منشأ من قالب
curl -X POST https://api.oblic.app/external/v1/messages/email \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": ["asha@example.org"],
"templateId": "TEM000R7ZM4Q2VXH00",
"text": "Hi {{first_name}}, your order {{order_id}} is confirmed.",
"variables": { "first_name": "Asha", "order_id": "1042" }
}'
يُتجاوز المستلمون الذين ألغوا الاشتراك أو أُدرجوا في قائمة المنع: تكون الرسالة لهم بالحالة skipped، ويوضح الحدث email.suppressed عبر إشعار ويب السبب.
| الرفض | cd | الحالة |
|---|---|---|
| 400 | الحقل، مثل TO[0] | حقل مفقود أو غير صالح؛ وتُرفض مجموعة المستلمين المجمّعة الفارغة أو الأكبر من الحد على to |
| 400 | INVALID_REQUEST | عدم تقديم أي من html وtemplateId أو تقديم كليهما، أو وجود variables من دون قالب، أو غياب الموضوع |
| 400 | INVALID_VARIABLES | موضع بلا قيمة، أو اسم مكرر باختلاف حالة الأحرف، أو موضوع طويل جداً بعد تعبئته |
| 400 | INVALID FILE | مرفق أكبر من المسموح أو من نوع غير مقبول |
| 403 | EMAIL_SUSPENDED | عُلّق بريد الحساب بسبب الارتدادات أو شكاوى البريد المزعج إلى أن يرفع دعم Oblic التعليق |
| 413 | MESSAGE_TOO_LARGE | البريد أكبر من أن يوضع في الطابور |
| 422 | UNVERIFIED_SENDER | from لا يخص هوية متحققاً منها؛ وتعرض الرسالة الهويات المتحقق منها |
| 422 | TEMPLATE_NOT_FOUND | لا يوجد قالب بريد بهذا المعرّف |
| 422 | TEMPLATE_HAS_MENTIONS | يحتوي القالب على إشارات لوحة التحكم مثل @unsubscribe، التي لا تعبئها إلا الحملات والأتمتة |
| 429 | RATE_LIMITED | تجاوز الحد الساعي للحساب (5,000 مستلم افتراضياً)، أو حده لعنوان واحد (10 في الساعة افتراضياً)؛ يحتسب كل إرسال المستلمين المميزين بعد توحيد العناوين عبر القوائم الثلاث، فيُحتسب العنوان المكرر ضمن ذلك الإرسال مرة واحدة. يحدّد Retry-After الموعد |
| 429 | QUOTA_EXCEEDED | تجاوز عدد رسائل الحساب للشهر (100,000 افتراضياً)؛ يحدد Retry-After وقت إعادة المحاولة |
عند تفعيل عامل السمعة، تراجع إعداداته الافتراضية القابلة للتعديل بريد كل حساب خلال آخر 7 أيام بعد الإرسال إلى 500 مستلم: يُنبه المالكون عند بلوغ الارتدادات 2% أو شكاوى البريد المزعج 0.05%، ويُعلق البريد عند 4% أو 0.08% إلى أن يرفع دعم Oblic التعليق. بهذه الإعدادات لا تُقيّم شكاوى البريد المزعج إلا بعد الإرسال إلى 1,251 مستلماً، ولذلك لا تعلق شكوى واحدة الحساب. تُحسب الارتدادات الدائمة فقط، وكل مستلم مرة واحدة. لا يجري العامل المتوقف مؤقتاً أو المعطل هذه المراجعة الدورية. أثناء تعليق الحساب يُرفض البريد بالرمز EMAIL_SUSPENDED؛ ويفشل البريد المقبول سابقاً ولم يُرسل بعد مع حدث email.failed تكون فيه قيمة failureCode هي EMAIL_SUSPENDED.
إرسال رسالة نصية
تُرسل الرسالة النصية إلى رقم هاتف محمول هندي، ويجب أن تطابق أحد قوالب DLT المسموح للحساب بإرسالها: النص الثابت للقالب بدقة، مع تعبئة كل متغير. قدم النص لتجد Oblic القالب، أو قدم معرّف DLT للقالب ومتغيراته.
- اسم
to- النوع
- string
- وصف
مطلوب:
+91ثم عشرة أرقام، أولها من 6 إلى 9. تُتجاهل المسافات والشرطات.
- اسم
text- النوع
- string
- وصف
الرسالة، بحد أقصى 2,000 محرف، وفق أحد قوالبك بعد تعبئة متغيراته: كل متغير من 1 إلى 30 محرفاً في سطر واحد. النص الذي يحتوي محرفاً خارج ASCII البسيط، مثل
éأو₹، لا يطابق إلا قوالب Unicode.
- اسم
templateId- النوع
- string
- وصف
بدلاً من
text: معرّف DLT للقالب، بحد أقصى 32 رقماً.
- اسم
variables- النوع
- string[]
- وصف
مع
templateId: قيمة لكل متغير في القالب بالترتيب، بحد أقصى 30 قيمة. كل قيمة من 1 إلى 30 محرفاً في سطر واحد، باستخدام ASCII البسيط إلا إذا كان القالب Unicode.
- اسم
senderId- النوع
- string
- وصف
ترويسة DLT للإرسال، بحد أقصى 11 محرفاً، ويجب أن تكون من ترويسات القالب. عند حذفها تُفضل الترويسة الافتراضية للحساب.
- اسم
purpose- النوع
- string
- وصف
otpأوtransactional(الافتراضي) أوpromotional. لا تطابق الرسالة الترويجية إلا القوالب الترويجية، ولا تطابق الرسائل الأخرى إلا القوالب غير الترويجية.
- اسم
unicode- النوع
- boolean
- وصف
استخدم
trueللنظر في قوالب Unicode فقط.
- اسم
metadata- النوع
- object
- وصف
سلاسل نصية خاصة بك حسب المفتاح، مثل معرّف الطلب أو المستأجر، تُعاد مع الرسالة وكل إشعار ويب لها ولا تُرسل إلى المستلمين. راجع البيانات الوصفية.
رسالة نصية قصيرة
curl -X POST https://api.oblic.app/external/v1/messages/sms \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: login-7731' \
-d '{
"to": "+919812345678",
"text": "Your Example code is 482913. It is valid for 10 minutes.",
"purpose": "otp"
}'
يحتوي المقطع على ما يصل إلى 160 وحدة GSM-7؛ وتُحسب محارف التوسعة مثل ^ بوحدتين. أما رسالة Unicode النصية فتحتوي حتى 70 وحدة ترميز UTF-16: يستخدم المحرف خارج المستوى الأساسي متعدد اللغات وحدتين. تستخدم الرسائل الأطول مقاطع من 153 وحدة GSM-7 أو 67 وحدة ترميز UTF-16. تُرسل الرسالة الترويجية فقط بين 10:00 شاملة و21:00 غير شاملة بتوقيت الهند. لا تُرفض رموز تسجيل الدخول والرسائل النصية للمعاملات والخدمات بسبب محفظة فارغة.
| الرفض | cd | الحالة |
|---|---|---|
| 400 | INVALID_NUMBER | to ليس رقم هاتف محمول هندياً |
| 400 | INVALID_REQUEST | عدم تقديم أي من text وtemplateId أو تقديم كليهما |
| 400 | INVALID_VARIABLES | المتغيرات لا تطابق القالب |
| 402 | INSUFFICIENT_BALANCE | الرسالة النصية ترويجية والمحفظة التي تدفع للحساب فارغة |
| 422 | TEMPLATE_NOT_REGISTERED | النص أو templateId لا يطابق أي قالب مسموح للحساب بإرساله، أو لا يطابق أي قالب ضمن senderId |
| 422 | SENDER_NOT_ALLOWED | senderId ليس ترويسة لأي قالب مسموح للحساب بإرساله |
| 422 | MESSAGE_TYPE_NOT_ENABLED | نوع القالب ليس من الأنواع التي ترسلها Oblic: تحددها messageTypes للحساب، وافتراضياً service_implicit فقط |
| 422 | URL_NOT_WHITELISTED | متغير يحتوي رابطاً لم يُدرج نطاقه في قائمة السماح لدى DLT |
| 422 | OUTSIDE_PROMOTIONAL_HOURS | رسالة نصية ترويجية خارج الفترة من 10:00 إلى 21:00 بتوقيت الهند؛ يحدد Retry-After وقت إعادة المحاولة |
| 429 | RATE_LIMITED | تجاوز الحد الساعي للحساب (1,000 رسالة افتراضياً)، أو الحد لرقم واحد (10 في الساعة افتراضياً)؛ يحدد Retry-After وقت إعادة المحاولة |
| 429 | QUOTA_EXCEEDED | تجاوز عدد مقاطع الحساب للشهر (10,000 افتراضياً)؛ يحدد Retry-After وقت إعادة المحاولة |
| 503 | SMS_UNAVAILABLE | تعذر وضع الرسالة النصية في الطابور الآن؛ أعد المحاولة باستخدام Idempotency-Key نفسه؛ أو لم تُضبط الرسائل النصية في نشر Oblic هذا |
تعرض GET /external/v1/sms/account حدود الحساب وأنواع القوالب التي ترسلها Oblic وما أُرسل هذا الشهر.
إرسال رسالة WhatsApp
تُرسل رسالة WhatsApp من الرقم المتصل بالحساب: قالب معتمد، أو رد حر خلال 24 ساعة من آخر رسالة أرسلها الشخص إليك.
- اسم
to- النوع
- string
- وصف
مطلوب: الرقم بصيغة دولية، مثل
+919812345678.
- اسم
template- النوع
- string
- وصف
اسم أحد قوالب WhatsApp كما أنشأته. قدم
templateأوtext، ولا تقدم كليهما.
- اسم
language- النوع
- string
- وصف
لغة القالب، مثل
enأوhi؛ والافتراضيةen.
- اسم
variables- النوع
- string[]
- وصف
قيم مواضع
{{1}}و{{2}}وما يليها في القالب، بالترتيب: بحد أقصى 30، وكل قيمة لا تتجاوز 1,024 محرفاً.
- اسم
headerVariables- النوع
- string[]
- وصف
قيم متغيرات الترويسة النصية للقالب، بالترتيب: بحد أقصى 5، وكل قيمة لا تتجاوز 1,024 محرفاً.
- اسم
headerMediaUrl- النوع
- string
- وصف
رابط https للصورة أو الفيديو أو المستند الذي ترسله ترويسة القالب، بحد أقصى 2,048 محرفاً. عند حذفه، ترسل الترويسة الوسائط التي اعتُمد القالب بها.
- اسم
text- النوع
- string
- وصف
رد حر لا يتجاوز 4,096 محرفاً، ولا يمكن إرساله إلا خلال 24 ساعة من آخر رسالة أرسلها الشخص إلى رقمك.
- اسم
metadata- النوع
- object
- وصف
سلاسل نصية خاصة بك حسب المفتاح، مثل معرّف الطلب أو المستأجر، تُعاد مع الرسالة وكل إشعار ويب لها ولا تُرسل إلى المستلمين. راجع البيانات الوصفية.
قالب WhatsApp
curl -X POST https://api.oblic.app/external/v1/messages/whatsapp \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": "+919812345678",
"template": "order_shipped",
"language": "en",
"variables": ["Asha", "1042"]
}'
تُعبّأ ترويسة القالب كما يُعبّأ متنه. تملأ headerVariables متغيرات الترويسة النصية، وتحدد headerMediaUrl الصورة أو الفيديو أو المستند لترويسة الوسائط؛ وإلا تُرسل الوسائط التي اعتُمد القالب بها. يُرفض أي قالب يتطلب ما لا تستطيع API إرساله، مثل ترويسة موقع أو زر بقيمة خاصة أو متغير مسمى مثل {{first_name}}، قبل أي إرسال أو احتساب رسوم.
قالب بصورة في الترويسة
curl -X POST https://api.oblic.app/external/v1/messages/whatsapp \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": "+919812345678",
"template": "diwali_sale",
"headerMediaUrl": "https://cdn.example.com/diwali.jpg",
"variables": ["20%"]
}'
توضح GET /external/v1/whatsapp/recipients/{number} ما إذا كان الرقم قد رفض التسويق، وحتى متى يمكن إرسال رد حر.
| الرفض | cd | الحالة |
|---|---|---|
| 400 | INVALID_REQUEST | عدم تقديم أي من template وtext أو تقديم كليهما، أو تقديم headerVariables أو headerMediaUrl مع text |
| 402 | INSUFFICIENT_BALANCE | القالب تسويقي والمحفظة التي تدفع للحساب فارغة |
| 422 | INVALID_NUMBER | to ليس رقماً بصيغة دولية |
| 422 | WHATSAPP_NOT_CONNECTED | ليس للحساب رقم WhatsApp متصل |
| 422 | TEMPLATE_NOT_FOUND | ليس للحساب قالب بهذا الاسم وبهذه اللغة |
| 422 | TEMPLATE_NOT_APPROVED | لم تعتمد Meta القالب |
| 422 | INVALID_VARIABLES | عدد المتغيرات لا يطابق متن القالب أو ترويسته النصية؛ أو استُخدمت headerVariables لترويسة وسائط، أو headerMediaUrl لترويسة ليست كذلك |
| 422 | MEDIA_REQUIRED | ترويسة القالب صورة أو فيديو أو مستند، لكن headerMediaUrl ليس رابط https؛ أو عند حذفه، لا تملك الوسائط التي اعتُمد القالب بها رابط https |
| 422 | TEMPLATE_NOT_SENDABLE | يتطلب القالب ما لا تستطيع API إرساله: ترويسة موقع أو زر بقيمة خاصة أو متغير مسمى |
| 422 | RECIPIENT_OPTED_OUT | قالب تسويقي إلى رقم رفض التسويق |
| 422 | OUTSIDE_SESSION_WINDOW | رد حر بعد مرور أكثر من 24 ساعة على آخر رسالة من الشخص |
إعادة محاولة الإرسال
أرسل الترويسة Idempotency-Key مع كل إرسال، من 1 إلى 255 محرفاً تختارها، مثل معرّف الطلب أو الحدث. إذا انتهت مهلة الإرسال أو لم تعرف هل قُبل، فأعده بالمفتاح نفسه والمتن نفسه. يعتمد منع التكرار على حالة المفتاح المحتفظ بها، ولا يمثل ضماناً دائماً ضد كل طلب متكرر:
- تكرار الإرسال نفسه يعيد
202مع معرّف الرسالة الأولى، ولا تُرسل الرسالة مرتين. - المفتاح نفسه مع رسالة مختلفة، بما فيها
metadata، يُرفض بالرمز409 IDEMPOTENCY_CONFLICT، ولا يوضع شيء في الطابور. - مدة بقاء المفتاح: تُحفظ حالة مفاتيح البريد وWhatsApp في Redis لمدة 24 ساعة؛ يؤدي فقدان ذاكرة التخزين المؤقت أو انتهاء صلاحيتها إلى إزالة حالة منع التكرار، وقد يرسل المفتاح نفسه مرة أخرى بعد ذلك. لا تنتهي صلاحية مفتاح الرسالة النصية بمرور الوقت في صف الرسالة المخزن؛ تحتاج الرسالة اللاحقة مفتاحاً مستقلاً. لا تضمن هذه الحدود التسليم.
- المفاتيح تخص مؤسستك، بمجموعة لكل قناة، لذا يمكن استخدام المفتاح نفسه لبريد إلكتروني ورسالة نصية. عند استخدام
X-Oblic-On-Behalf-Ofتخص الحساب الفرعي. - تُفحص إعادة المحاولة مجدداً قبل البحث عن المطابقة: يُرفض البريد إذا لم يعد مرسله متحققاً منه، أو رد WhatsApp إذا انقضت 24 ساعة، بدلاً من إعادة المعرّف الأول.
المفتاح الفارغ أو الأطول من 255 محرفاً يعطي 400 INVALID_IDEMPOTENCY_KEY.
في البريد الإلكتروني، تدخل قائمتا cc وbcc غير الفارغتين في تجزئة منع التكرار، حتى إن ظهرت عناوينهما أيضاً في to. لا تغيّر القوائم الغائبة أو الفارغة بنية التجزئة الخاصة بـ To فقط؛ وتظل قيود الاحتفاظ بالمفتاح والأهلية المذكورة أعلاه سارية.
البيانات الوصفية
أرفق بأي إرسال metadata، أي سلاسل نصية خاصة بك حسب المفتاح، لتجد الرسالة في سجلاتك: طلب أو مستأجر أو حملة. تخزن Oblic البيانات الوصفية وتعيدها في استجابات الرسائل وإشعارات الويب، لكنها لا تفسرها لأغراض التسليم ولا تمررها إلى المستلمين أو المزوّدين. لا تخفي الأسرار أو القيم الحساسة: تحقق مما تضيفه؛ اسم مفتاح مسموح لا يعني وجود مرشح خصوصية.
رسالة نصية ببيانات وصفية
{
"to": "+919876543210",
"text": "Your order 1042 has shipped.",
"metadata": { "orderId": "1042", "tenant": "acme" }
}
- حتى 20 مفتاحاً، كل منها من 1 إلى 40 حرفاً ورقماً من ASCII أو
_أو.أو-، وكل قيمة سلسلة لا تتجاوز 500 محرف. يُحفظ الرقم أوtrueكما كُتب في صورة السلسلة"1042"أو"true"؛ ويُرفضnullأو الكائن بالرمز400، ولا يوضع شيء في الطابور. - تُعاد البيانات في جلب رسالة، وفي كل عنصر من قائمة الرسائل، وكقيمة
data.metadataفي كل إشعار ويب للرسالة:{}إن أُرسلت الرسالة من دونها. - جزء من الرسالة: استخدام
Idempotency-Keyنفسه مع بيانات وصفية أخرى يعني رسالة مختلفة، ويعطي409 IDEMPOTENCY_CONFLICT.
قائمة الرسائل
الرسائل المرسلة عبر API، الأحدث أولاً، بعنصر لكل مستلم: البريد إلى ثلاثة عناوين يعطي ثلاثة عناصر لها id نفسه.
- اسم
channel- النوع
- string
- وصف
emailأوsmsأوwhatsapp؛ كرر المعامل لاختيار أكثر من قيمة.
- اسم
status- النوع
- string
- وصف
queuedأوsentأوdeliveredأوreadأوbouncedأوskippedأوfailed؛ كرر المعامل لاختيار أكثر من قيمة.
- اسم
since- النوع
- string
- وصف
أقدم وقت لطلب الإرسال، شاملاً الحد، بصيغة ISO 8601 مع
Zأو إزاحة UTC صريحة، مثل2026-10-01T00:00:00Z. الوقت المحلي من دون إزاحة لا يمثل لحظة محددة.
- اسم
until- النوع
- string
- وصف
أحدث وقت لطلب الإرسال، غير شامل للحد، مع
Zأو إزاحة UTC صريحة أيضاً.
- اسم
limit- النوع
- integer
- وصف
عدد النتائج، من 1 إلى 100؛ والافتراضي 25.
- اسم
cursor- النوع
- string
- وصف
قيمة
nextمن الصفحة السابقة لقراءة الصفحة التالية. راجع ترقيم الصفحات.
رسائل البريد المتجاوزة هذا الأسبوع
curl -G https://api.oblic.app/external/v1/messages \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d channel=email \
-d status=skipped \
-d since=2026-10-19T00:00:00Z
الاستجابة
{
"status": "success",
"data": {
"messages": [
{
"id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
"channel": "email",
"to": "ravi@example.org",
"status": "skipped",
"reason": "unsubscribed",
"requestedAt": "2026-10-20T08:15:02.120Z",
"sentAt": null,
"deliveredAt": null,
"readAt": null,
"failedAt": null,
"openedAt": null,
"clickedAt": null,
"metadata": { "orderId": "1042" }
}
],
"next": null
},
"errors": null
}
statusتستخدم المجموعة نفسها لكل القنوات:queued(لم تُرسل بعد)، وsent(قبلها المزوّد)، وdelivered، وread، وbounced، وskipped(لم تُرسل، مثل عنوان ألغى الاشتراك أو حُظر)، وfailed. توضحreasonالسبب، مثلunsubscribedأوsuppressedللرسالة المتجاوزة.toهو عنوان البريد، أو رقم الرسالة النصية مع+91، أو أرقام رقم WhatsApp من دون+.- الأوقات تبين وقت وقوع كل حدث، أو تكون
null؛ ويخصopenedAtوclickedAtالبريد الإلكتروني. metadataهي البيانات التي أُرفقت بالرسالة عند الإرسال، أو{}.
جلب رسالة
رسالة واحدة ونتيجتها، باستخدام المعرّف الذي أعاده الإرسال. تتشابه استجابتا الرسالة النصية وWhatsApp؛ تتضمن الأولى segments والثانية readAt. وللبريد شكل خاص، بعنصر لكل مستلم مع وصول أحداثه.
رسالة نصية قصيرة
{
"status": "success",
"data": {
"id": "msg_9a1b2c3d4e5f60718293a4b5c6d7e8f9",
"channel": "sms",
"status": "delivered",
"segments": 1,
"sentAt": "2026-10-20T08:15:03.410Z",
"deliveredAt": "2026-10-20T08:15:06.902Z",
"failedAt": null,
"failureCode": null,
"metadata": { "orderId": "1042" }
},
"errors": null
}
رسالة بريد إلكتروني
{
"status": "success",
"data": {
"id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
"status": "sent",
"recipients": [
{
"email": "asha@example.org",
"deliveredAt": "2026-10-20T08:16:11Z",
"openedAt": "2026-10-20T09:02:40Z",
"bouncedAt": null,
"complainedAt": null,
"delayedAt": null
}
],
"metadata": {}
},
"errors": null
}
- قيمة
statusللرسالة النصية هيqueuedأوsentأوdeliveredأوundeliveredأوfailed. - حالة رسالة WhatsApp هي
queuedأوsentأوdeliveredأوreadأوfailed، معreadAt. تأتي قيمةfailureCodeمن Meta، مثلmeta:131026. - حالة البريد الإلكتروني هي
queuedحتى يُرسل، ثمsent، أوpartially_suppressedعند تجاوز بعض المستلمين، أوsuppressedعند تجاوزهم جميعاً، أوfailedعند تعذر الإرسال. تأتي أوقات كل مستلم من أحداث مزوّد البريد، ولذلك تكونrecipientsفارغة حتى الحدث الأول. metadataهي البيانات المرفقة عند الإرسال، أو{}؛ راجع البيانات الوصفية.
الرسالة غير الموجودة أو التي لا تخص الحساب تعيد 404 MESSAGE_NOT_FOUND. البريد الذي لم يُرسل قط يصبح غير موجود هنا بعد 24 ساعة، لكنه يظل ظاهراً في القائمة.
ملخص التقرير
نتائج الرسائل التي طُلب إرسالها خلال فترة، محسوبة حسب القناة والحالة، مع عدد رسائل البريد المفتوحة أو المنقور عليها أو المعلّمة كبريد مزعج.
- اسم
from- النوع
- string
- وصف
بداية الفترة، شاملة، بصيغة ISO 8601 مع
Zأو إزاحة UTC صريحة؛ والافتراضي 30 يوماً قبلto.
- اسم
to- النوع
- string
- وصف
نهاية الفترة، غير شاملة، مع
Zأو إزاحة UTC صريحة أيضاً؛ والافتراضي الوقت الحالي. يجب أن تكون بعدfromوبفارق لا يتجاوز 92 يوماً.
الاستجابة
{
"status": "success",
"data": {
"from": "2026-09-24T00:00:00Z",
"to": "2026-10-24T00:00:00Z",
"all": {
"messages": 1250,
"statuses": { "queued": 4, "sent": 96, "delivered": 1075, "read": 30, "bounced": 12, "skipped": 18, "failed": 15 },
"opened": 410,
"clicked": 96,
"complained": 1
},
"channels": {
"email": { "messages": 800, "statuses": { "queued": 2, "sent": 40, "delivered": 728, "read": 0, "bounced": 12, "skipped": 18, "failed": 0 }, "opened": 410, "clicked": 96, "complained": 1 },
"sms": { "messages": 300, "statuses": { "queued": 1, "sent": 36, "delivered": 253, "read": 0, "bounced": 0, "skipped": 0, "failed": 10 }, "opened": 0, "clicked": 0, "complained": 0 },
"whatsapp": { "messages": 150, "statuses": { "queued": 1, "sent": 20, "delivered": 94, "read": 30, "bounced": 0, "skipped": 0, "failed": 5 }, "opened": 0, "clicked": 0, "complained": 0 }
}
},
"errors": null
}
تظهر دائماً جميع القنوات والحالات، محسوبة بمصطلحات القائمة نفسها. إذا كانت from عند to أو بعدها، أو تجاوز الفرق 92 يوماً، تكون النتيجة 400 INVALID_PERIOD.