DEV Community

Cover image for كيفية استخدام واجهات برمجة تطبيقات Brevo للتسويق عبر الرسائل النصية القصيرة؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام واجهات برمجة تطبيقات Brevo للتسويق عبر الرسائل النصية القصيرة؟

#api #marketing #tutorial #webdev

ملخص

تتيح واجهات برمجة تطبيقات Brevo إرسال رسائل بريد إلكتروني تسويقية ومعاملات ورسائل SMS برمجيًا. تعتمد المصادقة على مفتاح API، ويتم توجيه الطلبات إلى api.brevo.com. يمكنك استخدام خطافات الويب لتتبع التسليم والمشاركة. لاختبار التكامل، استخدم Apidog للتحقق من صحة الحمولات، واختبار معالجات خطافات الويب، وضمان التعامل الصحيح مع رسائل الارتداد وإلغاء الاشتراك.

جرّب Apidog اليوم

مقدمة

تعالج Brevo (سابقًا Sendinblue) ملايين الرسائل يوميًا لأكثر من 500,000 شركة. تُستخدم في الحملات التسويقية، البريد الإلكتروني للمعاملات، تسويق الرسائل القصيرة، وأتمتة سير العمل.

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

أهم حالات الاستخدام:

  • الحملات التسويقية: إرسال رسائل جماعية لقوائم الاتصال.
  • رسائل البريد الإلكتروني للمعاملات: إعادة تعيين كلمة المرور، تأكيد الطلب، إشعارات المستخدم.
  • رسائل SMS: رموز تحقق، تنبيهات، رسائل تسويقية.

💡 نصيحة: إذا كنت تدمج البريد الإلكتروني في تطبيقك، استخدم Apidog لاختبار القوالب، التحقق من حمولات الويب هوك، ومحاكاة استجابات Brevo أثناء التطوير. هذا يسمح باختبار الأخطاء دون إرسال رسائل حقيقية.

المصادقة والإعداد

الحصول على مفتاح API

  1. سجّل الدخول إلى Brevo
  2. اذهب إلى SMTP & API ← API Keys
  3. أنشئ مفتاح جديد وخصص الصلاحيات المطلوبة
  4. خزّن المفتاح بأمان

ضع مفتاح API في ترويسة api-key:

curl -X GET "https://api.brevo.com/v3/account" \
  -H "accept: application/json" \
  -H "api-key: your-api-key-here"
Enter fullscreen mode Exit fullscreen mode

عنوان URL الأساسي

كل الطلبات تُرسل إلى:

https://api.brevo.com/v3/
Enter fullscreen mode Exit fullscreen mode

حدود المعدل (Rate Limits)

  • مجاني: 300 طلب/دقيقة
  • المبتدئ: 600 طلب/دقيقة
  • الأعمال: 1200 طلب/دقيقة

تتبّع الاستهلاك عبر ترويسة X-RateLimit-Remaining.

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

رسائل البريد الإلكتروني للمعاملات تُرسل كرد فعل لإجراء المستخدم (إعادة تعيين كلمة المرور، تأكيد الطلب، إلخ).

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

curl -X POST "https://api.brevo.com/v3/smtp/email" \
  -H "accept: application/json" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "sender": {
      "name": "Your App",
      "email": "noreply@yourapp.com"
    },
    "to": [
      {
        "email": "user@example.com",
        "name": "John Doe"
      }
    ],
    "subject": "Welcome to Our Platform",
    "htmlContent": "<html><body><h1>Welcome!</h1><p>Thanks for signing up.</p></body></html>",
    "textContent": "Welcome! Thanks for signing up."
  }'
Enter fullscreen mode Exit fullscreen mode

استجابة متوقعة:

{
  "messageId": "<20260324123456.123456@relay.brevo.com>"
}
Enter fullscreen mode Exit fullscreen mode

استخدام القوالب

  1. أنشئ قالب في محرر Brevo.
  2. أرسل البريد باستخدام معرّف القالب: 
curl -X POST "https://api.brevo.com/v3/smtp/email" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "templateId": 15,
    "to": [
      {
        "email": "user@example.com",
        "name": "John Doe"
      }
    ],
    "params": {
      "name": "John",
      "order_number": "ORD-12345",
      "tracking_url": "https://tracking.example.com/ORD-12345"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

استخدم متغيرات القالب بهذا الشكل:

<p>Hi {{params.name}},</p>
<p>Your order {{params.order_number}} has shipped.</p>
<p><a href="{{params.tracking_url}}">Track your package</a></p>
Enter fullscreen mode Exit fullscreen mode

الإرسال مع المرفقات 

const response = await fetch('https://api.brevo.com/v3/smtp/email', {
  method: 'POST',
  headers: {
    'api-key': process.env.BREVO_API_KEY,
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    sender: { name: 'Your App', email: 'noreply@yourapp.com' },
    to: [{ email: 'user@example.com' }],
    subject: 'Your Invoice',
    htmlContent: '<p>Please find your invoice attached.</p>',
    attachment: [
      {
        name: 'invoice.pdf',
        content: base64EncodedPdfContent
      }
    ]
  })
})
Enter fullscreen mode Exit fullscreen mode

