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

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

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

# موصل Mailgun

حالة الموصل: مخطط له لم يُبنَ بعد. لا يشغّل Tajo هذا الموصل اليوم.

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

اربط Mailgun بـ Brevo من خلال Tajo لتوحيد بيانات البريد الإلكتروني المعاملاتي والتسويقي، ومزامنة أحداث التسليم ومقاييس التفاعل، ودمج البنية التحتية للبريد الإلكتروني في عرض عميل واحد.

## نظرة عامة

| الخاصية | القيمة |
| --- | --- |
| **المنصة** | Mailgun (من Sinch) |
| **الفئة** | التسويق عبر البريد الإلكتروني |
| **تعقيد الإعداد** | سهل |
| **تكامل رسمي** | لا |
| **البيانات المُزامَنة** | أحداث، جهات اتصال، قابلية التسليم، حملات |
| **طريقة المصادقة** | مفتاح API (HTTP Basic Auth) |

## الميزات

- **مزامنة أحداث التسليم** - تتبع الأحداث المُسلَّمة والمُرتدَّة والمفتوحة والمنقورة
- **مقاييس التفاعل** - مزامنة معدلات الفتح والنقرات مع سمات جهات اتصال Brevo
- **إدارة الارتدادات** - قمع العناوين المرتدة تلقائيًا في Brevo
- **معالجة الشكاوى** - مزامنة شكاوى البريد العشوائي لنظافة القائمة
- **سمعة النطاق** - مراقبة صحة نطاق الإرسال وقابلية التسليم
- **تتبع البريد المعاملاتي** - ربط الإرسال المعاملاتي ببيانات التسويق

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

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

1. حساب Mailgun مع نطاق إرسال مُوثَّق
2. مفتاح Mailgun API من [لوحة Mailgun](https://app.mailgun.com/settings/api_security)
3. حساب Brevo مع وصول إلى API
4. حساب Tajo مع صلاحيات الموصلات

## المصادقة

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

يستخدم Mailgun مصادقة HTTP Basic Authentication مع `api` كاسم مستخدم ومفتاح API الخاص بك ككلمة مرور:

```bash
# Get your API key from https://app.mailgun.com/settings/api_security
export MAILGUN_API_KEY=key-your-api-key
export MAILGUN_DOMAIN=your-domain.com
export TAJO_API_KEY=your_tajo_api_key
export BREVO_API_KEY=your_brevo_api_key
```

```javascript
// HTTP Basic Auth format
const headers = {
  'Authorization': `Basic ${Buffer.from(
    `api:${process.env.MAILGUN_API_KEY}`
  ).toString('base64')}`
};

// Or using curl
// curl -s --user 'api:YOUR_API_KEY' ...
```

أنواع مفاتيح API

يوفر Mailgun مفاتيح إرسال خاصة بالنطاق ومفاتيح API على مستوى الحساب. استخدم مفاتيح إرسال النطاق لعمليات الرسائل ومفتاح API للحساب لعمليات الإدارة.

## الإعداد

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

```yaml
connectors:
  mailgun:
    enabled: true
    api_key: "${MAILGUN_API_KEY}"
    domain: "${MAILGUN_DOMAIN}"
    region: "us"  # or "eu" for EU region

    sync:
      events: true
      contacts: true
      bounces: true
      complaints: true
      schedule: "*/15 * * * *"  # Every 15 minutes

    webhook:
      signing_key: "${MAILGUN_WEBHOOK_SIGNING_KEY}"

    lists:
      engaged: 30
      bounced: 31
      complained: 32
```

### تعيين الحقول

```yaml
field_mapping:
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  open_rate: MG_OPEN_RATE
  click_rate: MG_CLICK_RATE
  last_delivered: MG_LAST_DELIVERED
  bounce_type: MG_BOUNCE_TYPE
  engagement_score: MG_ENGAGEMENT
  unsubscribed: MG_UNSUBSCRIBED
```

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

| نقطة النهاية | الطريقة | الوصف |
| --- | --- | --- |
| `https://api.mailgun.net/v3/{domain}/messages` | POST | إرسال رسائل البريد الإلكتروني |
| `https://api.mailgun.net/v3/{domain}/events` | GET | استعلام سجلات الأحداث |
| `https://api.mailgun.net/v3/{domain}/bounces` | GET | سرد الارتدادات |
| `https://api.mailgun.net/v3/{domain}/complaints` | GET | سرد الشكاوى |
| `https://api.mailgun.net/v3/{domain}/unsubscribes` | GET | سرد إلغاءات الاشتراك |
| `https://api.mailgun.net/v3/{domain}/tags` | GET | سرد الوسوم |
| `https://api.mailgun.net/v3/{domain}/tags/{tag}/stats` | GET | الحصول على إحصائيات الوسم |
| `https://api.mailgun.net/v3/lists` | GET | سرد القوائم البريدية |
| `https://api.mailgun.net/v3/domains` | GET | سرد النطاقات |
| `https://api.mailgun.net/v4/address/validate` | POST | التحقق من عنوان البريد الإلكتروني |

منطقة EU

لحسابات Mailgun في الاتحاد الأوروبي، استخدم `https://api.eu.mailgun.net` بدلاً من `https://api.mailgun.net` لجميع نقاط نهاية API.

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

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

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

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

await tajo.connectors.connect('mailgun', {
  apiKey: process.env.MAILGUN_API_KEY,
  domain: process.env.MAILGUN_DOMAIN,
  region: 'us'
});
```

### إرسال رسالة عبر Mailgun API

```javascript
// إرسال بريد إلكتروني باستخدام Mailgun Messages API
const formData = new URLSearchParams();
formData.append('from', `Your App <noreply@${domain}>`);
formData.append('to', 'recipient@example.com');
formData.append('subject', 'Welcome to our platform');
formData.append('html', '<h1>Welcome!</h1><p>Thanks for signing up.</p>');
formData.append('o:tag', 'welcome-email');
formData.append('o:tracking', 'yes');

const response = await fetch(
  `https://api.mailgun.net/v3/${domain}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${Buffer.from(`api:${apiKey}`).toString('base64')}`
    },
    body: formData
  }
);

