---
title: "موصل SendGrid"
description: "دليل تكامل SendGrid الشامل لمزامنة جهات الاتصال، والبريد المعاملاتي، والحملات التسويقية، وأحداث التفاعل مع Brevo عبر Tajo."
url: https://tajo.io/ar/docs/connectors/marketing/sendgrid/
markdown: https://tajo.io/ar/docs/connectors/marketing/sendgrid.md
lang: ar-SA
robots: noindex
---

اطلب الوصول المبكر

أدخل اسمك الأول وعنوان بريدك الإلكتروني للعمل. سنرسل إليك رابطًا لتأكيد طلب الوصول إلى Tajo.

# موصل SendGrid

حالة الموصل: قيد التطوير قيد البناء. لم يتم التحقق منه بعد.

| حقل المصدر | حقل الوجهة | قيمة نموذجية |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

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

## نظرة عامة

| الخاصية | القيمة |
| --- | --- |
| **المنصة** | SendGrid (Twilio) |
| **الفئة** | التسويق |
| **تعقيد الإعداد** | سهل |
| **تكامل رسمي** | لا |
| **البيانات المُزامَنة** | جهات اتصال، حملات، بريد معاملاتي، أحداث |
| **عنوان URL الأساسي لـ API** | `https://api.sendgrid.com/v3` |

## الميزات

- **ترحيل جهات الاتصال** - ترحيل جهات اتصال 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.

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

أمان مفتاح API

تُعرض مفاتيح SendGrid API مرة واحدة فقط عند الإنشاء. خزّنها بأمان. في حالة الفقد، يجب عليك إنشاء مفتاح جديد.

## الإعداد

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

```yaml
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:

#### التعيينات الافتراضية

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | عنوان البريد الإلكتروني لجهة الاتصال (معرّف فريد) |
| `first_name` optional | string | يُعيَّن إلى سمة FIRSTNAME |
| `last_name` optional | string | يُعيَّن إلى سمة LASTNAME |
| `phone_number` optional | string | يُعيَّن إلى سمة SMS |
| `city` optional | string | مدينة جهة الاتصال |
| `country` optional | string | دولة جهة الاتصال |
| `custom_fields` optional | object | أزواج مفتاح-قيمة للحقول المخصصة |
| `list_ids` optional | array | عضويات قوائم SendGrid |

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

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

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

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

| الطريقة | نقطة النهاية | الوصف |
| --- | --- | --- |
| `PUT` | `/v3/marketing/contacts` | إضافة أو تحديث جهات الاتصال |
| `POST` | `/v3/marketing/contacts/search` | البحث في جهات الاتصال |
| `GET` | `/v3/marketing/contacts/count` | الحصول على عدد جهات الاتصال |
| `POST` | `/v3/marketing/contacts/exports` | تصدير جهات الاتصال |
| `DELETE` | `/v3/marketing/contacts` | حذف جهات الاتصال |
| `GET` | `/v3/marketing/lists` | سرد جميع قوائم جهات الاتصال |

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

| الطريقة | نقطة النهاية | الوصف |
| --- | --- | --- |
| `POST` | `/v3/mail/send` | إرسال بريد إلكتروني |
| `GET` | `/v3/templates` | سرد Dynamic Templates |
| `GET` | `/v3/templates/{id}` | الحصول على تفاصيل القالب |

### الحملات (Single Sends)

| الطريقة | نقطة النهاية | الوصف |
| --- | --- | --- |
| `GET` | `/v3/marketing/singlesends` | سرد Single Sends |
| `GET` | `/v3/marketing/singlesends/{id}` | الحصول على تفاصيل Single Send |
| `GET` | `/v3/marketing/automations` | سرد Automations |

### الإحصائيات

| الطريقة | نقطة النهاية | الوصف |
| --- | --- | --- |
| `GET` | `/v3/stats` | الحصول على إحصائيات البريد الإلكتروني العامة |
| `GET` | `/v3/categories/stats` | الحصول على إحصائيات الفئات |
| `GET` | `/v3/marketing/stats/singlesends` | الحصول على إحصائيات Single Send |

### القمع

| الطريقة | نقطة النهاية | الوصف |
| --- | --- | --- |
| `GET` | `/v3/suppression/bounces` | سرد الرسائل المرتدة |
| `GET` | `/v3/suppression/blocks` | سرد الرسائل المحظورة |
| `GET` | `/v3/suppression/spam_reports` | سرد تقارير البريد العشوائي |
| `GET` | `/v3/suppression/unsubscribes` | سرد إلغاءات الاشتراك العامة |

## الأحداث

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

| الحدث | المحفز | حالة الاستخدام |
| --- | --- | --- |
| `processed` | قبل SendGrid البريد الإلكتروني | تأكيد الإرسال |
| `delivered` | سُلِّم البريد الإلكتروني للمستلم | تتبع التسليم |
| `open` | تم فتح البريد الإلكتروني | تسجيل التفاعل |
| `click` | تم النقر على رابط | تتبع الاهتمام |
| `bounce` | ارتد البريد الإلكتروني | نظافة القائمة |
| `dropped` | تم قمع البريد الإلكتروني | مراجعة الامتثال |
| `deferred` | تأجيل التسليم | مراقبة إعادة المحاولة |
| `spam_report` | تم وضع علامة بريد عشوائي | إدارة السمعة |
| `unsubscribe` | ألغى الاشتراك عبر الرابط | مزامنة التفضيلات |

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

### تهيئة الموصل

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

```javascript
// ترحيل كامل لجهات الاتصال من 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
// }
```

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

```javascript
// التعامل مع 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:

