للمطوّرين

واجهة موجز البرمجية (API)

اربط موقعك أو خادمك بنشرتك: اقرأ مشتركيك وأضفهم، واعرض منشوراتك على موقعك، واطّلع على أرقامك الحقيقية، واستقبل أحداثًا موقّعة.

العنوان الأساسي
https://api.mujaz.io/api/v1
الإصدار
v1

متاحة من خطة برو. الإضافة الجماعية وخطافات الويب من خطة الأعمال. الخلاصات (RSS و JSON Feed) لكل الخطط.

البداية السريعة

  1. 1. في موجز افتح الإعدادات ← API واضغط «إنشاء مفتاح». لا يرى هذا التبويب إلا مالك الحساب ومن له دور المشرف العام (Super Admin).
  2. 2. اختر صلاحية المفتاح: «مفتاح الموقع» لعرض منشوراتك، أو «قراءة فقط»، أو «قراءة وكتابة». ثم انسخ المفتاح فورًا: يظهر كاملًا مرة واحدة فقط.
  3. 3. احفظه في متغيّر بيئة على خادمك، ثم جرّب هذا الطلب. إن رأيت اسم نشرتك فالمفتاح يعمل.
bash
export MUJAZ_API_KEY="mjz_live_7Kp2Qx9a_…"

curl https://api.mujaz.io/api/v1/me \
  -H "Authorization: Bearer $MUJAZ_API_KEY"

المصادقة

أرسل المفتاح في ترويسة Authorization فقط: Authorization: Bearer mjz_live_…. لا تُقرأ ملفات تعريف الارتباط (Cookies) في الواجهة، والمفتاح في الرابط (?api_key=) يُرفض برمز KEY_IN_URL.

المفتاح يتبع حسابًا واحدًا (علامة تجارية واحدة) إلى الأبد. نحفظ بصمته فقط، لا المفتاح نفسه، لذا لا نستطيع عرضه مرة أخرى. بعد إنشائه يظهر هكذا: mjz_live_7Kp2Qx9a_…wxyz (المعرّف وآخر أربعة أحرف).

صلاحيات المفاتيح

المفتاحيصل إلىفي المتصفح
مفتاح الموقع (posts:read)GET /me ومنشوراتك المنشورة فقطمسموح
قراءة فقط (read)كل طلبات GETمرفوض
قراءة وكتابة (write)كل شيءمرفوض

تُختار الصلاحية عند الإنشاء ولا تتغيّر؛ أنشئ مفتاحًا جديدًا إن احتجت غيرها. ويمكنك أن تجعل المفتاح ينتهي بعد 30 أو 90 أو 365 يومًا، أو ألّا ينتهي أبدًا (الافتراضي).

أي طلب يحمل ترويسة Origin (أي صادر من صفحة في متصفح) يُرفض برمز BROWSER_NOT_ALLOWED، إلا مفتاح الموقع على /me و/posts. هكذا يفشل المفتاح الذي يُلصق في صفحة ويب فورًا، قبل أن يُسرق.

إن تسرّب مفتاح، ألغِه من الإعدادات ← API: يتوقف خلال 30 ثانية على كل خوادمنا. يصل إلى مالك الحساب بريد عند إنشاء كل مفتاح جديد، ويظهر في القائمة آخر استخدام للمفتاح وعنوان IP الذي استخدمه.

اعرض منشوراتك على موقعك

طريقتان تعرضان بالضبط ما تعرضه صفحتك العامة: المنشورات المنشورة والعامة فقط، لا المسودات ولا المجدولة ولا المخفية.

1. الخلاصة (Feed): بلا مفتاح، لكل الخطط

لكل نشرة خلاصة RSS 2.0 وخلاصة JSON Feed 1.1 بآخر 20 منشورًا مع نصّها الكامل. ضعها في ووردبريس أو أي قارئ خلاصات أو أداة أتمتة. إن كان لنشرتك نطاق خاص فعّال، تعمل الخلاصة عليه أيضًا.

text
https://www.mujaz.io/@mynewsletter/feed.xml     # RSS 2.0
https://www.mujaz.io/@mynewsletter/feed.json    # JSON Feed 1.1

https://newsletter.example.com/feed.xml     # on your own domain
https://newsletter.example.com/feed.json

تتحدّث الخلاصة خلال ثوانٍ من نشر منشور جديد، وخلال 10 دقائق على الأكثر. معرّف كل منشور (mujaz:post:<id>) ثابت حتى لو غيّرت رابطه أو نطاقك، فلا يظهر منشور مرتين في القارئ.

2. واجهة المنشورات بمفتاح الموقع: برو وما فوق