الحملات التسويقية

تُستخدم لإرسال رسائل البريد الإلكتروني إلى قوائم جهات الاتصال، وتشمل إدارة روابط إلغاء الاشتراك والجدولة والتحليلات.

إنشاء حملة 

curl -X POST "https://api.brevo.com/v3/emailCampaigns" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "name": "March Newsletter",
    "subject": "What'\''s New in March",
    "sender": {
      "name": "Your Brand",
      "email": "newsletter@yourbrand.com"
    },
    "type": "classic",
    "htmlContent": "<html><body>Newsletter content here...</body></html>",
    "recipients": {
      "listIds": [12, 15]
    },
    "scheduledAt": "2026-03-25T09:00:00+00:00"
  }'
Enter fullscreen mode Exit fullscreen mode

الإرسال فورًا 

curl -X POST "https://api.brevo.com/v3/emailCampaigns/{campaignId}/sendNow" \
  -H "api-key: your-api-key"
Enter fullscreen mode Exit fullscreen mode

الحصول على إحصائيات الحملة 

curl -X GET "https://api.brevo.com/v3/emailCampaigns/{campaignId}" \
  -H "api-key: your-api-key"
Enter fullscreen mode Exit fullscreen mode

الاستجابة:

{
  "statistics": {
    "delivered": 4850,
    "opened": 1455,
    "clicked": 291,
    "unsubscribed": 12,
    "bounces": 150
  }
}
Enter fullscreen mode Exit fullscreen mode

إدارة جهات الاتصال

نظّم جهات الاتصال في قوائم، وأضف سمات مخصصة.

إنشاء جهة اتصال 

curl -X POST "https://api.brevo.com/v3/contacts" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "email": "new.user@example.com",
    "attributes": {
      "FIRSTNAME": "Jane",
      "LASTNAME": "Smith",
      "PLAN": "premium"
    },
    "listIds": [12, 15],
    "updateEnabled": true
  }'
Enter fullscreen mode Exit fullscreen mode

updateEnabled: true لتحديث جهات الاتصال الموجودة.

الحصول على تفاصيل جهة الاتصال 

curl -X GET "https://api.brevo.com/v3/contacts/user@example.com" \
  -H "api-key: your-api-key"
Enter fullscreen mode Exit fullscreen mode

الإضافة إلى قائمة 

curl -X POST "https://api.brevo.com/v3/contacts/lists/12/contacts/add" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "emails": ["user1@example.com", "user2@example.com"]
  }'
Enter fullscreen mode Exit fullscreen mode

الإزالة من قائمة 

curl -X DELETE "https://api.brevo.com/v3/contacts/lists/12/contacts/remove" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "emails": ["user@example.com"]
  }'
Enter fullscreen mode Exit fullscreen mode

إلغاء اشتراك جهة اتصال 

curl -X PUT "https://api.brevo.com/v3/contacts/user@example.com" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "emailBlacklisted": true
  }'
Enter fullscreen mode Exit fullscreen mode

تسويق الرسائل القصيرة (SMS)

يمكنك إرسال رسائل SMS عالميًا عبر Brevo.

إرسال رسالة SMS 

curl -X POST "https://api.brevo.com/v3/transactionalSMS/sms" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "sender": "YourApp",
    "recipient": "+15551234567",
    "content": "Your verification code is: 123456",
    "type": "transactional"
  }'
Enter fullscreen mode Exit fullscreen mode

إرسال رسائل SMS تسويقية 

curl -X POST "https://api.brevo.com/v3/transactionalSMS/sms" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "sender": "YourBrand",
    "recipient": "+15551234567",
    "content": "Flash sale! 50% off today only. Reply STOP to unsubscribe.",
    "type": "marketing"
  }'
Enter fullscreen mode Exit fullscreen mode

الحصول على إحصائيات الرسائل القصيرة 

curl -X GET "https://api.brevo.com/v3/transactionalSMS/statistics?startDate=2026-03-01&endDate=2026-03-31" \
  -H "api-key: your-api-key"
Enter fullscreen mode Exit fullscreen mode

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

خطافات الويب تمكنك من تتبع الأحداث (التسليم، الفتح، النقر، الارتداد، إلغاء الاشتراك).

تكوين خطافات الويب

