موصل SendGrid

اربط حساب SendGrid الخاص بك مع Brevo عبر Tajo لترحيل البنية التحتية للبريد الإلكتروني، ومزامنة جهات الاتصال، ونقل بيانات الحملات، وتحليلات تفاعل موحدة عبر المنصتين.

نظرة عامة

الميزات

• ترحيل جهات الاتصال - ترحيل جهات اتصال SendGrid Marketing إلى Brevo مع الحقول المخصصة
• مزامنة البريد المعاملاتي - تتبع أحداث البريد المعاملاتي للتقارير الموحدة
• بيانات الحملات - مزامنة بيانات أداء حملات Single Send وAutomation
• webhooks الأحداث - إعادة توجيه أحداث البريد الإلكتروني (مُسلَّم، مفتوح، منقور، مرتد) إلى Brevo
• مزامنة القمع - ترحيل قوائم الارتداد والحظر وإلغاء الاشتراك للامتثال
• ترحيل القوالب - تصدير Dynamic Transactional Templates لاستخدام Brevo
• التحقق من المرسل - مزامنة هويات المرسل المُوثَّقة ومصادقة النطاق
• مزامنة الإحصائيات - استيراد إحصائيات التفاعل التاريخية إلى سمات Brevo

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

1. حساب SendGrid (Free أو Essentials أو Pro أو Premier)
2. مفتاح SendGrid API مع الصلاحيات المطلوبة
3. حساب Brevo مع وصول إلى API
4. حساب Tajo

المصادقة

مصادقة مفتاح API

يستخدم SendGrid مصادقة bearer token.

curl https://api.sendgrid.com/v3/marketing/contacts \
  -H "Authorization: Bearer SG.YOUR_API_KEY" \
  -H "Content-Type: application/json"

أنشئ مفاتيح API في SendGrid Settings > API Keys بمستويات صلاحية محددة:

• Full Access - وصول API كامل
• Restricted Access - تحكم دقيق في الصلاحيات
• Billing Access - عمليات الفوترة فقط

الصلاحيات المطلوبة

Marketing: Full Access
  - Contacts (read)
  - Single Sends (read)
  - Automations (read)
Mail Send: Full Access
  - Mail Send (read)
Stats: Read Access
Suppressions: Read Access
Tracking: Read Access

الإعداد

الإعداد الأساسي

connectors:
  sendgrid:
    enabled: true
    api_key: "${SENDGRID_API_KEY}"

    # Data sync options
    sync:
      contacts: true
      campaigns: true
      transactional: true
      suppressions: true
      statistics: true

    # List mapping to Brevo
    list_mapping:
      "All Contacts": 60
      "Newsletter": 61
      "Transactional": 62

تعيين الحقول

ربط حقول جهات اتصال SendGrid بسمات جهات اتصال Brevo:

تعيين الحقول المخصصة

field_mapping:
  # Standard fields
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone_number: SMS

  # Location fields
  city: CITY
  state_province_region: STATE
  country: COUNTRY
  postal_code: POSTAL_CODE

  # Engagement metrics
  avg_open_rate: AVG_OPEN_RATE
  avg_click_rate: AVG_CLICK_RATE

  # Custom fields
  custom_fields.company: COMPANY_NAME
  custom_fields.plan: PLAN_TYPE

نقاط نهاية واجهة البرمجة

جهات الاتصال التسويقية

البريد المعاملاتي (Mail Send)

الحملات (Single Sends)

الإحصائيات

القمع

الأحداث

أحداث البريد الإلكتروني (عبر Event Webhook)

أمثلة على الكود

تهيئة الموصل

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect SendGrid
await tajo.connectors.connect('sendgrid', {
  apiKey: process.env.SENDGRID_API_KEY
});

ترحيل جهات الاتصال إلى Brevo

// ترحيل كامل لجهات الاتصال من SendGrid إلى Brevo
await tajo.connectors.sync('sendgrid', {
  type: 'full',
  resources: ['contacts', 'suppressions'],
  options: {
    includeCustomFields: true,
    migrateListMemberships: true,
    migrateSuppressions: true
  }
});

// التحقق من حالة الترحيل
const status = await tajo.connectors.status('sendgrid');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsMigrated: 45000,
//   suppressionsSynced: 3200,
//   listsMapped: 8
// }

إعادة توجيه أحداث البريد الإلكتروني

// التعامل مع SendGrid Event Webhook
app.post('/webhooks/sendgrid', async (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');

  // التحقق من توقيع webhook (ECDSA)
  if (!verifySendGridSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  // معالجة دفعة من الأحداث
  for (const event of req.body) {
    await tajo.connectors.handleWebhook('sendgrid', {
      type: event.event,
      email: event.email,
      timestamp: event.timestamp,
      payload: event
    });
  }

  res.status(200).send('OK');
});

حدود المعدل

حدود معدل SendGrid API:

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

المشاكل الشائعة

وضع التصحيح

تفعيل التسجيل المفصل:

connectors:
  sendgrid:
    debug: true
    log_level: verbose
    log_webhooks: true

اختبار الاتصال

tajo connectors test sendgrid
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Lists accessible
# ✓ Statistics readable
# ✓ Suppressions accessible

أفضل الممارسات

1. رحّل القمع أولاً - تأكد من وجود الارتدادات والحظر وإلغاءات الاشتراك في Brevo قبل الإرسال
2. استخدم تحميلات جهات الاتصال المجمّعة - PUT حتى 30,000 جهة اتصال لكل طلب للكفاءة
3. تحقق من Event Webhook - فعّل webhooks الموقّعة مع التحقق من ECDSA
4. عيّن الحقول المخصصة - أنشئ سمات Brevo المقابلة قبل ترحيل جهات الاتصال
5. زامن بيانات التفاعل - استورد الإحصائيات التاريخية للتقسيم في Brevo
6. تعامل مع التصديرات غير المتزامنة - تصديرات جهات الاتصال غير متزامنة؛ استطلع للاكتمال

الأمان

• مصادقة مفتاح API - Bearer token بمستويات صلاحية دقيقة
• توقيع Event Webhook - التحقق من توقيع ECDSA لحمولات webhook
• تشفير TLS - جميع اتصالات API مشفرة عبر HTTPS
• إدارة وصول IP - قيّد وصول لوحة التحكم وAPI حسب IP
• المصادقة الثنائية - 2FA متاحة للوصول إلى الحساب

موارد ذات صلة

• وثائق SendGrid API
• دليل SendGrid Event Webhook
• موصل Brevo
• موصل Mailchimp
• مهارة مزامنة العملاء