لتصميم قائمة منشورات خاصة بموقعك، أنشئ «مفتاح موقع». هذا المفتاح لا يقرأ إلا ما هو منشور على صفحتك أصلًا، لذا يمكن وضعه في صفحة ويب: إن تسرّب، لا يكشف أي بيانات مشتركين.

posts.html
<ul id="mujaz-posts"></ul>
<script>
  // A Website key (posts:read) only. Never a Read-only or Read-and-write key.
  const MUJAZ_WEBSITE_KEY = "mjz_live_7Kp2Qx9a_…";

  fetch("https://api.mujaz.io/api/v1/posts?limit=5", {
    headers: { Authorization: "Bearer " + MUJAZ_WEBSITE_KEY },
  })
    .then((res) => res.json())
    .then(({ data }) => {
      const list = document.getElementById("mujaz-posts");
      for (const post of data) {
        const item = document.createElement("li");
        const link = document.createElement("a");
        link.href = post.url;
        link.textContent = post.title; // textContent, never innerHTML
        item.dir = post.language === "ar" ? "rtl" : "ltr";
        item.appendChild(link);
        list.appendChild(item);
      }
    });
</script>

كل طلب يُحسب من حدّ حسابك في الدقيقة (60 في برو، 300 في الأعمال)، ومن كل زائر يفتح الصفحة طلب. إن كان موقعك كثير الزيارات، اجلب المنشورات من خادمك وخزّنها مؤقتًا بضع دقائق، أو استخدم الخلاصة.

الإشارة إلى موجز

كل رد من /posts يحمل الحقل attribution: نص الشارة بالعربية والإنجليزية (textAr وtext)، ورابطها url إلى صفحتك العامة، وسطرًا جاهزًا (lineAr وline). وcontentHtml، حين يكون موجودًا، ينتهي بهذا السطر في فقرة <p>.

badge.html
<ul id="mujaz-posts"></ul>
<p id="mujaz-badge"></p>
<script>
  fetch("https://api.mujaz.io/api/v1/posts?limit=5", {
    headers: { Authorization: "Bearer " + MUJAZ_WEBSITE_KEY },
  })
    .then((res) => res.json())
    .then(({ data, attribution }) => {
      // … your list of posts (see above) …
      const badge = document.createElement("a");
      badge.href = attribution.url;
      badge.target = "_blank";
      badge.rel = "noopener";
      badge.textContent = document.documentElement.lang === "ar" ? attribution.textAr : attribution.text;
      document.getElementById("mujaz-badge").appendChild(badge);
    });
</script>

لا تريد أن تكتب شيئًا؟ في «الإعدادات» ← «تكامل النماذج» ← «كود التضمين» صندوق جاهز بأحدث أعدادك ونموذج اشتراك، والشارة فيه.

الأخطاء

كل خطأ يعود بالشكل نفسه: رمز ثابت تبني عليه شيفرتك، ورسالة بالإنجليزية والعربية تعرضها لمستخدمك، ومعرّف الطلب الذي تذكره لنا إن راسلت الدعم.

json
{
  "status": "error",
  "code": "KEY_INVALID",
  "message": "This API key isn't valid. Check that you copied all of it.",
  "messageAr": "مفتاح API هذا غير صالح. تأكد أنك نسخته كاملًا.",
  "requestId": "req_4f1c09a2b7d3e811"
}

أخطاء التحقق (VALIDATION_FAILED) تضيف errors بحقل لكل مشكلة. الحقول غير المعروفة خطأ أيضًا: firstname بدل firstName يُرفض ولا يُتجاهل بصمت.

json
{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "Some fields aren't valid.",
  "messageAr": "بعض الحقول غير صالحة.",
  "errors": [
    { "field": "firstname", "code": "unknown", "message": "…", "messageAr": "…" }
  ],
  "requestId": "req_…"
}

حدود الطلبات

الخطةطلبات في الدقيقةمفاتيح فعّالةالإضافة الجماعيةخطافات الويب
برو602——
الأعمال و Scale30010حتى 1,000 في الطلب، 30 طلبًا في الساعةحتى 5 عناوين

الحد للحساب كله لا للمفتاح: مفتاحان لا يضاعفان الحد. لكل علامة تجارية (Brand) حدّها الخاص. كل رد يحمل X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset (بالثواني منذ 1970). عند التجاوز يعود 429 RATE_LIMITED مع Retry-After: انتظر تلك الثواني ثم أعد المحاولة.

20 طلبًا بمفتاح خاطئ في الدقيقة من عنوان IP واحد تُوقف ذلك العنوان 10 دقائق (TOO_MANY_BAD_KEYS).

إعادة المحاولة الآمنة (Idempotency)