const result = await response.json();
// { id: '<message-id@domain.com>', message: 'Queued. Thank you.' }
```

### مزامنة أحداث البريد الإلكتروني مع Brevo

```javascript
// استعلام أحداث Mailgun ومزامنة بيانات التفاعل
const eventsResponse = await fetch(
  `https://api.mailgun.net/v3/${domain}/events?` +
    new URLSearchParams({
      begin: lastSyncDate,
      ascending: 'yes',
      limit: 300,
      event: 'delivered OR opened OR clicked'
    }),
  {
    headers: {
      'Authorization': `Basic ${Buffer.from(`api:${apiKey}`).toString('base64')}`
    }
  }
);

const { items, paging } = await eventsResponse.json();

for (const event of items) {
  const email = event.recipient;

  switch (event.event) {
    case 'delivered':
      await tajo.contacts.update(email, {
        attributes: { MG_LAST_DELIVERED: event.timestamp }
      });
      break;
    case 'opened':
      await tajo.events.track({
        email,
        event: 'email_opened',
        properties: { subject: event.message.headers.subject }
      });
      break;
    case 'clicked':
      await tajo.events.track({
        email,
        event: 'email_clicked',
        properties: { url: event.url }
      });
      break;
  }
}

// اتّبع التقسيم للمزيد من الأحداث
if (paging.next) {
  // جلب الصفحة التالية باستخدام عنوان paging.next
}
```

### التعامل مع Mailgun Webhooks

```javascript
const crypto = require('crypto');

