API للمطورين

واجهة REST API واحدة للقوائم والحملات وبريد المعاملات، وللذكاء الاصطناعي أيضًا.

البدء

تتضمن كل باقة مدفوعة وصولًا كاملًا إلى REST API. أنشئ مفتاحًا في حسابك من الحساب ← مفاتيح API، ثم أرسله مع كل طلب:

curl -H "X-Api-Key: YOUR_KEY" https://mailflow.top/api/index.php/lists

عنوان URL الأساسي: https://mailflow.top/api/index.php · تكون الاستجابات بتنسيق JSON وتتضمن حقل status بقيمة success أو error. لا تتوفر API في الباقة المجانية.

الموارد الأساسية

المنصة متوافقة مع MailWizz، لذا فإن واجهة API الأساسية الكاملة — القوائم، والمشتركون، والشرائح، والحقول المخصصة، والحملات، والتتبع، والقوالب، وبريد المعاملات، والارتدادات، وإلغاءات الاشتراك — موثّقة بشكل تفاعلي (OpenAPI)، إلى جانب جميع نقاط نهاية MailFlow الواردة في هذه الصفحة، على العنوان التالي:

← مرجع API التفاعلي (OpenAPI)

تعمل حِزم SDK الحالية الخاصة بـ MailWizz (مثل PHP SDK الرسمية) مباشرةً دون أي إعداد؛ ما عليك سوى توجيهها إلى عنوان URL الأساسي أعلاه.

نقاط نهاية الذكاء الاصطناعي

ميزات الذكاء الاصطناعي جزء أصيل من API: المفتاح نفسه، والمصادقة نفسها، وحدود الباقة واحتساب الأرصدة نفسها كما في تطبيق الويب.

GET /ai/credits

عدّاد أرصدة الذكاء الاصطناعي للشهر الحالي. تُحتسب الأرصدة لكل شهر فوترة، ولا تُرحَّل الأرصدة غير المستخدمة.

{"status":"success","data":{"unlimited":false,"limit":750,"used":112,"remaining":638}}

GET /ai/replies

تصنيفات الردود الذكية لحملاتك: زوّد نظام CRM لديك بمن هو مهتم، ومن طرح سؤالًا، ومن اشتكى. عوامل التصفية: category (interested، question، complaint، unsubscribe_request، auto_reply، out_of_office، bounce، other)، campaign_uid، since (YYYY-MM-DD)، page، per_page (50 كحد أقصى).

curl -H "X-Api-Key: YOUR_KEY" \
  "https://mailflow.top/api/index.php/ai/replies?category=interested&since=2026-08-01"

{"status":"success","data":{"count":42,"current_page":1,"per_page":20,"total_pages":3,
  "records":[{"from_email":"[email protected]","subject":"RE: your offer",
    "category":"interested","confidence":98,"engine":"embeddings",
    "summary":"...","suggested_reply":"...","date_added":"2026-08-24 18:21:19",
    "campaign_uid":"py794hjqk8a8d"}]}}

GET /ai/tiers

مستويات التفاعل المحددة بالذكاء الاصطناعي (vip، engaged، passive، at_risk، dormant) لكل قائمة، وهو التقييم نفسه الذي يشغّل الطيار الآلي واستعادة المشتركين.

{"status":"success","data":{"records":[
  {"list_uid":"qk661oq7nl8c1","name":"Main list","tiers":{"engaged":1200,"passive":3400,"dormant":900}}]}}

POST /ai/subject-lines

توليد أسطر الموضوع بأي لغة. نص الطلب: topic (إلزامي)، count (1–5، الافتراضي 3)، language (اختياري). يستهلك أرصدة الذكاء الاصطناعي مثل محرر الويب.

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"topic":"Summer sale for B2B customers","count":3,"language":"Greek"}' \
  https://mailflow.top/api/index.php/ai/subject-lines

{"status":"success","data":{"subjects":["...","...","..."],"credits_remaining":636}}

GET /ai/flows · POST /ai/flows/author · POST /ai/flows/<uid>/enroll · POST /ai/flows/<uid>/status

منشئ مسارات العمل بالذكاء الاصطناعي عبر API: اعرض مسارات العمل لديك مع عدّادات مباشرة؛ واجعل الذكاء الاصطناعي يؤلّف مسار عمل كاملًا انطلاقًا من هدف مكتوب بلغة بسيطة ({"goal":"...","list_uid":"..."} — يُعيد مسودة تفعّلها باستخدام {"status":"active"})؛ وأضف مشتركًا إلى مسار عمل ({"email":"..."}).

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"When someone replies interested, notify me, wait 2 days, then send a case study"}' \
  https://mailflow.top/api/index.php/ai/flows/author