أرسل ترويسة Idempotency-Key (من 1 إلى 100 حرف: أحرف لاتينية وأرقام و_.:-) مع أي طلب POST أو PATCH أو DELETE. إن انقطع الاتصال وأعدت الطلب نفسه بالمفتاح نفسه خلال 24 ساعة، يعود الرد المحفوظ مع Idempotent-Replayed: true ولا يُنفَّذ شيء مرتين. ننصح بها في الإضافة والإضافة الجماعية وإلغاء الاشتراك.

bash
curl -X POST https://api.mujaz.io/api/v1/subscribers \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-2026-11-18-reader-example-com" \
  -d '{ "email": "[email protected]" }'
  • المفتاح نفسه مع طلب مختلف ← 422 IDEMPOTENCY_KEY_REUSED.
  • المفتاح نفسه والطلب الأول ما زال يعمل ← 409 IDEMPOTENCY_IN_PROGRESS. أعد المحاولة بعد لحظة.
  • خطأ من جهتنا (5xx) لا يُحفظ، فتُنفَّذ الإعادة من جديد.

التصفّح بين الصفحات

القوائم تعود بـ limit عنصر (من 1 إلى 100، الافتراضي 50؛ المنشورات حتى 50، الافتراضي 20) ومعها pagination. لجلب الصفحة التالية أرسل nextCursor في cursor، حتى يصير hasMore يساوي false. أضف includeTotal=true لتعرف العدد الكلي.

json
{
  "status": "success",
  "data": [ … ],
  "pagination": { "nextCursor": "eyJpZCI6IjY3NDBjMWYy…", "hasMore": true }
}

المؤشر لا يتباطأ مع عمق الصفحات، ولا يكرّر عنصرًا ولا يُسقطه إن أُضيف مشترك أثناء التصفّح. لمزامنة كاملة من الأقدم إلى الأحدث استخدم order=asc.

الحساب

الحساب والمفتاح

GET/me
المفتاح المطلوب: مفتاح الموقع

يعيد الحساب الذي يتبعه المفتاح، والمفتاح نفسه، والخطة والحدود. أبسط طلب لتجربة المفتاح. مع مفتاح الموقع يعود الحساب والمفتاح وlimits.perMinute فقط.

graceUntil تاريخ حين تنتهي خطتك: تبقى المفاتيح تعمل 30 يومًا، وتحمل الردود Mujaz-Api-Warning: plan-ended; until=<ISO>.

الطلب
curl https://api.mujaz.io/api/v1/me \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": {
    "workspace": {
      "id": "6720f0a1b2c3d4e5f6a7b8c9",
      "name": "نشرتي",
      "handle": "mynewsletter",
      "isBrand": false,
      "publicUrl": "https://www.mujaz.io/@mynewsletter"
    },
    "key": { "keyId": "7Kp2Qx9a", "name": "WordPress", "scope": "write", "createdAt": "2026-11-18T09:00:00.000Z", "expiresAt": null },
    "plan": "pro",
    "tier": "pro",
    "limits": { "perMinute": 60, "bulk": false, "webhooks": false },
    "graceUntil": null
  }
}

المشتركون

كائن المشترك نفسه في كل رد. لا نعيد أبدًا عنوان IP المشترك ولا رموز التأكيد. أرقام engagement هي العدّادات المخزّنة الحقيقية، بلا تقديرات.

قائمة المشتركين

GET/subscribers
المفتاح المطلوب: قراءة فقط

المشتركون من الأحدث إلى الأقدم (أو العكس)، مع عوامل تصفية.

معاملات العنوان (Query)

status
active,pending,unsubscribed,bounced,complainedاختياري
حالة أو أكثر، مفصولة بفواصل.
list
idاختياري
المشتركون في هذه القائمة.
tag
stringاختياري
المشتركون الذين يحملون هذا الوسم.
language
ar | enاختياري
لغة المشترك.
email
stringاختياري
عنوان بريد بعينه (مطابقة تامة).
createdAfter / createdBefore
ISO 8601اختياري
حدود تاريخ الانضمام.
order
desc | ascاختياري
desc (الافتراضي) الأحدث أولًا، وasc للمزامنة من الأقدم.
limit
1–100اختياري
عدد العناصر في الصفحة (الافتراضي 50).
cursor
stringاختياري
قيمة nextCursor من الصفحة السابقة.
includeTotal
trueاختياري
يضيف total إلى pagination.
الطلب
curl "https://api.mujaz.io/api/v1/subscribers?status=active&limit=2" \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": [
    {
      "id": "6740c1f2a9b8e4d3c2b1a0f9",
      "email": "[email protected]",
      "firstName": "Lina",
      "lastName": "",
      "language": "ar",
      "status": "active",
      "tags": ["vip"],
      "lists": ["6731aa04c2e9d8f7b6a5e4d3"],
      "source": "api",
      "sourceRef": "wordpress-footer",
      "createdAt": "2026-11-18T10:00:00.000Z",
      "updatedAt": "2026-11-18T10:00:00.000Z",
      "unsubscribedAt": null,
      "confirmationSentAt": null,
      "engagement": { "opens": 12, "clicks": 3, "lastOpenedAt": "2026-11-17T08:12:00.000Z", "lastClickedAt": "2026-11-10T19:40:00.000Z" }
    },
    { "id": "…", "email": "…", "…": "…" }
  ],
  "pagination": { "nextCursor": "eyJpZCI6…", "hasMore": true }
}

