POST/api/v2/messages/bulk/{jobId}/cancel

إلغاء مهمة الإرسال الجماعي

يقبل الإلغاء ما لم تكن المهمة completed أو cancelled أو rejected. بلا جسم. النافذة الحالية قد تكمل ثم تصبح الصفوف غير المرسلة cancelled. استعلم حتى تتغير الحالة.

متى تستخدمه. إيقاف نهائي للصفوف التي لم تُرسَل.

مثال الطلب

مثال صحيح: صحيح: طلب الإلغاء

curl --location 'https://raselsms.com/api/v2/messages/bulk/64b0c0ff0000000000000001/cancel' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json'

مثال خاطئ: خطأ: مهمة منتهية

curl --location 'https://raselsms.com/api/v2/messages/bulk/64b0c0ff0000000000000001/cancel' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json'

مثال الاستجابة

200 — صحيح: طلب الإلغاء

{  "success": true,  "job": {    "id": "64b0c0ff0000000000000001",    "name": "Morning notices",    "status": "running",    "messagesPerSecond": 10,    "pauseReason": null,    "total": 2,    "validatedCount": 2,    "counts": {      "pending": 1,      "sent": 1,      "failed": 0,      "cancelled": 0    },    "errorCode": null,    "errorMessage": null,    "createdAt": "2026-09-24T12:00:00.000Z"  }}

409 — خطأ: مهمة منتهية

{  "success": false,  "code": "JOB_NOT_CANCELLABLE",  "error": "Job cannot be cancelled"}

200 — قُبل طلب الإلغاء.

{  "success": true,  "job": {    "id": "64b0c0ff0000000000000001",    "name": "Morning notices",    "status": "running",    "messagesPerSecond": 10,    "pauseReason": null,    "total": 2,    "validatedCount": 2,    "counts": {      "pending": 0,      "sent": 0,      "failed": 0,      "cancelled": 0    },    "errorCode": null,    "errorMessage": null,    "createdAt": "2026-09-24T12:00:00.000Z"  }}

404 — لا توجد مهمة بهذا المعرّف لهذا الحساب. الرمز JOB_NOT_FOUND.

{  "success": false,  "code": "JOB_NOT_FOUND",  "error": "Job was not found"}

401 — مفتاح API مفقود أو غير صالح.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "UNAUTHORIZED",  "error": "Missing or invalid API key"}

403 — الهاتف غير موثّق أو تنقص صلاحية messages:create. الرمز FORBIDDEN.

{  "success": false,  "code": "FORBIDDEN",  "error": "Phone not verified or missing permission"}

429 — تم تجاوز حد الطلبات. انتظر Retry-After إن وُجد.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "RATE_LIMITED",  "error": "Rate limit exceeded",  "retryAfterSeconds": 30}

طلب HTTP

POST /api/v2/messages/bulk/{jobId}/cancel

ترويسات الطلب

الترويسة	النوع	الوصف
X-API-Key	string	مفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. *

معاملات المسار

الحقل	النوع	الوصف
jobId	string	معرّف المهمة من رد الإنشاء. المهمة ظاهرة لصاحب المفتاح فقط. *

حقول الاستجابة

الحقل	النوع	الوصف
success	enum	صحيح عندما ينجح الإجراء، أو عندما ينجح مستلم واحد على الأقل في الدفعة. *
job	object	تفاصيل المهمة. الحقول التالية تخص هذه المهمة فقط ولا تظهر لحساب آخر. *
job.id	string	معرّف المورد. *
job.name	string	الاسم الظاهر أو معرّف القالب الإنجليزي الصغير، حسب المسار. *
job.status	enum	حالة التسليم أو السجل. في الإرسال: sent أو queued أو scheduled. في الموارد الأخرى هي فلتر الحالة أو قيمتها. *
job.messagesPerSecond	integer	سقف السرعة: عدد صحيح من 1 إلى 10. الصفر والكسور وما فوق 10 يرفض الطلب قبل إنشاء المهمة. السقف مشترك بين مهام الحساب حسب ترتيب إنشائها. *
job.pauseReason	enum	يظهر فقط والمهمة paused. insufficient_balance وprovider_rate_limit يوقفان النافذة الحالية. user يعني أن الحساب طلب الإيقاف. *
job.total	integer	إجمالي الصفوف المطابقة. *
job.validatedCount	integer	كم صفاً اكتمل فحصه بينما الحالة validating. *
job.counts	object	عدّادات الصفوف. تبقى منفصلة حتى لو اكتملت المهمة وفيها صفوف فاشلة. *
job.counts.pending	integer	صفوف لم تُرسل بعد. *
job.counts.sent	integer	صفوف قُبلت للتسليم. تظهر أيضاً في سجل الرسائل العادي. *
job.counts.failed	integer	صفوف فشلت. المهمة المكتملة قد تبقى فيها صفوف فاشلة. *
job.counts.cancelled	integer	صفوف أُلغيت قبل الإرسال. *
job.errorCode	string	رمز المهمة عندما تكون rejected: VALIDATION_FAILED (فشل فحص صف أو أكثر ولم يُرسل شيء)، أو INSUFFICIENT_BALANCE (الحساب لا يستطيع إرسال رسالة واحدة ولم يُرسل شيء)، أو INTAKE_INCOMPLETE (التخزين لم يكتمل ولم يُرسل شيء). *
job.errorMessage	string	شرح قصير آمن لعرضه لصاحب الحساب. طابق قراراتك على code لا على هذا النص. *
job.createdAt	string	وقت الإنشاء.

رموز الحالة

الحالة	الوصف
200	نجاح.
401	مفتاح API مفقود أو غير صالح.
403	الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء.
404	المورد غير موجود لمالك مفتاح API.
409	تعارض، مثل إعادة استخدام مفتاح Idempotency بجسم مختلف، أو جلسة غير جاهزة.
429	تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى.

جرّب الطلب

مفتاح الـ API

المتغيرات

jobId*

معرّف المهمة من رد الإنشاء. المهمة ظاهرة لصاحب المفتاح فقط.

الطلب

{}

الاستجابة

نفّذ طلباً لعرض الاستجابة.