Mailgun конектор
Свържи Mailgun с Brevo през Tajo, за да унифицираш транзакционните и маркетинговите си имейл данни, да синхронизираш събития от доставка и метрики за ангажираност и да консолидираш своята имейл инфраструктура в единен клиентски изглед.
Преглед
| Свойство | Стойност |
|---|---|
| Платформа | Mailgun (by Sinch) |
| Категория | Имейл маркетинг |
| Сложност на настройка | Лесна |
| Официална интеграция | Не |
| Синхронизирани данни | Събития, контакти, deliverability, кампании |
| Метод на автентикация | API Key (HTTP Basic Auth) |
Функции
- Синхронизация на delivery събития – Проследявай delivered, bounced, opened и clicked събития
- Метрики за ангажираност – Синхронизирай open и click rates към атрибути на контактите в Brevo
- Управление на bounces – Автоматично suppress-вай bounced адреси в Brevo
- Обработка на complaints – Синхронизирай spam complaints за хигиена на списък
- Репутация на домейн – Мониторирай здравето на изпращащия домейн и deliverability
- Проследяване на транзакционни имейли – Корелирай транзакционните изпращания с маркетингови данни
Предварителни условия
Преди да започнеш, увери се, че имаш:
- Акаунт в Mailgun с верифициран sending домейн
- Mailgun API ключ от Mailgun Dashboard
- Акаунт в Brevo с API достъп
- Акаунт в Tajo с разрешения за конектори
Автентикация
Автентикация с API ключ
Mailgun използва HTTP Basic Authentication с api като username и твоя API ключ като парола:
# Get your API key from https://app.mailgun.com/settings/api_securityexport MAILGUN_API_KEY=key-your-api-keyexport MAILGUN_DOMAIN=your-domain.comexport TAJO_API_KEY=your_tajo_api_keyexport BREVO_API_KEY=your_brevo_api_key// HTTP Basic Auth formatconst 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 предоставя domain-specific sending ключове и account-level API ключове. Използвай domain sending ключове за операции със съобщения, а account API ключа за management операции.
Конфигурация
Основна настройка
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Мапване на полета
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_UNSUBSCRIBEDAPI крайни точки
| Крайна точка | Метод | Описание |
|---|---|---|
https://api.mailgun.net/v3/{domain}/messages | POST | Изпращане на имейл съобщения |
https://api.mailgun.net/v3/{domain}/events | GET | Заявка на логове със събития |
https://api.mailgun.net/v3/{domain}/bounces | GET | Списък с bounces |
https://api.mailgun.net/v3/{domain}/complaints | GET | Списък с complaints |
https://api.mailgun.net/v3/{domain}/unsubscribes | GET | Списък с unsubscribes |
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 | Списък с mailing списъци |
https://api.mailgun.net/v3/domains | GET | Списък с домейни |
https://api.mailgun.net/v4/address/validate | POST | Валидиране на имейл адрес |
EU регион
За EU-базирани Mailgun акаунти използвай https://api.eu.mailgun.net вместо https://api.mailgun.net за всички API крайни точки.
Примери с код
Инициализация на конектора
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
// Send an email using Mailgun's Messages APIconst formData = new URLSearchParams();formData.append('from', `Your App <noreply@${domain}>`);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: '<[email protected]>', message: 'Queued. Thank you.' }Синхронизация на имейл събития към Brevo
// Query Mailgun events and sync engagement dataconst 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; }}
// Follow pagination for more eventsif (paging.next) { // Fetch next page using paging.next URL}Обработка на Mailgun уебхуци
const crypto = require('crypto');
app.post('/webhooks/mailgun', async (req, res) => { // Verify webhook signature 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 });
// Handle bounce suppression if (event === 'failed' && eventData.severity === 'permanent') { await tajo.contacts.update(email, { attributes: { MG_BOUNCE_TYPE: 'hard_bounce' }, emailBlacklisted: true }); }
res.status(200).send('OK');});Синхронизация на bounces и complaints
// Sync bounced addresses for list hygieneconst 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/ч (free), неограничено (платено) |
| Events API | Без изричен лимит | Използвай пагинация с макс. 300 артикула |
| Validation API | Според плана | Pay-per-validation |
| Уебхуци | Реално време | Без rate limit при доставка |
| Suppressions API | Без изричен лимит | Прилага се стандартен rate limiting |
Лимити за изпращане
Mailgun налага лимити за изпращане на базата на плана ти и репутацията на домейна. Новите домейни започват с по-ниски лимити, които се увеличават с подобряване на sender репутацията. Мониторирай статистиките на домейна в Mailgun dashboard.
Отстраняване на проблеми
| Проблем | Причина | Решение |
|---|---|---|
| 401 Unauthorized | Невалиден API ключ | Провери API ключа в Mailgun dashboard |
| Домейнът не е верифициран | Липсващи DNS записи | Добави необходимите TXT, CNAME, MX записи |
| Уебхукът не се получава | URL-ът не е достъпен | Увери се, че webhook URL е публично достъпен |
| Липсващи събития | Твърде тесен времеви диапазон | Разшири параметрите begin/end |
| Нисък deliverability | Репутация на домейна | Провери статистиките на домейна и автентикацията |
Режим за дебъг
connectors: mailgun: debug: true log_level: verbose log_webhooks: true log_events: trueДобри практики
- Верифицирай sending домейните – Завърши DNS верификацията за оптимален deliverability
- Използвай уебхуци за събития – Доставка на уебхуци в реално време вместо polling на Events API
- Обработвай bounces проактивно – Незабавно suppress-вай hard bounces в Brevo
- Тагирай своите съобщения – Използвай тагове, за да категоризираш и анализираш performance на имейли
- Мониторирай репутацията на домейна – Проследявай deliverability метриките в Mailgun dashboard
- Използвай имейл валидация – Валидирай адресите преди добавяне в Brevo списъци
Сигурност
- HTTP Basic Auth – API ключът се предава чрез хедъра Authorization
- Подписи на уебхуци – HMAC-SHA256 верификация на подпис
- Верификация на домейна – SPF, DKIM и DMARC DNS автентикация
- IP whitelisting – Достъпно за планове с dedicated IP
- TLS криптиране – Всички API крайни точки изискват HTTPS
- Ротация на ключове – Периодично ротирай API ключовете чрез Mailgun dashboard