رموز الأخطاء الخاصة

مشترك واحد

GET/subscribers/{idOrEmail}
المفتاح المطلوب: قراءة فقط

بالمعرّف (24 حرفًا) أو بعنوان البريد (مُرمَّزًا في الرابط: @ تصبح %40).

الطلب
curl https://api.mujaz.io/api/v1/subscribers/reader%40example.com \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": {
    "id": "6740c1f2a9b8e4d3c2b1a0f9",
    "email": "[email protected]",
    "firstName": "Lina",
    "lastName": "",
    "language": "ar",
    "status": "active",
    "tags": ["vip"],
    "lists": ["6731aa04c2e9d8f7b6a5e4d3"],
    "source": "api",
    "sourceRef": "wordpress-footer",
    "createdAt": "2026-11-18T10:00:00.000Z",
    "updatedAt": "2026-11-18T10:00:00.000Z",
    "unsubscribedAt": null,
    "confirmationSentAt": null,
    "engagement": { "opens": 12, "clicks": 3, "lastOpenedAt": "2026-11-17T08:12:00.000Z", "lastClickedAt": "2026-11-10T19:40:00.000Z" }
  }
}

رموز الأخطاء الخاصة

إضافة مشترك

POST/subscribers
المفتاح المطلوب: قراءة وكتابة

يعمل مثل نموذج الاشتراك في موقعك: تأكيد مزدوج إن كان مفعّلًا في نموذجك (ودائمًا للحسابات الجديدة)، ورسالة الترحيب حين يصبح المشترك فعّالًا. إن كان الشخص موجودًا أصلًا يعود 200 مع created: false وتُضاف القوائم والوسوم فقط.

محتوى الطلب (JSON)

email
stringمطلوب
عنوان البريد.
firstName / lastName
string ≤ 100اختياري
الاسم.
language
ar | enاختياري
لغة المشترك.
tags
string[] ≤ 20اختياري
وسوم تُضاف.
lists
id[] ≤ 20اختياري
قوائم يُضاف إليها. «كل المشتركين» تُضاف دائمًا.
doubleOptIn
booleanاختياري
إن حُذف يُتّبع إعداد نموذجك. true: يبقى pending ونرسل رسالة التأكيد. الحساب الجديد يُفرض عليه التأكيد ويقول الرد doubleOptInForced: true.
sendWelcome
booleanاختياري
false يتخطّى رسالة الترحيب.
sourceRef
stringاختياري
مرجعك الخاص، مثل اسم النموذج.
updateExisting
booleanاختياري
true يستبدل اسم المشترك الموجود ولغته. بدونه تُملأ الفارغة فقط. الحالة لا تتغيّر أبدًا.

من ألغى اشتراكه أو ارتدّ بريده أو أبلغ عن رسالة لا يمكن إعادته من الواجهة (OPTED_OUT)، ولا العناوين المحظورة (SUPPRESSED). العودة قرار القارئ وحده.

رسائل التأكيد التي تسببها الواجهة محدودة بـ 200 في الساعة و1,000 في اليوم. بعدها يُنشأ المشترك pending بلا رسالة، ويقول الرد confirmationWithheld: true.

الطلب
curl -X POST https://api.mujaz.io/api/v1/subscribers \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wp-signup-8812" \
  -d '{
    "email": "[email protected]",
    "firstName": "Lina",
    "language": "ar",
    "tags": ["vip"],
    "sourceRef": "wordpress-footer"
  }'
الرد
{
  "status": "success",
  "data": {
    "created": true,
    "doubleOptInForced": false,
    "confirmationWithheld": false,
    "subscriber": {
      "id": "6740c1f2a9b8e4d3c2b1a0f9",
      "email": "[email protected]",
      "firstName": "Lina",
      "lastName": "",
      "language": "ar",
      "status": "active",
      "tags": ["vip"],
      "lists": ["6731aa04c2e9d8f7b6a5e4d3"],
      "source": "api",
      "sourceRef": "wordpress-footer",
      "createdAt": "2026-11-18T10:00:00.000Z",
      "updatedAt": "2026-11-18T10:00:00.000Z",
      "unsubscribedAt": null,
      "confirmationSentAt": null,
      "engagement": { "opens": 12, "clicks": 3, "lastOpenedAt": "2026-11-17T08:12:00.000Z", "lastClickedAt": "2026-11-10T19:40:00.000Z" }
    }
  }
}