أنشئ تطبيقك الخاص على MailFlow

كل ما تفعله في تطبيق الويب يمكن تنفيذه عبر API، لذا يمكنك تشغيل MailFlow من برامجك الخاصة. إليك سير عمل نموذجيًا:

  1. أنشئ قائمة وأضِف جهات الاتصال: POST /lists، POST /lists/<list_uid>/subscribers/bulk.
  2. اعثر على جهات اتصال جديدة باستخدام DataStack: POST /datastack/import.
  3. أنشئ حملة بنفسك (POST /campaigns) أو دَع الذكاء الاصطناعي يكتبها: POST /ai/campaigns.
  4. راجِع مسودة الذكاء الاصطناعي وجدوِل إرسالها: GET /ai/campaigns/<run_id>، POST /ai/campaigns/<run_id>/approve.
  5. اطّلِع على النتائج: GET /analytics/campaigns، GET /campaigns/<campaign_uid>/clicks.

تعمل المهام الطويلة (الكتابة بالذكاء الاصطناعي، وقراءة المواقع، وعمليات الاستيراد من DataStack) في الخلفية: يستجيب الطلب بـ 202 مع job_id، ويُعلِمك GET /ai/jobs/<job_id> عند اكتمال المهمة.

التحليلات

الأرقام نفسها الظاهرة في لوحة التحكم وتقارير الحملات. التواريخ بتوقيت UTC؛ والقيمة الافتراضية لـ from وto (YYYY-MM-DD) هي آخر 30 يومًا. تُحدَّث إجماليات الحساب كل بضع دقائق.

  • GET /analytics/overview — القوائم والمشتركون والحملات ونتائج الإرسال خلال فترة محددة: المُرسَل، والمُسلَّم، ومرات الفتح، والنقرات، والارتدادات، والشكاوى، وإلغاءات الاشتراك، ومعدلاتها.
  • GET /analytics/timeline — النتائج نفسها لكل يوم (أو لكل ساعة باستخدام interval=hour)، إضافةً إلى المشتركين الجدد.
  • GET /analytics/campaigns — صف واحد لكل حملة مع نتائجها؛ يمكنك التصفية باستخدام status.
  • GET /campaigns/<campaign_uid>/opens و/clicks — مَن فتح الرسالة أو نقر عليها، ومتى، ومن أين، وعلى أي جهاز (unique=1 لعرض الأحداث الأولى فقط).
  • GET /campaigns/<campaign_uid>/links، /locations، /devices، /timeline، /abuse-reports — النقرات لكل رابط، والنتائج حسب الدولة والمدينة، وحسب نوع الجهاز، وحسب الساعة، وبلاغات إساءة الاستخدام.
  • GET /campaigns/<campaign_uid>/stats، /bounces، /unsubscribes، /complaints، /delivery-logs — تقارير الحملة الأساسية.
  • GET /lists/<list_uid>/stats — المشتركون حسب الحالة والمصدر، والنمو اليومي، والحملات المُرسَلة إلى القائمة.
curl -H "X-Api-Key: YOUR_KEY" \
  "https://mailflow.top/api/index.php/analytics/overview?from=2026-09-01&to=2026-09-30"

{"status":"success","data":{"period":{"from":"2026-09-01","to":"2026-09-30","timezone":"UTC"},
  "lists":9,"subscribers":{"total":52040,"confirmed":50102,"unsubscribed":311},
  "campaigns":{"total":24,"sent":20,"draft":4},
  "activity":{"sent":48210,"delivered":47650,"unique_opens":14230,"unique_clicks":2210,
    "bounces":402,"complaints":3,"unsubscribes":95,"open_rate":29.86,"click_rate":4.64}}}