| نقطة النهاية | الحد | التفاصيل |
| --- | --- | --- |
| Mail Send (`/v3/mail/send`) | يعتمد على الخطة | Free: 100/يوم، Essentials: بناءً على الخطة |
| Marketing Contacts PUT | 3 طلبات/ثانية | دفعة تصل إلى 30,000 جهة اتصال |
| Marketing Contacts Search | 50 طلب/ثانية | لكل مفتاح API |
| API العام | 1,000 طلب/ثانية | لكل مفتاح API |
| Event Webhook | تسليم مجمّع | حتى 1,000 حدث لكل POST |

حدود Mail Send

تعتمد حدود Mail Send على خطة SendGrid الخاصة بك. تقتصر الحسابات المجانية على 100 بريد إلكتروني/يوم. تحقق من تفاصيل خطتك لحدود الإرسال الدقيقة.

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

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

| المشكلة | السبب | الحل |
| --- | --- | --- |
| 401 Unauthorized | مفتاح API غير صالح | تحقق من مفتاح API في SendGrid Settings |
| 403 Forbidden | صلاحيات مفتاح API غير كافية | أنشئ مفتاحًا جديدًا بالنطاقات المطلوبة |
| تصدير جهات الاتصال معلّق | معالجة مجموعة بيانات كبيرة | استطلع نقطة نهاية حالة التصدير حتى الاكتمال |
| مزامنة القمع غير مكتملة | التقسيم مطلوب | طبّق التقسيم بمعامل offset |
| Event webhook لم يُستلم | عنوان URL غير مُوثَّق | أكمل التحقق من عنوان URL لـ webhook في SendGrid |

### وضع التصحيح

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

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

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

```bash
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](https://docs.sendgrid.com/api-reference)
- [دليل SendGrid Event Webhook](https://docs.sendgrid.com/for-developers/tracking-events/event)
- [موصل Brevo](https://tajo.io/ar/docs/connectors/marketing/brevo)
- [موصل Mailchimp](https://tajo.io/ar/docs/connectors/marketing/mailchimp)
- [مهارة مزامنة العملاء](https://tajo.io/ar/docs/skills/data-sync/customer-sync)