تعديل مشترك

PATCH/subscribers/{id}
المفتاح المطلوب: قراءة وكتابة

حقل واحد على الأقل. لا يمكن تغيير البريد ولا الحالة: تغيير العنوان أو العودة بعد الإلغاء قرار القارئ نفسه.

محتوى الطلب (JSON)

firstName / lastName / language
stringاختياري
تستبدل القيم الحالية.
tags
string[]اختياري
يستبدل كل الوسوم.
addTags / removeTags
string[]اختياري
يضيف وسومًا أو يزيلها.
addLists / removeLists
id[]اختياري
يضيفه إلى قوائم أو يزيله منها.
الطلب
curl -X PATCH https://api.mujaz.io/api/v1/subscribers/6740c1f2a9b8e4d3c2b1a0f9 \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "addTags": ["webinar-2026"] }'
الرد
{
  "status": "success",
  "data": { "id": "6740c1f2a9b8e4d3c2b1a0f9", "tags": ["vip", "webinar-2026"], "…": "…" }
}

رموز الأخطاء الخاصة

إلغاء اشتراك

POST/subscribers/{id}/unsubscribe
المفتاح المطلوب: قراءة وكتابة

يلغي الاشتراك ويحظر العنوان من الإضافة مجددًا، كما في لوحة التحكم. تكرار الطلب آمن. يعمل حتى أثناء مراجعة الحساب: إلغاء الاشتراك لا ينتظر.

محتوى الطلب (JSON)

reason
string ≤ 200اختياري
السبب (اختياري).
الطلب
curl -X POST https://api.mujaz.io/api/v1/subscribers/6740c1f2a9b8e4d3c2b1a0f9/unsubscribe \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Asked by email" }'
الرد
{
  "status": "success",
  "data": { "id": "6740c1f2a9b8e4d3c2b1a0f9", "status": "unsubscribed", "unsubscribedAt": "2026-11-18T11:00:00.000Z", "…": "…" }
}

رموز الأخطاء الخاصة

حذف مشترك

DELETE/subscribers/{id}
المفتاح المطلوب: قراءة وكتابة

لطلبات الخصوصية. يُحذف من كل القوائم ثم يُحذف نهائيًا. من ألغى اشتراكه يبقى محظورًا حتى لا يُضاف مجددًا. أرسل suppress: true لتحظر عنوانًا فعّالًا أيضًا («احذفني ولا تراسلني أبدًا»).

محتوى الطلب (JSON)

suppress
booleanاختياري
يحظر العنوان أيضًا.
الطلب
curl -X DELETE https://api.mujaz.io/api/v1/subscribers/6740c1f2a9b8e4d3c2b1a0f9 \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "suppress": true }'
الرد
{ "status": "success", "data": { "deleted": true, "suppressed": true } }

رموز الأخطاء الخاصة

إضافة جماعية

POST/subscribers/bulk
المفتاح المطلوب: قراءة وكتابةخطة الأعمال

حتى 1,000 شخص في الطلب، و30 طلبًا في الساعة. يعمل مثل الاستيراد في لوحة التحكم بكل فحوصه: يُضاف المشتركون فعّالين، بلا رسالة تأكيد ولا ترحيب. كل صف له نتيجة.

محتوى الطلب (JSON)

subscribers
[{ email, firstName, lastName, language, tags }] ≤ 1000مطلوب
الأشخاص.
lists
id[]اختياري
قوائم يُضاف إليها الجميع.
language
ar | enاختياري
اللغة لمن لا لغة له.
updateExisting
booleanاختياري
يحدّث بيانات الموجودين.

result لكل صف واحد من: created وexisted وupdated وskipped وleftOut (تجاوز حد الخطة) وerror.

الطلب
curl -X POST https://api.mujaz.io/api/v1/subscribers/bulk \
  -H "Authorization: Bearer $MUJAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-2026-11-18" \
  -d '{
    "subscribers": [
      { "email": "[email protected]", "firstName": "Sami" },
      { "email": "b@example" }
    ],
    "lists": ["6731aa04c2e9d8f7b6a5e4d3"]
  }'
الرد
{
  "status": "success",
  "data": {
    "imported": 1, "updated": 0, "alreadyExisted": 0, "skipped": 1, "errors": 0,
    "truncated": false, "leftOut": 0, "limit": null,
    "results": [
      { "row": 1, "email": "[email protected]", "result": "created", "id": "6740c1f2a9b8e4d3c2b1a0fa" },
      { "row": 2, "email": "b@example", "result": "skipped", "code": "EMAIL_INVALID" }
    ]
  }
}

القوائم والوسوم

القوائم