الحساب وإعداد الإرسال

  • GET /account · PUT /account — ملفك التعريفي وباقتك وحصة الإرسال والحدود الأخرى؛ مع إمكانية تحديث اسمك أو رقم هاتفك أو منطقتك الزمنية.
  • GET|POST /campaign-groups · GET|PUT|DELETE /campaign-groups/<group_uid> — مجموعات الحملات.
  • GET|POST /suppression-lists · GET|PUT|DELETE /suppression-lists/<list_uid> · GET|POST|DELETE /suppression-lists/<list_uid>/emails — قوائم الاستبعاد (حتى 10,000 عنوان بريد إلكتروني في كل طلب).
  • GET|POST /blacklist · DELETE /blacklist/<email_uid> · GET /blacklist/check?email= — قائمتك السوداء، والتحقق مما إذا كان عنوان ما محظورًا في أي مكان.
  • GET|POST /sending-domains · GET|DELETE /sending-domains/<id> · POST /sending-domains/<id>/verify — نطاقات الإرسال مع سجلات DKIM وSPF وDMARC المطلوب نشرها.
  • GET|POST /tracking-domains · GET|DELETE /tracking-domains/<id> · POST /tracking-domains/<id>/verify — نطاقات تتبع الروابط الخاصة بك.
  • GET /delivery-servers · GET /countries — الخوادم التي يمكنك الإرسال عبرها، والدول مع مناطقها.

حملات الذكاء الاصطناعي

دَع الذكاء الاصطناعي يكتب الحملات نيابةً عنك، مع مراجعتك أو بدونها. يستخدم الذكاء الاصطناعي الملف التعريفي لنشاطك التجاري، ويختار الجمهور ووقت الإرسال، ويفحص الرسالة مقابل فلاتر البريد العشوائي، ويكتبها بلغة كل مشترك.

  • POST /ai/campaigns — أخبر الذكاء الاصطناعي بما تريد إرساله: goal (إلزامي)، list_uid (قائمة، auto أو prospects)، audience، business، template_uid، follow_up، auto_send. أما طريقة الإرسال فتكتبها في settings_brief بكلمات بسيطة (تاريخ، التوقيت المحلي لكل قارئ، نافذة إرسال يومية، تكرار أسبوعي، حدّ أقصى، اختبار A/B لسطر الموضوع، نطاق التتبع الخاص بك، نقل من يفتحون إلى قائمة، وسمهم، webhook، وسوم إضافية) أو كإعدادات settings صريحة.
  • POST /ai/campaigns/prepare — يقرر الذكاء الاصطناعي ما يُرسَل تاليًا (حتى 3 في اليوم)؛ مع hint اختياريًا.
  • GET /ai/campaigns · GET /ai/campaigns/<run_id> — حملات الذكاء الاصطناعي مع سطور الموضوع والجمهور والوقت المقترح وفحص البريد المزعج والإعدادات التي اختارها الذكاء الاصطناعي مع أسبابه (html=1 يضيف الرسالة).
  • GET|PUT /ai/campaigns/<run_id>/settings — كل إعدادات حملة MailWizz للمسودة مع قيمها المسموح بها: الخيارات (tracking_domain_id، max_send_count، max_send_count_random، embed_images، plain_text_email، preheader، email_stats…)، التتبع (open_tracking، url_tracking، smart_open_tracking، smart_click_tracking، استبعاد الزواحف)، اختبار A/B (ab_enabled، ab_subjects، معايير الفائز)، الإجراءات عند الفتح/الإرسال (open_actions، sent_actions، open_field_actions، sent_field_actions، open_webhooks، extra_tags، مرشّح فتح/لم يفتح، قوائم الاستبعاد) وخطوة التأكيد (send_at، cronjob المتكرر، send_between_start/send_between_interval، timewarp_enabled/timewarp_hour/timewarp_minute). يغيّر PUT أيًّا منها بعد التحقق وفق قواعد MailWizz نفسها. أما خوادم التسليم فيختارها MailWizz نفسه دائمًا.
  • POST /ai/campaigns/<run_id>/approve — جدولتها: when = proposed أو now أو custom مع send_at؛ اختياري max_send. تنطبق الفحوصات نفسها الموجودة في خطوة تأكيد الحملة (القالب، نطاق إرسال موثّق عندما تشترطه خطتك، حدّ الحملات النشطة، الكلمات المحظورة).
  • POST /ai/campaigns/<run_id>/revise (مع feedback) · POST /ai/campaigns/<run_id>/discard — اطلب تعديلات، أو تخلَّص من المسودة.
  • GET /ai/jobs/<job_id> — حالة مهمة الخلفية وحملات الذكاء الاصطناعي التي أنشأتها.
  • GET|PUT /ai/hands-off — وضع التشغيل الآلي الكامل: يخطط الذكاء الاصطناعي ويكتب ويُرسِل دون انتظارك ({"enabled":true}).
curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"Invite our customers to the autumn webinar","list_uid":"auto"}' \
  https://mailflow.top/api/index.php/ai/campaigns

