Skip to main content
دع Sentra يكتب كود التكامل نيابةً عنك.
استخدم مساعد الذكاء الاصطناعي الخاص بنا في VS Code أو Cursor أو Windsurf لإنشاء كود SDK/API ومعالجات webhook وغير ذلك، وذلك بمجرد وصف ما تريده.
جرّب Sentra: تكامل مدعوم بالذكاء الاصطناعي →
في هذا البرنامج التعليمي، ستنشئ MailKit، وهي منصة للبريد الإلكتروني للمعاملات يدفع فيها العملاء مقدمًا مقابل مجموعة من أرصدة البريد الإلكتروني. تمنح الخطة حصة شهرية من رسائل البريد الإلكتروني؛ وعندما ينخفض رصيد العملاء، يمكنهم شراء حزمة شحن بدلًا من انتظار الدورة التالية. يُخصم رصيد واحد تلقائيًا عند كل إرسال.
يستخدم هذا البرنامج التعليمي Resend كمزود للبريد الإلكتروني. تكفي خطته المجانية (3,000 رسالة شهريًا) لإنشاء التدفق بالكامل واختباره دون حساب مدفوع. يعمل هذا النمط مع أي مزود؛ استبدل resend.emails.send بـ SendGrid أو Postmark أو SES أو مرحّل SMTP الخاص بك.
بنهاية هذا البرنامج التعليمي، ستعرف كيفية:
  • إنشاء استحقاق أرصدة مخصص (لرسائل البريد الإلكتروني) في لوحة التحكم
  • إرفاق الأرصدة بخطة اشتراك وبمنتج شحن لمرة واحدة
  • إرسال رسائل بريد إلكتروني حقيقية عبر Resend وخصم رصيد واحد لكل إرسال من خلال إدخال في دفتر الأستاذ
  • الاستعلام عن رصيد الأرصدة الحالي من الواجهة الأمامية
  • التحقق من webhooks الخاصة بـ Dodo بشكل صحيح ومعالجة credit.balance_low لتنبيه العملاء قبل وصول رصيدهم إلى الصفر

ما سنبنيه

إليك نموذج التسعير الخاص بـ MailKit: الوحدة هي رسالة بريد إلكتروني واحدة = رصيد واحد. لا يحتاج العملاء إلى التفكير في الرموز أو الدفعات أو الوحدات الموزونة. سيرون فقط: “لديك 4,231 رسالة بريد إلكتروني متبقية هذا الشهر.”
قبل البدء، تأكد من توفر ما يلي لديك:
  • حساب Dodo Payments (يكفي وضع الاختبار)
  • حساب ومفتاح API مجانيان لدى Resend
  • Node.js 18+ وإلمام أساسي بـ TypeScript

الخطوة 1: إنشاء استحقاق أرصدة البريد الإلكتروني

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

The Credits tab under Products lists all your credit entitlements.

1

Open the Credits section

  1. سجّل الدخول إلى لوحة تحكم Dodo Payments
  2. انقر على Products في الشريط الجانبي الأيسر
  3. حدّد علامة التبويب Credits
  4. انقر على Create Credit
2

Configure the credit unit

أدخل تفاصيل الرصيد:اسم الرصيد: Email Creditsنوع الرصيد: حدّد Custom Unitاسم الوحدة: emailالدقة: 0 (رسالة البريد الإلكتروني دائمًا وحدة كاملة؛ لا يمكنك إرسال نصف رسالة)انتهاء صلاحية الرصيد: 30 days (تُعاد حصة كل دورة إلى قيمتها الأصلية)
لا يمكن تغيير الدقة بعد الإنشاء. بالنسبة إلى الوحدات المنفصلة مثل رسائل البريد الإلكتروني أو الرسائل أو الجلسات، فإن 0 صحيح.
3

Leave the other defaults as-is

لن نمكّن الترحيل أو التجاوز في هذا الدليل؛ فالهدف هو أبسط تدفق ممكن لـ CBB. يمكنك إعادة النظر في هذه الإعدادات لاحقًا عند إرفاق الرصيد.
4