GET/lists
المفتاح المطلوب: قراءة فقط

قوائمك مع عدد أعضائها الآن (فعّال + بانتظار التأكيد). isDefault هي «كل المشتركين».

الطلب
curl https://api.mujaz.io/api/v1/lists \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": [
    { "id": "6731aa04c2e9d8f7b6a5e4d3", "name": "All Subscribers", "description": "", "languageTag": null, "isDefault": true, "subscriberCount": 3100, "createdAt": "2026-03-02T12:00:00.000Z" }
  ]
}

الوسوم

GET/tags
المفتاح المطلوب: قراءة فقط

كل وسم مع عدد من يحمله.

الطلب
curl https://api.mujaz.io/api/v1/tags \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{ "status": "success", "data": [ { "tag": "vip", "count": 120 } ] }

الإحصائيات والأعداد

أرقام حقيقية فقط، محسوبة بالدوال نفسها التي تعرضها لوحة التحكم: لا تقديرات، والنسبة null حين لا يوجد مستلمون (لا 0% مختلقة).

أرقام الحساب

GET/stats
المفتاح المطلوب: قراءة فقط

المشتركون والبريد خلال فترة.

معاملات العنوان (Query)

period
7d | 30d | 90d | 1yاختياري
الفترة (الافتراضي 30d).
الطلب
curl "https://api.mujaz.io/api/v1/stats?period=30d" \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": {
    "period": "30d", "from": "2026-10-19T00:00:00.000Z", "to": "2026-11-18T00:00:00.000Z", "periodClamped": null,
    "subscribers": { "total": 3100, "active": 2950, "pending": 150, "unsubscribed": 210, "bounced": 40, "complained": 2,
                     "newInPeriod": 320, "unsubscribedInPeriod": 18 },
    "emails": { "newslettersSent": 4, "recipients": 11800, "delivered": 11690, "uniqueOpens": 5200, "uniqueClicks": 900,
                "openRate": 44.5, "clickRate": 7.7, "bounces": 60, "complaints": 1 }
  }
}

الأعداد

GET/newsletters
المفتاح المطلوب: قراءة فقط

أعدادك بلا محتواها. publicUrl موجود حين يكون العدد منشورًا وعامًا. رسائل الترحيب لا تظهر.

معاملات العنوان (Query)

status
sent | scheduled | draftاختياري
الافتراضي sent.
limit
1–100اختياري
عدد العناصر في الصفحة (الافتراضي 50).
cursor
stringاختياري
قيمة nextCursor من الصفحة السابقة.
الطلب
curl "https://api.mujaz.io/api/v1/newsletters?status=sent&limit=10" \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": [
    { "id": "6741d0e3b8a7f6e5d4c3b2a1", "title": "…", "subject": "…", "slug": "my-post", "status": "sent",
      "format": "article", "webOnly": false, "sentAt": "2026-11-15T09:00:00.000Z", "scheduledAt": null,
      "publishedAt": "2026-11-15T09:00:00.000Z", "recipients": 2950,
      "publicUrl": "https://www.mujaz.io/@mynewsletter/my-post" }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

عدد واحد

GET/newsletters/{id}
المفتاح المطلوب: قراءة فقط

الكائن نفسه الذي في القائمة.

الطلب
curl https://api.mujaz.io/api/v1/newsletters/6741d0e3b8a7f6e5d4c3b2a1 \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{ "status": "success", "data": { "id": "6741d0e3b8a7f6e5d4c3b2a1", "status": "sent", "…": "…" } }

رموز الأخطاء الخاصة

أرقام عدد

GET/newsletters/{id}/stats
المفتاح المطلوب: قراءة فقط

الارتدادات والشكاوى أشخاص مختلفون لا محاولات. unsubscribesSinceSend لكل الحساب منذ الإرسال: لا شيء يربط إلغاء الاشتراك بعدد بعينه. عدد لم يُرسل يعود بأصفار وsent: false.

الطلب
curl https://api.mujaz.io/api/v1/newsletters/6741d0e3b8a7f6e5d4c3b2a1/stats \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": {
    "recipients": 2950, "delivered": 2921, "opens": 2400, "uniqueOpens": 1300, "clicks": 410, "uniqueClicks": 260,
    "bounces": 12, "complaints": 0, "openRate": 44.5, "clickRate": 8.9,
    "unsubscribesSinceSend": 5, "unsubscribesScope": "workspace"
  }
}

رموز الأخطاء الخاصة

المنشورات

ما تعرضه صفحتك العامة فقط: المنشور والعام، بالترتيب نفسه. أي مفتاح يقرأها، ومفتاح الموقع يقرأها من المتصفح أيضًا.

قائمة المنشورات

GET/posts
المفتاح المطلوب: مفتاح الموقع