من لوحة تحكم Brevo: Settings → Webhooks → Add webhook

أحداث يمكن تتبعها:

  • delivered: تم التسليم
  • opened: تم الفتح
  • clicked: تم النقر
  • bounced: ارتداد
  • spam: تم وضع علامة كسبام
  • unsubscribed: إلغاء الاشتراك

معالجة حمولة خطاف الويب 

app.post('/webhooks/brevo', (req, res) => {
  const event = req.body

  switch (event.event) {
    case 'delivered':
      console.log(`Email ${event.messageId} delivered to ${event.email}`)
      break
    case 'opened':
      console.log(`Email opened by ${event.email} at ${event.date}`)
      break
    case 'bounced':
      console.log(`Bounce: ${event.email} - ${event.reason}`)
      // Mark contact as invalid
      markContactBounced(event.email)
      break
    case 'spam':
      console.log(`Spam complaint from ${event.email}`)
      // Remove from all lists
      removeFromAllLists(event.email)
      break
    case 'unsubscribed':
      console.log(`Unsubscribed: ${event.email}`)
      break
  }

  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

الاختبار باستخدام Apidog

واجهات برمجة تطبيقات البريد الإلكتروني قد تفشل بطرق معقدة. اختبر القوالب، وارتدادات البريد، وخطافات الويب باستخدام Apidog.

apidog-validation

1. محاكاة إرسال البريد الإلكتروني 

pm.test('Email API accepts valid payload', () => {
  const response = pm.response.json()
  pm.expect(response).to.have.property('messageId')
  pm.expect(response.messageId).to.match(/<.*@relay\.brevo\.com>/)
})
Enter fullscreen mode Exit fullscreen mode

apidog-webhook

2. اختبار معالجة خطاف الويب

أنشئ حمولة وهمية في Apidog:

{
  "event": "bounced",
  "email": "invalid@example.com",
  "messageId": "<12345@relay.brevo.com>",
  "reason": "hard_bounce",
  "date": "2026-03-24T12:00:00Z",
  "subject": "Welcome to Our Platform"
}
Enter fullscreen mode Exit fullscreen mode

أرسلها إلى نقطة النهاية الخاصة بك وتحقق من أن الكود يعالجها بشكل صحيح.

3. التحقق من صحة القوالب 

pm.test('Template variables are valid', () => {
  const payload = pm.request.body.toJSON()
  pm.expect(payload.params).to.have.property('name')
  pm.expect(payload.params).to.have.property('order_number')
})
Enter fullscreen mode Exit fullscreen mode

4. فصل البيئات 

# Development
BREVO_API_KEY: xkeysib-dev-xxx
BREVO_SENDER: dev@yourapp.com

# Production
BREVO_API_KEY: xkeysib-prod-xxx
BREVO_SENDER: noreply@yourapp.com
Enter fullscreen mode Exit fullscreen mode

اختبر واجهات برمجة تطبيقات Brevo باستخدام Apidog - مجانًا

الأخطاء الشائعة والإصلاحات

400 طلب سيء – حقل مطلوب مفقود

السبب: الحمولة ناقصة حقل مطلوب

الإصلاح: تحقق من رسالة الخطأ. مثال:

{
  "code": "invalid_parameter",
  "message": "sender.email is required"
}
Enter fullscreen mode Exit fullscreen mode

401 غير مصرح به

السبب: مفتاح API غير صالح أو مفقود

الإصلاح: تأكد من وضع ترويسة api-key بشكل صحيح وأن المفتاح غير ملغي.

402 مطلوب دفع

السبب: تجاوز الحدود أو نفاد الرصيد

الإصلاح:

  • للبريد الإلكتروني: تحقق من الحد الشهري
  • للرسائل القصيرة: اشترِ أرصدة إضافية

429 عدد كبير جدًا من الطلبات

السبب: تجاوز حد المعدل

الإصلاح: نفذ التراجع الأُسي (exponential backoff):

async function sendWithRetry(email, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await sendEmail(email)
    if (response.status === 429) {
      await sleep(Math.pow(2, i) * 1000)
    } else {
      return response
    }
  }
  throw new Error('Rate limit exceeded')
}
Enter fullscreen mode Exit fullscreen mode

404 جهة الاتصال غير موجودة

السبب: محاولة تحديث جهة اتصال غير موجودة

الإصلاح: عند إنشاء جهة اتصال استخدم updateEnabled: true:

{
  "email": "new@example.com",
  "updateEnabled": true
}
Enter fullscreen mode Exit fullscreen mode

البدائل والمقارنات

الميزة Brevo SendGrid Mailchimp Postmark
الأسعار 300 رسالة بريد إلكتروني/يوم مجانًا 100 رسالة بريد إلكتروني/يوم مجانًا 500 رسالة بريد إلكتروني/شهر مجانًا 100 رسالة بريد إلكتروني/شهر مجانًا
رسائل البريد الإلكتروني التسويقية نعم نعم نعم لا
رسائل البريد الإلكتروني للمعاملات نعم نعم محدودة نعم (متخصصة)
الرسائل القصيرة (SMS) نعم لا لا لا
الأتمتة نعم نعم نعم محدودة
محرر القوالب مرئي + كود كود مرئي كود

Brevo تقدم دعمًا متكاملًا للبريد الإلكتروني والرسائل القصيرة بأسعار تنافسية.

حالات الاستخدام الواقعية

  • سير عمل التجارة الإلكترونية: تأكيد الطلب، إشعار الشحن، استعادة السلة، وعروض ترويجية، جميعها من خلال تكامل واحد.
  • إعداد مستخدمي SaaS: رسائل ترحيب، إعادة تعيين كلمة المرور، دعوات الفريق، بالإضافة إلى حملات تسويقية للمستخدمين.
  • التحقق عبر SMS: إرسال رموز المصادقة الثنائية عبر SMS، وتتبع فشل التسليم لمحاولة الإرسال مرة أخرى.

الخاتمة

ملخص عملي:

  • واجهات Brevo تدعم التسويق، البريد الإلكتروني للمعاملات، والرسائل القصيرة
  • المصادقة عبر ترويسة api-key
  • القوالب تمنحك رسائل موحدة وسهلة الصيانة
  • إدارة قوائم وجهات الاتصال للحملات المستهدفة
  • تتبع التسليم والارتداد عبر Webhooks
  • اختبر كل شيء عبر Apidog قبل الإطلاق

خطوات التنفيذ:

  1. أنشئ حسابًا في Brevo واحصل على مفتاح API
  2. أرسل أول رسالة بريد إلكتروني للمعاملات
  3. أنشئ قالبًا عبر المحرر المرئي
  4. أضف معالجات Webhook للارتداد وإلغاء الاشتراك
  5. اختبر التكامل عبر Apidog في بيئة التطوير

اختبر واجهات برمجة تطبيقات Brevo باستخدام Apidog – مجانًا

الأسئلة الشائعة

ما الفرق بين Brevo و Sendinblue؟

هما نفس المنتج، الاسم تغير فقط. Sendinblue أصبح Brevo في 2023. واجهات البرمجة الآن تحت api.brevo.com، لكن بعض الوثائق القديمة تشير للاسم السابق.

كم عدد الرسائل المجانية؟

300 رسالة يوميًا على الخطة المجانية (9,000 شهريًا). للزيادة، يمكنك الترقية إلى خطة مدفوعة.

هل يمكن استخدام Brevo للبريد الإلكتروني البارد؟

نظريًا نعم، لكن ذلك محفوف بالمخاطر بسبب ارتفاع معدل الارتداد والشكاوى. Brevo يراقب السمعة بدقة، وقد يؤدي ذلك إلى تعليق الحساب.

كيفية التعامل مع الرسائل المرتدة؟

استمع إلى Webhooks للحدث bounced. الارتداد القاسي: احذف جهة الاتصال نهائيًا. الارتداد اللين: أعد المحاولة لاحقًا. راقب معدل الارتداد (تجاوز 5% خطر).

ما الفرق بين الرسائل التسويقية والمعاملات؟

المعاملات: تفاعلات المستخدم (شراء، تسجيل...) إلى مستلم واحد. التسويقية: حملات جماعية. Brevo يفصل بينهما لأسباب تتعلق بالتسليم والامتثال.

كيف أضيف رابط إلغاء الاشتراك؟

Brevo يضيف الرابط تلقائيًا في الرسائل التسويقية. في الرسائل المعاملاتية أضف رابطك:

<a href="{{ unsubscribe_url }}">Unsubscribe</a>
Enter fullscreen mode Exit fullscreen mode

هل يمكن الإرسال من نطاقي الخاص؟

نعم. أضف سجلات SPF وDKIM وDMARC من إعدادات Brevo. بدونها قد يتم تصنيف الرسائل كسبام.

كيف أجدول رسالة في منطقة زمنية محددة؟

استخدم الحقل scheduledAt بتنسيق ISO 8601:

{
  "scheduledAt": "2026-03-25T09:00:00-05:00"
}
Enter fullscreen mode Exit fullscreen mode

ما الذي يحدث عند الوصول لحد المعدل؟

تتلقى خطأ 429، مع ترويسة X-RateLimit-Reset بالثواني المتبقية. استخدم التراجع الأُسي أو ضع الرسائل في طابور للإرسال لاحقًا.

Top comments (0)