Save and copy the credit ID

انقر على Create Credit. افتح الرصيد وانسخ معرّفه. ستحتاج إليه للاستعلام عن الأرصدة من الواجهة الخلفية. سيبدو بهذا الشكل: cent_xxxxxxxxxxxx.
أصبح استحقاق Email Credits جاهزًا. التالي: المنتجات التي تمنح الأرصدة للعملاء.

الخطوة 2: إنشاء الخطة وحزمة الشحن

ستنشىء منتجين: خطة Subscription متكررة، ومنتج شحن Single Payment. تمنح الخطة 5,000 رسالة بريد إلكتروني في كل دورة؛ بينما تضيف حزمة الشحن 5,000 رسالة أخرى عند الطلب. ويرتبط كلاهما باستحقاق Email Credits نفسه.
يخصم هذا الدليل الأرصدة من خلال إدخالات مباشرة في دفتر الأستاذ بدلًا من العدادات القائمة على الاستخدام. تكون إدخالات دفتر الأستاذ فورية (يُحدّث الرصيد خلال أجزاء من الثانية)، ولا تحتاج إلى إعداد إضافي، وهي مناسبة عندما يعادل إجراء مستخدم واحد رصيدًا واحدًا بالضبط. إذا كنت تفضّل الخصم التلقائي من أحداث الاستخدام المُدخلة (وهو مفيد للوحدات الموزونة مثل “الرموز” أو “الميجابايت المُعالجة”)، فراجع الفوترة القائمة على الأرصدة → فوترة الاستخدام باستخدام الأرصدة لمعرفة النمط القائم على العداد.

خطة MailKit ($19/شهريًا، 5,000 رسالة بريد إلكتروني)

1

Create the subscription

  1. انتقل إلى Products → Create Product
  2. أدخل تفاصيل المنتج:
اسم المنتج: MailKit Planالوصف: 5,000 transactional emails per month.
  1. حدّد Subscription نوعًا للمنتج
  2. عيّن السعر المتكرر:
السعر المتكرر: 19.00دورة الفوترة: Monthlyالعملة: USD
2

Attach the email credit entitlement

مرّر إلى Entitlements → Credits → Attach واضبط ما يلي:استحقاق الرصيد: Email Creditsالأرصدة المُصدرة لكل دورة فوترة: 5000حد انخفاض الرصيد: 20 (نسبة مئوية؛ يُطلق credit.balance_low عندما ينخفض الرصيد إلى أقل من 20% من حصة الدورة، أي 1,000 رسالة بريد إلكتروني)استيراد إعدادات الرصيد الافتراضية: مفعّل (يستخدم مدة الصلاحية البالغة 30 يومًا من الخطوة 1)انقر على Add to Product، ثم Save المنتج. انسخ معرّف المنتج (pdt_xxxxxxxxxxxx).
الخطة: $19/شهريًا ← 5,000 رسالة بريد إلكتروني تتجدد في كل دورة.

حزمة الشحن ($9 لمرة واحدة، 5,000 رسالة بريد إلكتروني)

1

Create a one-time product

  1. انتقل إلى Products → Create Product
  2. أدخل تفاصيل المنتج:
اسم المنتج: Email Top-Up Packالوصف: Add 5,000 emails to your MailKit balance instantly.
  1. حدّد Single Payment نوعًا للمنتج
  2. عيّن السعر:
السعر: 9.00العملة: USD
2

Attach the credit grant

في Entitlements → Credits → Attach:
  • استحقاق الرصيد: Email Credits
  • الأرصدة المُصدرة: 5000
تمنح المنتجات لمرة واحدة أرصدةً ذات مدة صلاحية خاصة بها (30 يومًا من تاريخ الشراء، وفقًا للخطوة 1). تتراكم حزم الشحن فوق أرصدة الاشتراك؛ ولا تستبدلها.
احفظ معرّف المنتج وانسخه.
حزمة الشحن: $9 ← +5,000 رسالة بريد إلكتروني، متاحة فورًا.