الأحدث أولًا. أي عامل تصفية آخر (مثل status) يُرفض: الواجهة لا تعرض إلا ما تعرضه الخلاصة.

معاملات العنوان (Query)

limit
1–50اختياري
الافتراضي 20.
cursor
stringاختياري
قيمة nextCursor من الصفحة السابقة.
format
article | newsletterاختياري
المقالات أو الأعداد فقط.
includeContent
trueاختياري
يضيف contentHtml لكل منشور، وlimit حينها 10 على الأكثر.
الطلب
curl "https://api.mujaz.io/api/v1/posts?limit=5" \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": [
    {
      "id": "6741d0e3b8a7f6e5d4c3b2a1",
      "slug": "my-post",
      "title": "…",
      "subtitle": "…",
      "excerpt": "…",
      "format": "article",
      "language": "ar",
      "publishedAt": "2026-11-15T09:00:00.000Z",
      "updatedAt": "2026-11-15T09:30:00.000Z",
      "url": "https://www.mujaz.io/@mynewsletter/my-post",
      "shortUrl": "https://www.mujaz.io/@mynewsletter/k3x9",
      "coverImage": { "url": "https://img.mujaz.io/…webp", "alt": "…" },
      "readingMinutes": 6,
      "categories": ["…"],
      "author": { "name": "…", "role": "…", "avatar": "https://…" }
    }
  ],
  "pagination": { "nextCursor": "eyJjIjoiMjAyNi0xMS0xNVQwOTowMDow…", "hasMore": true },
  "attribution": {
    "text": "Powered by Mujaz",
    "textAr": "مدعوم بواسطة موجز",
    "url": "https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "subscribeUrl": "https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "line": "Written and sent with Mujaz. Subscribe: https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "lineAr": "كُتبت وأُرسلت عبر موجز. اشترك: https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution"
  }
}

رموز الأخطاء الخاصة

منشور واحد

GET/posts/{idOrSlug}
المفتاح المطلوب: مفتاح الموقع

بالمعرّف أو بالرابط المختصر (slug)؛ الرابط القديم أو الرمز القصير يجد المنشور أيضًا، ويعود الرد بالرابط الحالي. يعود دائمًا مع contentHtml: HTML منقّى (بلا سكربتات ولا أنماط مضمّنة)، ملفوف في dir وlang الصحيحين، وروابطه مطلقة. ما لا يُعرض على صفحتك يعود 404.

المنشور الكبير جدًا (أكثر من 100 KB) أو المصمّم بـ HTML خاص يعود بلا contentHtml: اعرض المقتطف ورابطًا إلى url.

الطلب
curl https://api.mujaz.io/api/v1/posts/my-post \
  -H "Authorization: Bearer $MUJAZ_API_KEY"
الرد
{
  "status": "success",
  "data": {
    "id": "6741d0e3b8a7f6e5d4c3b2a1",
    "slug": "my-post",
    "title": "…",
    "subtitle": "…",
    "excerpt": "…",
    "format": "article",
    "language": "ar",
    "publishedAt": "2026-11-15T09:00:00.000Z",
    "updatedAt": "2026-11-15T09:30:00.000Z",
    "url": "https://www.mujaz.io/@mynewsletter/my-post",
    "shortUrl": "https://www.mujaz.io/@mynewsletter/k3x9",
    "coverImage": { "url": "https://img.mujaz.io/…webp", "alt": "…" },
    "readingMinutes": 6,
    "categories": ["…"],
    "author": { "name": "…", "role": "…", "avatar": "https://…" },
    "contentHtml": "<div dir=\"rtl\" lang=\"ar\">…</div><p dir=\"rtl\" lang=\"ar\">كُتبت وأُرسلت عبر موجز. اشترك: <a href=\"…\">…</a></p>"
  },
  "attribution": {
    "text": "Powered by Mujaz",
    "textAr": "مدعوم بواسطة موجز",
    "url": "https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "subscribeUrl": "https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "line": "Written and sent with Mujaz. Subscribe: https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution",
    "lineAr": "كُتبت وأُرسلت عبر موجز. اشترك: https://www.mujaz.io/@mynewsletter?utm_source=api&utm_medium=referral&utm_campaign=attribution"
  }
}

رموز الأخطاء الخاصة

خطافات الويب (Webhooks)

يرسل موجز إلى خادمك طلبًا موقّعًا عند كل حدث يهمّك: مشترك جديد، تأكيد، إلغاء اشتراك، ارتداد، استيراد، أو عدد أُرسل.

توثيق خطافات الويب

كل رموز الأخطاء

