رسائل واجهة API

أرسل البريد الإلكتروني والرسائل النصية ورسائل WhatsApp باسم مؤسستك، واستخدم مفتاح منع التكرار لإعادة المحاولة ضمن حدود الاحتفاظ الموثقة، وتابع نتيجة كل رسالة على حدة أو في تقرير.

يرد طلب الإرسال الناجح عادةً بالحالة 202 Accepted مع معرّف الرسالة وحالتها. قبول الطلب لا يعني تسليم المزوّد للرسالة: يتطلب الإرسال تفعيل التسليم الصادر، وتشغيل مستهلكي القناة، وضبط مزوّدها. لا يوجد وقت تسليم مضمون. في عمليات النشر التي تعطل التسليم الصادر، لا يعني قبول الطلب أن رسالة ستُرسل. يتكون المعرّف من msg_ متبوعاً بـ 32 محرفاً سداسياً عشرياً، ويمكن استخدامه لمعرفة النتيجة هنا أو في إشعار ويب.

202 تم القبول

{
  "status": "success",
  "data": { "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60", "status": "queued" },
  "errors": null
}

POST/external/v1/messages/email

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

يُرسل البريد من إحدى هويات المرسل التي تحققت منها مؤسستك، بمحتوى 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
400INVALID_REQUESTعدم تقديم أي من html وtemplateId أو تقديم كليهما، أو وجود variables من دون قالب، أو غياب الموضوع
400INVALID_VARIABLESموضع بلا قيمة، أو اسم مكرر باختلاف حالة الأحرف، أو موضوع طويل جداً بعد تعبئته
400INVALID FILEمرفق أكبر من المسموح أو من نوع غير مقبول
403EMAIL_SUSPENDEDعُلّق بريد الحساب بسبب الارتدادات أو شكاوى البريد المزعج إلى أن يرفع دعم Oblic التعليق
413MESSAGE_TOO_LARGEالبريد أكبر من أن يوضع في الطابور
422UNVERIFIED_SENDERfrom لا يخص هوية متحققاً منها؛ وتعرض الرسالة الهويات المتحقق منها
422TEMPLATE_NOT_FOUNDلا يوجد قالب بريد بهذا المعرّف
422TEMPLATE_HAS_MENTIONSيحتوي القالب على إشارات لوحة التحكم مثل @unsubscribe، التي لا تعبئها إلا الحملات والأتمتة
429RATE_LIMITEDتجاوز الحد الساعي للحساب (5,000 مستلم افتراضياً)، أو حده لعنوان واحد (10 في الساعة افتراضياً)؛ يحتسب كل إرسال المستلمين المميزين بعد توحيد العناوين عبر القوائم الثلاث، فيُحتسب العنوان المكرر ضمن ذلك الإرسال مرة واحدة. يحدّد Retry-After الموعد
429QUOTA_EXCEEDEDتجاوز عدد رسائل الحساب للشهر (100,000 افتراضياً)؛ يحدد Retry-After وقت إعادة المحاولة

عند تفعيل عامل السمعة، تراجع إعداداته الافتراضية القابلة للتعديل بريد كل حساب خلال آخر 7 أيام بعد الإرسال إلى 500 مستلم: يُنبه المالكون عند بلوغ الارتدادات 2% أو شكاوى البريد المزعج 0.05%، ويُعلق البريد عند 4% أو 0.08% إلى أن يرفع دعم Oblic التعليق. بهذه الإعدادات لا تُقيّم شكاوى البريد المزعج إلا بعد الإرسال إلى 1,251 مستلماً، ولذلك لا تعلق شكوى واحدة الحساب. تُحسب الارتدادات الدائمة فقط، وكل مستلم مرة واحدة. لا يجري العامل المتوقف مؤقتاً أو المعطل هذه المراجعة الدورية. أثناء تعليق الحساب يُرفض البريد بالرمز EMAIL_SUSPENDED؛ ويفشل البريد المقبول سابقاً ولم يُرسل بعد مع حدث email.failed تكون فيه قيمة failureCode هي EMAIL_SUSPENDED.


POST/external/v1/messages/sms

إرسال رسالة نصية

