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

ملخص

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

مقدمة

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

تبدو واجهات برمجة تطبيقات البريد الإلكتروني بسيطة - أرسل رسالة، وانتهى الأمر. ولكن أنظمة البريد الإلكتروني للإنتاج تحتاج إلى التعامل مع رسائل الارتداد، وشكاوى الرسائل غير المرغوب فيها (spam)، وإلغاء الاشتراك، وتوقيت التسليم. تدير Brevo هذا التعقيد حتى لا تضطر أنت لذلك.

تغطي واجهة برمجة التطبيقات ثلاث حالات استخدام رئيسية:

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

💡

إذا كنت تقوم بدمج البريد الإلكتروني في تطبيقك، فإن Apidog يساعدك على اختبار القوالب، والتحقق من صحة حمولات الويب هوك (webhook payloads)، والتأكد من أن تكاملك يعمل عبر عملاء البريد الإلكتروني. يمكنك محاكاة استجابات Brevo أثناء التطوير واختبار معالجة الأخطاء دون إرسال رسائل بريد إلكتروني حقيقية.

button

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

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

سجل الدخول إلى Brevo
انتقل إلى SMTP & API ← API Keys (مفاتيح API)
أنشئ مفتاحًا جديدًا بالصلاحيات المناسبة
قم بتخزينه بأمان

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

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

عنوان URL الأساسي لواجهة برمجة التطبيقات

تذهب جميع الطلبات إلى:

https://api.brevo.com/v3/

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

تحدد Brevo الطلبات حسب الخطة:

مجاني: 300 طلب/دقيقة
المبتدئ (Starter): 600 طلب/دقيقة
الأعمال (Business): 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."
  }'

الاستجابة:

{
  "messageId": "<20260324123456.123456@relay.brevo.com>"
}

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

أنشئ قوالب في المحرر المرئي لـ Brevo، ثم أرسلها باستخدام المعرّف:

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"
    }
  }'

تستخدم متغيرات القالب الأقواس المزدوجة:

<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>

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

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
      }
    ]
  })
})

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

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

إنشاء حملة

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"
  }'

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

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

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

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

تتضمن الاستجابة:

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

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

جهات الاتصال هم الأشخاص الذين ترسل إليهم رسائل البريد الإلكتروني. قم بتنظيمهم في قوائم وأضف سمات مخصصة.

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

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
  }'

تعمل علامة updateEnabled: true على تحديث جهات الاتصال الموجودة بدلاً من الفشل.

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

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

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

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"]
  }'

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

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"]
  }'

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

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
  }'

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

ترسل Brevo رسائل SMS عالميًا عبر واجهة برمجة تطبيقات الرسائل القصيرة الخاصة بها.

إرسال رسالة 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"
  }'

إرسال رسائل 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"
  }'

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

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

خطافات الويب (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')
})

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

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

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>/)
})

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"
}

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

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')
})

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

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

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

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

السبب: حمولة البيانات تفتقر إلى حقول مطلوبة.

الإصلاح: تحقق من رسالة الخطأ لمعرفة التفاصيل:

{
  "code": "invalid_parameter",
  "message": "sender.email is required"
}

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')
}

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

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

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

{
  "email": "new@example.com",
  "updateEnabled": true
}

هذا ينشئ أو يحدث جهة الاتصال.

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

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

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

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

سير عمل طلبات التجارة الإلكترونية. يستخدم متجر عبر الإنترنت Brevo لـ: تأكيد الطلب (معاملات)، إشعار الشحن (معاملات)، استعادة سلة التسوق المهجورة (أتمتة تسويقية)، وعروض ترويجية أسبوعية (حملات تسويقية). كل ذلك من خلال تكامل واحد.

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

التحقق عبر الرسائل القصيرة. يستخدم تطبيق مالي Brevo's SMS API لرموز المصادقة الثنائية. تقوم نقطة نهاية الرسائل القصيرة للمعاملات بتسليم الرموز في غضون ثوانٍ، وتتبع خطافات الويب فشل التسليم لمنطق إعادة المحاولة.

الخاتمة

إليك ما تعلمته:

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

خطواتك التالية:

أنشئ حسابًا في Brevo واحصل على مفتاح API
أرسل أول رسالة بريد إلكتروني للمعاملات
أنشئ قالبًا في المحرر المرئي
أعدّ معالجات خطاف الويب لرسائل الارتداد وإلغاء الاشتراك
اختبر باستخدام Apidog في مرحلة التطوير

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

button

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

ما الفرق بين Brevo و Sendinblue؟نفس المنتج، اسم جديد. أعادت Sendinblue تسمية نفسها إلى Brevo في عام 2023. لا تزال واجهات برمجة التطبيقات تستخدم api.brevo.com ولكنك ستجد إشارات إلى Sendinblue في الوثائق القديمة.

كم عدد رسائل البريد الإلكتروني التي يمكنني إرسالها مجانًا؟300 رسالة بريد إلكتروني يوميًا على الخطة المجانية. هذا يعني 9,000 رسالة بريد إلكتروني شهريًا. للمزيد، قم بالترقية إلى خطة مدفوعة تبدأ من 25 دولارًا شهريًا لـ 20,000 رسالة بريد إلكتروني.

هل يمكنني استخدام Brevo لرسائل البريد الإلكتروني الباردة (cold emails)؟نظريًا نعم، ولكن هذا محفوف بالمخاطر. رسائل البريد الإلكتروني الباردة لديها معدلات ارتداد ورسائل غير مرغوب فيها عالية. تراقب Brevo سمعة المرسل. معدلات الشكاوى العالية تؤدي إلى تعليق الحسابات. قم بـ "تسخين" نطاقك أولاً واتبع أفضل ممارسات البريد الإلكتروني.

كيف أتعامل مع رسائل البريد الإلكتروني المرتدة؟استمع إلى خطافات الويب (webhooks) من نوع bounced. الارتدادات القاسية (بريد إلكتروني غير صالح) يجب أن تزيل جهات الاتصال بشكل دائم. يمكن إعادة محاولة الارتدادات اللينة (صندوق البريد ممتلئ، مشاكل مؤقتة). تتبع معدل الارتداد - إذا تجاوز 5%، تنخفض سمعة المرسل لديك.

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

كيف أضيف رابط إلغاء الاشتراك؟تضيف Brevo تلقائيًا روابط إلغاء الاشتراك إلى رسائل البريد الإلكتروني التسويقية. بالنسبة لرسائل البريد الإلكتروني للمعاملات، أضف الرابط الخاص بك:

<a href="{{ unsubscribe_url }}">Unsubscribe</a>

هل يمكنني إرسال رسائل بريد إلكتروني من نطاقي الخاص؟نعم. قم بإعداد سجلات SPF و DKIM و DMARC. توفر Brevo القيم في الإعدادات (Settings) ← المرسل وعنوان IP (Sender & IP). بدون المصادقة الصحيحة، قد تصل رسائل البريد الإلكتروني إلى البريد العشوائي.

كيف أجدول رسائل البريد الإلكتروني في منطقة زمنية محددة؟استخدم المعامل scheduledAt مع ختم زمني بتنسيق ISO 8601:

{
  "scheduledAt": "2026-03-25T09:00:00-05:00"
}

ماذا يحدث إذا وصلت إلى حد المعدل؟ستتلقى خطأ 429. تتضمن الاستجابة ترويسة X-RateLimit-Reset مع الثواني المتبقية حتى إعادة الضبط. قم بتنفيذ التراجع الأُسي (exponential backoff) أو قم بوضع رسائل البريد الإلكتروني في قائمة انتظار للإرسال لاحقًا.