الرمزHTTPالمعنى
KEY_MISSING401أضف مفتاح API في ترويسة Authorization بالشكل: Bearer mjz_live_…
KEY_INVALID401مفتاح API هذا غير صالح. تأكد أنك نسخته كاملًا.
KEY_REVOKED401أُلغي مفتاح API هذا. أنشئ مفتاحًا جديدًا من الإعدادات ← API.
KEY_EXPIRED401انتهت صلاحية مفتاح API هذا. أنشئ مفتاحًا جديدًا من الإعدادات ← API.
KEY_IN_URL400أرسل مفتاح API في ترويسة Authorization، لا في الرابط.
BAD_HEADER400لا يمكن استخدام هذه الترويسة مع واجهة API.
BROWSER_NOT_ALLOWED403يعمل هذا المفتاح من خادمك فقط. في صفحات الويب استخدم الخلاصة (Feed) أو مفتاح موقع.
API_OFF403واجهة API غير متاحة لهذا الحساب بعد.
PLAN_TOO_LOW403واجهة API متاحة من خطة برو. رقِّ خطتك لتستخدمها.
UNPAID_TRIAL403تُتاح واجهة API بعد أول دفعة، ولا تتوفر خلال الفترة التجريبية.
BUSINESS_FEATURE403الإضافة الجماعية وخطافات الويب (Webhooks) متاحة من خطة الأعمال.
SCOPE_REQUIRED403صلاحية المفتاح لا تكفي لهذا الطلب: مفتاح القراءة لا يكتب، ومفتاح الموقع لا يقرأ إلا المنشورات.
WORKSPACE_PAUSED403هذا الحساب قيد المراجعة، لذا تقتصر واجهة API على القراءة حاليًا.
WORKSPACE_SUSPENDED403هذا الحساب موقوف. راسل [email protected].
ACCOUNT_PENDING_DELETION403الحساب مجدول للحذف.
RATE_LIMITED429طلبات كثيرة. انتظر الثواني المذكورة في Retry-After ثم أعد المحاولة.
TOO_MANY_BAD_KEYS429طلبات كثيرة بمفتاح خاطئ من هذا العنوان. أعد المحاولة بعد 10 دقائق.
BODY_TOO_LARGE413الطلب كبير جدًا. الحد الأقصى 1 ميغابايت.
JSON_REQUIRED415أرسل المحتوى بصيغة JSON (Content-Type: application/json).
VALIDATION_FAILED400بعض الحقول غير صالحة. التفاصيل في errors.
NOT_FOUND404غير موجود (ويشمل ذلك معرّفات حساب آخر).
IDEMPOTENCY_IN_PROGRESS409طلب بمفتاح Idempotency-Key نفسه ما زال قيد التنفيذ. أعد المحاولة بعد لحظة.
IDEMPOTENCY_KEY_REUSED422استُخدم مفتاح Idempotency-Key هذا من قبل مع طلب مختلف.
EMAIL_INVALID400هذا ليس عنوان بريد صالحًا.
EMAIL_TYPO400يبدو أن في نطاق البريد خطأً إملائيًا. تحقق منه.
EMAIL_DISPOSABLE400لا يمكن إضافة عناوين البريد المؤقتة.
EMAIL_UNDELIVERABLE400نطاق هذا البريد لا يستقبل الرسائل. تحقق من العنوان.
LIST_NOT_FOUND404إحدى هذه القوائم غير موجودة في هذا الحساب.
OPTED_OUT409ألغى هذا الشخص اشتراكه أو ارتدّ بريده أو أبلغ عن رسالة، فلا يمكن إعادته من الواجهة.
SUPPRESSED409هذا العنوان محظور من الإضافة.
SUBSCRIBER_LIMIT403وصلت إلى حد المشتركين في خطتك.
NEW_ACCOUNT_IMPORT_CAP403يمكن للحسابات الجديدة أن تحمل حتى 1,000 مشترك في أسبوعها الأول. راسل الدعم لتوثيق حسابك ورفع الحد.
API_INTAKE_LOOKS_PURCHASED403تبدو العناوين المضافة عبر واجهة API مشتراة أو مجموعة آليًا. لا يرسل موجز إلا لمن طلب أن يسمع منك. راسل [email protected] لمراجعتها.
IMPORT_LOOKS_PURCHASED403تبدو هذه الدفعة مشتراة أو مجموعة آليًا، فلم تُستورد.
BULK_TOO_LARGE400أرسل 1,000 شخص على الأكثر في الطلب الواحد.
INTERNAL500حدث خطأ من جهتنا. أعد المحاولة؛ مع Idempotency-Key تكون الإعادة آمنة.

سجلّ التغييرات

  • v1

    الإصدار الأول: المفاتيح بثلاث صلاحيات، والمشتركون، والقوائم والوسوم، والإحصائيات، والأعداد، والمنشورات، والإضافة الجماعية، وخطافات الويب الموقّعة، وخلاصات RSS و JSON Feed.

آخر مراجعة: