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
  • Проследяване на транзакционни имейли – Корелирай транзакционните изпращания с маркетингови данни

Предварителни условия

Преди да започнеш, увери се, че имаш:

  1. Акаунт в Mailgun с верифициран sending домейн
  2. Mailgun API ключ от Mailgun Dashboard
  3. Акаунт в Brevo с API достъп
  4. Акаунт в Tajo с разрешения за конектори

Автентикация

Автентикация с API ключ

Mailgun използва HTTP Basic Authentication с api като username и твоя API ключ като парола:

Terminal window
# 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
// 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 предоставя 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_UNSUBSCRIBED

API крайни точки

Крайна точкаМетодОписание
https://api.mailgun.net/v3/{domain}/messagesPOSTИзпращане на имейл съобщения
https://api.mailgun.net/v3/{domain}/eventsGETЗаявка на логове със събития
https://api.mailgun.net/v3/{domain}/bouncesGETСписък с bounces
https://api.mailgun.net/v3/{domain}/complaintsGETСписък с complaints
https://api.mailgun.net/v3/{domain}/unsubscribesGETСписък с unsubscribes
https://api.mailgun.net/v3/{domain}/tagsGETСписък с тагове
https://api.mailgun.net/v3/{domain}/tags/{tag}/statsGETПолучаване на статистики за таг
https://api.mailgun.net/v3/listsGETСписък с mailing списъци
https://api.mailgun.net/v3/domainsGETСписък с домейни
https://api.mailgun.net/v4/address/validatePOSTВалидиране на имейл адрес

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 API
const formData = new URLSearchParams();
formData.append('from', `Your App <noreply@${domain}>`);
formData.append('to', '[email protected]');
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 data
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;
}
}
// Follow pagination for more events
if (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 hygiene
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/ч (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

Добри практики

  1. Верифицирай sending домейните – Завърши DNS верификацията за оптимален deliverability
  2. Използвай уебхуци за събития – Доставка на уебхуци в реално време вместо polling на Events API
  3. Обработвай bounces проактивно – Незабавно suppress-вай hard bounces в Brevo
  4. Тагирай своите съобщения – Използвай тагове, за да категоризираш и анализираш performance на имейли
  5. Мониторирай репутацията на домейна – Проследявай deliverability метриките в Mailgun dashboard
  6. Използвай имейл валидация – Валидирай адресите преди добавяне в Brevo списъци

Сигурност

  • HTTP Basic Auth – API ключът се предава чрез хедъра Authorization
  • Подписи на уебхуци – HMAC-SHA256 верификация на подпис
  • Верификация на домейна – SPF, DKIM и DMARC DNS автентикация
  • IP whitelisting – Достъпно за планове с dedicated IP
  • TLS криптиране – Всички API крайни точки изискват HTTPS
  • Ротация на ключове – Периодично ротирай API ключовете чрез Mailgun dashboard

Свързани ресурси

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI асистент

Здравейте! Попитайте ме за документацията.