app.post('/webhooks/mailgun', async (req, res) => {
  // التحقق من توقيع webhook
  const { timestamp, token, signature } = req.body.signature;
  const encodedToken = crypto
    .createHmac('sha256', process.env.MAILGUN_WEBHOOK_SIGNING_KEY)
    .update(timestamp.concat(token))
    .digest('hex');

  if (encodedToken !== signature) {
    return res.status(401).send('Unauthorized');
  }

  const eventData = req.body['event-data'];
  const event = eventData.event;
  const email = eventData.recipient;

  await tajo.connectors.handleWebhook('mailgun', {
    topic: event,
    payload: eventData
  });

  // معالجة قمع الارتدادات
  if (event === 'failed' && eventData.severity === 'permanent') {
    await tajo.contacts.update(email, {
      attributes: { MG_BOUNCE_TYPE: 'hard_bounce' },
      emailBlacklisted: true
    });
  }

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

### مزامنة الارتدادات والشكاوى

```javascript
// مزامنة العناوين المرتدة لنظافة القائمة
const bouncesResponse = await fetch(
  `https://api.mailgun.net/v3/${domain}/bounces?limit=100`,
  {
    headers: {
      'Authorization': `Basic ${Buffer.from(`api:${apiKey}`).toString('base64')}`
    }
  }
);

const { items: bounces } = await bouncesResponse.json();

for (const bounce of bounces) {
  await tajo.contacts.update(bounce.address, {
    attributes: {
      MG_BOUNCE_TYPE: bounce.error.includes('550') ? 'hard_bounce' : 'soft_bounce',
      MG_BOUNCE_DATE: bounce.created_at
    },
    emailBlacklisted: bounce.error.includes('550')
  });
}
```

## حدود المعدل

| نقطة النهاية | الحد | ملاحظات |
| --- | --- | --- |
| Messages API | يختلف حسب الخطة | 100/ساعة (مجاني)، غير محدود (مدفوع) |
| Events API | لا يوجد حد صريح | استخدم التقسيم بـ 300 عنصر كحد أقصى |
| Validation API | بناءً على الخطة | ادفع مقابل كل عملية تحقق |
| Webhooks | آنية | لا يوجد حد معدل على التسليم |
| Suppressions API | لا يوجد حد صريح | تطبّق حدود المعدل القياسية |

حدود الإرسال

يفرض Mailgun حدود إرسال بناءً على خطتك وسمعة نطاقك. تبدأ النطاقات الجديدة بحدود أقل تزداد مع تحسن سمعة المرسل. راقب إحصائيات نطاقك في لوحة Mailgun.

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

| المشكلة | السبب | الحل |
| --- | --- | --- |
| 401 Unauthorized | مفتاح API غير صالح | تحقق من مفتاح API في لوحة Mailgun |
| النطاق غير مُوثَّق | سجلات DNS مفقودة | أضف سجلات TXT وCNAME وMX المطلوبة |
| Webhook لم يُستلم | عنوان URL غير قابل للوصول | تأكد من أن عنوان URL لـ webhook قابل للوصول علنيًا |
| الأحداث مفقودة | نطاق الوقت ضيق جدًا | وسّع معاملات `begin`/`end` |
| قابلية تسليم منخفضة | سمعة النطاق | تحقق من إحصائيات النطاق والمصادقة |

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

```yaml
connectors:
  mailgun:
    debug: true
    log_level: verbose
    log_webhooks: true
    log_events: true
```

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

1. **وثّق نطاقات الإرسال** - أكمل التحقق من DNS لقابلية تسليم مثلى
2. **استخدم webhooks للأحداث** - تسليم webhook آني مقابل استطلاع Events API
3. **تعامل مع الارتدادات استباقيًا** - اقمع الارتدادات الصعبة فورًا في Brevo
4. **ضع وسومًا على رسائلك** - استخدم الوسوم لتصنيف وتحليل أداء البريد الإلكتروني
5. **راقب سمعة النطاق** - تتبع مقاييس قابلية التسليم في لوحة Mailgun
6. **استخدم التحقق من البريد الإلكتروني** - تحقق من العناوين قبل إضافتها إلى قوائم Brevo

## الأمان

- **HTTP Basic Auth** - مفتاح API يُنقل عبر ترويسة Authorization
- **توقيعات Webhook** - التحقق من توقيع HMAC-SHA256
- **التحقق من النطاق** - مصادقة DNS عبر SPF وDKIM وDMARC
- **قائمة IP المسموح بها** - متاحة لخطط IP المخصصة
- **تشفير TLS** - تتطلب جميع نقاط نهاية API بروتوكول HTTPS
- **تدوير المفاتيح** - دوّر مفاتيح API دوريًا عبر لوحة Mailgun

## موارد ذات صلة

- [موصل Brevo](https://tajo.io/ar/docs/connectors/marketing/brevo)
- [موصل Segment](https://tajo.io/ar/docs/connectors/custom/segment)
- [مهارة مزامنة العملاء](https://tajo.io/ar/docs/skills/data-sync/customer-sync)
- [وثائق Mailgun API](https://documentation.mailgun.com/)