تُرسل الرسالة النصية إلى رقم هاتف محمول هندي، ويجب أن تطابق أحد قوالب 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الحالة
400INVALID_NUMBERto ليس رقم هاتف محمول هندياً
400INVALID_REQUESTعدم تقديم أي من text وtemplateId أو تقديم كليهما
400INVALID_VARIABLESالمتغيرات لا تطابق القالب
402INSUFFICIENT_BALANCEالرسالة النصية ترويجية والمحفظة التي تدفع للحساب فارغة
422TEMPLATE_NOT_REGISTEREDالنص أو templateId لا يطابق أي قالب مسموح للحساب بإرساله، أو لا يطابق أي قالب ضمن senderId
422SENDER_NOT_ALLOWEDsenderId ليس ترويسة لأي قالب مسموح للحساب بإرساله
422MESSAGE_TYPE_NOT_ENABLEDنوع القالب ليس من الأنواع التي ترسلها Oblic: تحددها messageTypes للحساب، وافتراضياً service_implicit فقط
422URL_NOT_WHITELISTEDمتغير يحتوي رابطاً لم يُدرج نطاقه في قائمة السماح لدى DLT
422OUTSIDE_PROMOTIONAL_HOURSرسالة نصية ترويجية خارج الفترة من 10:00 إلى 21:00 بتوقيت الهند؛ يحدد Retry-After وقت إعادة المحاولة
429RATE_LIMITEDتجاوز الحد الساعي للحساب (1,000 رسالة افتراضياً)، أو الحد لرقم واحد (10 في الساعة افتراضياً)؛ يحدد Retry-After وقت إعادة المحاولة
429QUOTA_EXCEEDEDتجاوز عدد مقاطع الحساب للشهر (10,000 افتراضياً)؛ يحدد Retry-After وقت إعادة المحاولة
503SMS_UNAVAILABLEتعذر وضع الرسالة النصية في الطابور الآن؛ أعد المحاولة باستخدام Idempotency-Key نفسه؛ أو لم تُضبط الرسائل النصية في نشر Oblic هذا

تعرض GET /external/v1/sms/account حدود الحساب وأنواع القوالب التي ترسلها Oblic وما أُرسل هذا الشهر.


POST/external/v1/messages/whatsapp

إرسال رسالة 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الحالة
400INVALID_REQUESTعدم تقديم أي من template وtext أو تقديم كليهما، أو تقديم headerVariables أو headerMediaUrl مع text
402INSUFFICIENT_BALANCEالقالب تسويقي والمحفظة التي تدفع للحساب فارغة
422INVALID_NUMBERto ليس رقماً بصيغة دولية
422WHATSAPP_NOT_CONNECTEDليس للحساب رقم WhatsApp متصل
422TEMPLATE_NOT_FOUNDليس للحساب قالب بهذا الاسم وبهذه اللغة
422TEMPLATE_NOT_APPROVEDلم تعتمد Meta القالب
422INVALID_VARIABLESعدد المتغيرات لا يطابق متن القالب أو ترويسته النصية؛ أو استُخدمت headerVariables لترويسة وسائط، أو headerMediaUrl لترويسة ليست كذلك
422MEDIA_REQUIREDترويسة القالب صورة أو فيديو أو مستند، لكن headerMediaUrl ليس رابط https؛ أو عند حذفه، لا تملك الوسائط التي اعتُمد القالب بها رابط https
422TEMPLATE_NOT_SENDABLEيتطلب القالب ما لا تستطيع API إرساله: ترويسة موقع أو زر بقيمة خاصة أو متغير مسمى
422RECIPIENT_OPTED_OUTقالب تسويقي إلى رقم رفض التسويق
422OUTSIDE_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.

GET/external/v1/messages

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

الرسائل المرسلة عبر 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 هي البيانات التي أُرفقت بالرسالة عند الإرسال، أو {}.

GET/external/v1/messages/{messageId}

جلب رسالة

رسالة واحدة ونتيجتها، باستخدام المعرّف الذي أعاده الإرسال. تتشابه استجابتا الرسالة النصية و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 ساعة، لكنه يظل ظاهراً في القائمة.


GET/external/v1/reports/summary

ملخص التقرير

نتائج الرسائل التي طُلب إرسالها خلال فترة، محسوبة حسب القناة والحالة، مع عدد رسائل البريد المفتوحة أو المنقور عليها أو المعلّمة كبريد مزعج.

  • اسم
    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.

هل كانت هذه الصفحة مفيدة؟