الخطوة 3: إعداد الواجهة الخلفية

أنشئ الآن خادم Express الذي يتعامل مع الدفع، والإرسال، والاستعلامات عن الرصيد، وwebhooks.
1

Initialize the project

أضف برنامج تطوير إلى package.json:
يشغّل tsx TypeScript مباشرةً دون خطوة إنشاء أو tsconfig.json، ما يجعله مثاليًا لبرنامج تعليمي. في بيئة الإنتاج، أضف tsconfig.json وبرنامج build.
2

Configure environment variables

أنشئ .env:
.env
ستملأ DODO_WEBHOOK_KEY في الخطوة 4 بعد إنشاء نقطة النهاية. يأتي مفتاح Resend API من resend.com/api-keys.
أضف .env إلى .gitignore فورًا. لا تُودع مفاتيح API مطلقًا في المستودع.
3

Build the server

أنشئ server.ts في جذر المشروع:
يجب أن يكون نص webhook خامًا. تقوم express.json() بتحليل النص وإعادة تسلسله، ما يؤدي إلى فشل التحقق من التوقيع. عرّف /webhooks/dodo باستخدام express.raw() قبل سطر app.use(express.json()).
أصبحت الواجهة الخلفية جاهزة: تم إعداد الاشتراك، والشحن، والرصيد، والإرسال، ومعالج webhook.
4

Add a demo UI

أنشئ public/index.html:

الخطوة 4: إعداد نقطة نهاية webhook

يتيح لك حدث credit.balance_low تنبيه العملاء قبل نفاد أرصدتهم. وبدونه، لن يلاحظوا المشكلة للمرة الأولى إلا عند فشل إرسال رسالة بريد إلكتروني.
1

Expose your local server

