---
title: "Коннектор Mailgun"
description: "Полное руководство по интеграции Mailgun для синхронизации данных о доставке email, метрик вовлечённости и транзакционных событий с Brevo через Tajo."
url: https://tajo.io/ru/docs/connectors/marketing/mailgun/
markdown: https://tajo.io/ru/docs/connectors/marketing/mailgun.md
lang: ru-RU
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 для объединения транзакционных и маркетинговых данных email, синхронизации событий доставки и метрик вовлечённости, а также консолидации email-инфраструктуры в единое представление о клиенте.

## Обзор

| Свойство | Значение |
| --- | --- |
| **Платформа** | Mailgun (от Sinch) |
| **Категория** | Email Marketing |
| **Сложность настройки** | Простая |
| **Официальная интеграция** | Нет |
| **Синхронизируемые данные** | События, контакты, доставляемость, кампании |
| **Метод аутентификации** | API Key (HTTP Basic Auth) |

## Возможности

- **Синхронизация событий доставки**, трекинг событий доставки, отказов, открытий и кликов
- **Метрики вовлечённости**, синхронизация показателей открытий и кликов в атрибуты контактов Brevo
- **Управление отказами**, автоматическое исключение адресов с отказами в Brevo
- **Обработка жалоб**, синхронизация жалоб на спам для гигиены списков
- **Репутация домена**, мониторинг состояния домена отправителя и доставляемости
- **Трекинг транзакционных email**, корреляция транзакционных отправок с маркетинговыми данными

## Предварительные требования

Прежде чем начать, убедитесь, что у вас есть:

1. Аккаунт Mailgun с верифицированным доменом отправителя
2. API-ключ Mailgun из [Mailgun Dashboard](https://app.mailgun.com/settings/api_security)
3. Аккаунт Brevo с доступом к API
4. Аккаунт Tajo с разрешениями коннектора

## Аутентификация

### Аутентификация по API Key

Mailgun использует HTTP Basic Authentication с `api` в качестве имени пользователя и вашим API-ключом в качестве пароля:

```bash
# Получите API-ключ по адресу 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
const headers = {
  'Authorization': `Basic ${Buffer.from(
    `api:${process.env.MAILGUN_API_KEY}`
  ).toString('base64')}`
};

// Или через curl
// curl -s --user 'api:YOUR_API_KEY' ...
```

Типы API Key

Mailgun предоставляет ключи отправки для конкретного домена и ключи API уровня аккаунта. Используйте ключи отправки домена для операций с сообщениями и ключ API аккаунта для операций управления.

## Конфигурация

### Базовая настройка

```yaml
connectors:
  mailgun:
    enabled: true
    api_key: "${MAILGUN_API_KEY}"
    domain: "${MAILGUN_DOMAIN}"
    region: "us"  # или "eu" для региона ЕС

    sync:
      events: true
      contacts: true
      bounces: true
      complaints: true
      schedule: "*/15 * * * *"  # Каждые 15 минут

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

## Эндпоинты API

| Эндпоинт | Метод | Описание |
| --- | --- | --- |
| `https://api.mailgun.net/v3/{domain}/messages` | POST | Отправка email-сообщений |
| `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 | Валидация email-адреса |

Регион ЕС

Для аккаунтов 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
// Отправка email через Messages API Mailgun
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.' }
```

### Синхронизация событий email в 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) {
  // Получение следующей страницы по URL paging.next
}
```

### Обработка вебхуков Mailgun

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

app.post('/webhooks/mailgun', async (req, res) => {
  // Верификация подписи вебхука
  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-записи |
| Вебхук не получен | URL недоступен | Убедитесь, что URL вебхука публично доступен |
| Отсутствуют события | Слишком узкий диапазон времени | Расширьте параметры `begin`/`end` |
| Низкая доставляемость | Репутация домена | Проверьте статистику домена и аутентификацию |

### Режим отладки

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

## Лучшие практики

1. **Верифицируйте домены отправителя**, выполните DNS-верификацию для оптимальной доставляемости
2. **Используйте вебхуки для событий**, доставка вебхуков в реальном времени лучше опроса Events API
3. **Проактивно обрабатывайте отказы**, немедленно исключайте жёсткие отказы в Brevo
4. **Тегируйте сообщения**, используйте теги для категоризации и анализа эффективности email
5. **Мониторьте репутацию домена**, отслеживайте метрики доставляемости в дашборде Mailgun
6. **Используйте валидацию email**, валидируйте адреса перед добавлением в списки Brevo

## Безопасность

- **HTTP Basic Auth**, API-ключ передаётся через заголовок Authorization
- **Подписи вебхуков**, верификация подписи HMAC-SHA256
- **Верификация домена**, DNS-аутентификация SPF, DKIM и DMARC
- **IP-разрешение**, доступно для планов с выделенными IP
- **TLS-шифрование**, все API-эндпоинты требуют HTTPS
- **Ротация ключей**, периодически ротируйте API-ключи через дашборд Mailgun

## Связанные ресурсы

- [Коннектор Brevo](https://tajo.io/ru/docs/connectors/marketing/brevo)
- [Коннектор Segment](https://tajo.io/ru/docs/connectors/custom/segment)
- [Скилл синхронизации клиентов](https://tajo.io/ru/docs/skills/data-sync/customer-sync)
- [Документация Mailgun API](https://documentation.mailgun.com/)