{"status":"success","data":{"job_id":512,"job_status":"queued","check":"/ai/jobs/512"}}

curl -H "X-Api-Key: YOUR_KEY" https://mailflow.top/api/index.php/ai/jobs/512

{"status":"success","data":{"job_id":512,"type":"autopilot","status":"done","ai_campaigns":[331],"sent":false}}

curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"Invite our customers to the autumn webinar",
       "settings_brief":"Send Tuesday at 9 in the morning at each reader\u2019s local time, only 5000 people, A/B test the subject",
       "settings":{"tracking_domain_id":"7"}}' \
  https://mailflow.top/api/index.php/ai/campaigns

curl -X PUT -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"settings":{"smart_open_tracking":"yes","send_between_start":"09:00:00","send_between_interval":"8"}}' \
  https://mailflow.top/api/index.php/ai/campaigns/331/settings

الملفات التعريفية للأنشطة التجارية

يكتب الذكاء الاصطناعي باسم نشاطك التجاري. خصِّص ملفًا تعريفيًا واحدًا لكل موقع ويب:

  • GET|POST /ai/businesses — أنشطتك التجارية؛ أضِف نشاطًا جديدًا باستخدام website.
  • GET|PUT|DELETE /ai/businesses/<domain> — الملف التعريفي، والمرسل (from_name، from_email، reply_to)، وبيانات الشركة (company_*).
  • POST /ai/businesses/<domain>/read-website · PUT /ai/businesses/<domain>/main — دَع الذكاء الاصطناعي يقرأ الموقع ويملأ الملف التعريفي؛ واجعله نشاطك التجاري الرئيسي.

العملاء المحتملون من DataStack

اعثر على عناوين بريد إلكتروني جديدة للأعمال وأخرى شخصية، واستوردها مباشرةً إلى قوائمك. يُحتسَب الاستيراد ضمن باقتك، أما عمليات العدّ فمجانية.

  • GET /datastack/credits — عدد العناوين التي لا تزال باقتك تسمح لك باستيرادها هذا الشهر.
  • GET /datastack/count — عدد العناوين المتاحة حسب country وniche (فئات الأعمال) وkeyword وrole (العناوين الشخصية). مجانًا.
  • POST /datastack/import — استيراد عناوين من نوع business و/أو personal إلى list_uid (مهمة في الخلفية). تُفحَص العناوين الجديدة قبل أن تُرسَل إليها أي حملة.
curl -X POST -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"list_uid":"cr5899rtqe668","business":2000,"country":"Greece","niche":"dentist, hotel"}' \
  https://mailflow.top/api/index.php/datastack/import

{"status":"success","data":{"job_id":513,"job_status":"queued","check":"/ai/jobs/513","list_uid":"cr5899rtqe668"}}

تذاكر الدعم

  • GET|POST /support-tickets — تذاكرك؛ افتح تذكرة جديدة باستخدام subject وmessage وcategory وpriority.
  • GET /support-tickets/<ticket_uid> · POST /support-tickets/<ticket_uid>/replies · PUT /support-tickets/<ticket_uid>/close — قراءة المحادثة، والرد، والإغلاق.

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

يمكن قصر المفتاح على نقاط نهاية معيّنة. من الحساب ← مفاتيح API، عدِّل المفتاح وفعِّل الصلاحيات وحدِّد ما يُسمح له باستخدامه. تظهر نقاط النهاية الواردة في هذه الصفحة هناك بالبادئة MailFlow.

الأخطاء والحدود

  • 400 — X-Api-Key مفقود أو غير صالح، أو ليس لدى المفتاح صلاحية لاستخدام نقطة النهاية هذه
  • 402 — أرصدة DataStack غير كافية هذا الشهر
  • 403 — الميزة غير مشمولة في باقتك، أو تم بلوغ أحد حدود الباقة
  • 404 — القائمة أو الحملة أو العنصر الآخر غير موجود في حسابك
  • 409 — العنصر ليس في الحالة المناسبة (على سبيل المثال، لا يمكن اعتماد سوى المسودات)
  • 422 — معلمات مفقودة أو غير صالحة
  • 429 — تم بلوغ حد أرصدة الذكاء الاصطناعي أو الحصة الشهرية للذكاء الاصطناعي؛ يُعاد ضبطه في تاريخ الفوترة التالي

يُحَدّ من دفعات الطلبات المتلاحقة لكل مفتاح، لذا طبّق التراجع الأُسّي عند تلقي 429. هل لديك أسئلة؟ تواصل معنا أو افتح تذكرة دعم.