تحتاج webhooks إلى عنوان URL عامًا. استخدم ngrok (أو أي نفق) أثناء التطوير:
انسخ عنوان URL لإعادة التوجيه عبر HTTPS (مثل https://1234abcd.ngrok-free.app).
2

Register the endpoint in Dodo

  1. انتقل إلى Developers → Webhooks → Add Endpoint
  2. URL: https://1234abcd.ngrok-free.app/webhooks/dodo
  3. الأحداث: اشترك في credit.added وcredit.balance_low وcredit.rolled_over
  4. احفظ مفتاح signing key، ثم انسخه إلى .env باسم DODO_WEBHOOK_KEY
  5. أعد تشغيل الخادم

الخطوة 5: اختبار التدفق بالكامل

1

Start the server

يجب أن ترى MailKit running on http://localhost:3000. افتحه في متصفحك.
2

Subscribe a test customer

  1. في القسم 1، أدخل بريدًا إلكترونيًا تجريبيًا واسمًا، ثم انقر على Get checkout link
  2. افتح الرابط وأكمل الدفع باستخدام بطاقة اختبار
  3. بعد الدفع، اعثر على customer_id في لوحة التحكم ضمن Customers
يجب أن يمتلك العميل الآن 5,000 رسالة بريد إلكتروني في رصيده. تحقّق من Customers → [Customer] → Credits.
3

Send a real email

  1. الصق customer_id في القسم 3
  2. اترك to مضبوطًا على delivered@resend.dev (صندوق الوارد التجريبي في Resend الذي يقبل كل شيء)
  3. انقر على Send
ستتلقى معرّف رسالة من Resend. حدّث الرصيد في القسم 2، وسينخفض العدد فورًا إلى 4,999. ينعكس كل خصم من دفتر الأستاذ في الرصيد المباشر لحظة كتابته.
4

Trigger the low-balance webhook

الحد هو 20% (1,000 من حصة 5,000 رسالة). لتفعيله دون إرسال 4,000 رسالة حقيقية، خصم الرصيد يدويًا من لوحة التحكم:
  1. انتقل إلى Customers → [Customer] → Credits → Email Credits
  2. انقر على Adjust Balance وخصم 4000
  3. أرسل رسالة بريد إلكتروني أخرى من خلال العرض التجريبي
يجب أن يسجّل خادمك خلال بضع ثوانٍ:
استلم خادمك webhook وتحقق منه. في بيئة الإنتاج، يمكنك هنا إرسال بريد إلكتروني إلى العميل أو عرض شريط تنبيه داخل التطبيق.
5

Buy a top-up pack

  1. الصق customer_id في القسم 4
  2. انقر على Buy 5,000 emails وأكمل الدفع التجريبي
  3. حدّث الرصيد، وستجده قد زاد بمقدار 5,000
يُطلق حدث credit.added مع grant_source: one_time. تتراكم حزمة الشحن فوق أرصدة الاشتراك؛ ويُستهلك كلا الرصيدين وفق FIFO (أقدم منحة غير منتهية الصلاحية أولًا).
6

Test the hard stop

خصم الرصيد يدويًا حتى يصل إلى الصفر، ثم حاول إرسال رسالة بريد إلكتروني أخرى. ستحصل على:
يمثل الخطأ 402 ذلك التطبيق لفرض القيود على مستوى تطبيقك. تُعد واجهة API الخاصة برصيد Dodo مصدر الحقيقة؛ لا تخزّن الرصيد مؤقتًا على العميل مطلقًا.

استكشاف الأخطاء وإصلاحها

يُحسب التوقيع على نص HTTP الخام. تقوم express.json() بتحليل الحمولة وإعادة تسلسلها، ما يؤدي إلى كسر HMAC. تأكد من تسجيل /webhooks/dodo باستخدام express.raw({ type: 'application/json' }) فوق سطر app.use(express.json())، وأن DODO_WEBHOOK_KEY يطابق مفتاح التوقيع الظاهر في صفحة تفاصيل نقطة النهاية.
تحقق من ثلاثة أمور، بهذا الترتيب:
  1. أن العميل أكمل الدفع (تُصدر الأرصدة عند نجاح الدفع، وليس عند إنشاء الجلسة)
  2. أن CREDIT_ENTITLEMENT_ID في .env يطابق الرصيد المرفق بالمنتج (تؤدي المعرّفات غير المتطابقة بصمت إلى الكتابة في الرصيد الخطأ)
  3. أن customer_id الذي تمرره جاء من Dodo (جدول customers في لوحة التحكم)، وليس من قاعدة بياناتك الخاصة
لا يرسل المرسل التجريبي onboarding@resend.dev إلا إلى البريد الإلكتروني الموجود في حسابك لدى Resend أو إلى delivered@resend.dev. للإرسال إلى أي شخص آخر، تحقق من نطاق واستخدم عنوان from عليه.

ما بنيته

One reusable credit unit

تم تعريف Email Credits مرة واحدة وإرفاقه بكل من خطة الاشتراك وحزمة الشحن.

Subscription with prepaid allowance

تمنح الخطة $19/شهريًا 5,000 رسالة بريد إلكتروني في كل دورة. يعرف العملاء ما يدفعون مقابله، وتعرف أنت التكلفة القصوى المتوقعة.

Top-up pack

منتج لمرة واحدة يمنح 5,000 رسالة بريد إلكتروني. يتراكم فوق أرصدة الاشتراك دون الحاجة إلى تغيير الخطة.

Instant ledger debits

استدعاء واحد لـ createLedgerEntry بعد كل إرسال. بلا عداد، ولا تأخر في التجميع، وهو idempotent عند إعادة المحاولة باستخدام معرّف رسالة Resend.

Credit-Based Billing Reference

اقرأ وثائق CBB الكاملة للتعرّف على الترحيل، وأنماط التجاوز، وإدارة دفتر الأستاذ، وواجهة API الكاملة.
هل تحتاج إلى مساعدة؟
آخر تعديل في ٣١ يوليو ٢٠٢٦