Konektor Mailgun
Propojte Mailgun s Brevo přes Tajo pro sjednocení transakčních a marketingových e-mailových dat, synchronizaci událostí doručení a metrik zapojení a konsolidaci vaší e-mailové infrastruktury do jednotného pohledu na zákazníka.
Přehled
| Vlastnost | Hodnota |
|---|---|
| Platforma | Mailgun (od Sinch) |
| Kategorie | E-mailový marketing |
| Složitost nastavení | Snadná |
| Oficiální integrace | Ne |
| Synchronizovaná data | Události, Kontakty, Doručitelnost, Kampaně |
| Metoda ověření | API klíč (HTTP Basic Auth) |
Funkce
- Synchronizace událostí doručení – Sledujte události doručení, odrazu, otevření a kliknutí
- Metriky zapojení – Synchronizujte míry otevření a prokliku na atributy kontaktů Brevo
- Správa odrazů – Automaticky potlačujte odražené adresy v Brevo
- Zpracování stížností – Synchronizujte stížnosti na spam pro hygienu seznamu
- Reputace domény – Monitorujte stav odesílající domény a doručitelnost
- Sledování transakčních e-mailů – Korelujte transakční odesílání s marketingovými daty
Předpoklady
Než začnete, ujistěte se, že máte:
- Účet Mailgun s ověřenou odesílající doménou
- API klíč Mailgun z Řídicího panelu Mailgun
- Účet Brevo s přístupem k API
- Účet Tajo s oprávněními ke konektoru
Ověření
Ověření API klíčem
Mailgun používá HTTP Basic Authentication s api jako uživatelským jménem a vaším API klíčem jako heslem:
# Získejte API klíč na 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// Formát HTTP Basic Authconst headers = { 'Authorization': `Basic ${Buffer.from( `api:${process.env.MAILGUN_API_KEY}` ).toString('base64')}`};
// Nebo pomocí curl// curl -s --user 'api:YOUR_API_KEY' ...Typy API klíčů
Mailgun poskytuje klíče pro odesílání specifické pro doménu a API klíče na úrovni účtu. Používejte klíče pro odesílání domény pro operace se zprávami a API klíč účtu pro správcovské operace.
Konfigurace
Základní nastavení
connectors: mailgun: enabled: true api_key: "${MAILGUN_API_KEY}" domain: "${MAILGUN_DOMAIN}" region: "us" # nebo "eu" pro region EU
sync: events: true contacts: true bounces: true complaints: true schedule: "*/15 * * * *" # Každých 15 minut
webhook: signing_key: "${MAILGUN_WEBHOOK_SIGNING_KEY}"
lists: engaged: 30 bounced: 31 complained: 32Mapování polí
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_UNSUBSCRIBEDKoncové body API
| Koncový bod | Metoda | Popis |
|---|---|---|
https://api.mailgun.net/v3/{domain}/messages | POST | Odeslání e-mailových zpráv |
https://api.mailgun.net/v3/{domain}/events | GET | Dotaz na protokoly událostí |
https://api.mailgun.net/v3/{domain}/bounces | GET | Výpis odrazů |
https://api.mailgun.net/v3/{domain}/complaints | GET | Výpis stížností |
https://api.mailgun.net/v3/{domain}/unsubscribes | GET | Výpis odhlášení |
https://api.mailgun.net/v3/{domain}/tags | GET | Výpis štítků |
https://api.mailgun.net/v3/{domain}/tags/{tag}/stats | GET | Statistiky štítku |
https://api.mailgun.net/v3/lists | GET | Výpis poštovních seznamů |
https://api.mailgun.net/v3/domains | GET | Výpis domén |
https://api.mailgun.net/v4/address/validate | POST | Ověření e-mailové adresy |
Region EU
Pro účty Mailgun v EU používejte https://api.eu.mailgun.net místo https://api.mailgun.net pro všechny API koncové body.
Příklady kódu
Inicializace konektoru
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'});Odeslání zprávy přes Mailgun API
// Odeslání e-mailu pomocí Messages API Mailgunconst 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.' }Synchronizace e-mailových událostí do Brevo
// Dotaz na události Mailgun a synchronizace dat zapojení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; }}
// Pokračujte ve stránkování pro více událostíif (paging.next) { // Načtěte další stránku pomocí URL paging.next}Zpracování webhooků Mailgun
const crypto = require('crypto');
app.post('/webhooks/mailgun', async (req, res) => { // Ověření podpisu webhooku 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 });
// Zpracování potlačení odrazů if (event === 'failed' && eventData.severity === 'permanent') { await tajo.contacts.update(email, { attributes: { MG_BOUNCE_TYPE: 'hard_bounce' }, emailBlacklisted: true }); }
res.status(200).send('OK');});Synchronizace odrazů a stížností
// Synchronizace odražených adres pro hygienu seznamuconst 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') });}Omezení rychlosti
| Koncový bod | Limit | Poznámky |
|---|---|---|
| Messages API | Závisí na plánu | 100/hod (zdarma), neomezeno (placené) |
| Events API | Žádný explicitní limit | Používejte stránkování s max. 300 položkami |
| Validation API | Na základě plánu | Platba za ověření |
| Webhooky | Reálný čas | Žádný limit rychlosti při doručení |
| Suppressions API | Žádný explicitní limit | Platí standardní omezení rychlosti |
Limity odesílání
Mailgun vynucuje limity odesílání na základě vašeho plánu a reputace domény. Nové domény začínají s nižšími limity, které se zvyšují s růstem vaší reputace odesílatele. Monitorujte statistiky domény v řídicím panelu Mailgun.
Řešení problémů
| Problém | Příčina | Řešení |
|---|---|---|
| 401 Unauthorized | Neplatný API klíč | Ověřte API klíč v řídicím panelu Mailgun |
| Doména není ověřena | Chybějící DNS záznamy | Přidejte požadované TXT, CNAME, MX záznamy |
| Webhook nebyl přijat | URL není přístupná | Ujistěte se, že URL webhooku je veřejně dostupná |
| Chybějící události | Příliš úzký časový rozsah | Rozšiřte parametry begin/end |
| Nízká doručitelnost | Reputace domény | Zkontrolujte statistiky domény a ověřování |
Režim ladění
connectors: mailgun: debug: true log_level: verbose log_webhooks: true log_events: trueOsvědčené postupy
- Ověřte odesílající domény – Dokončete DNS ověřování pro optimální doručitelnost
- Používejte webhooky pro události – Doručení webhooků v reálném čase vs. pollování Events API
- Proaktivně zpracovávejte odrazy – Okamžitě potlačujte tvrdé odrazy v Brevo
- Tagujte zprávy – Používejte štítky pro kategorizaci a analýzu výkonu e-mailů
- Monitorujte reputaci domény – Sledujte metriky doručitelnosti v řídicím panelu Mailgun
- Používejte ověřování e-mailů – Ověřujte adresy před přidáním do seznamů Brevo
Zabezpečení
- HTTP Basic Auth – API klíč přenášen přes autorizační hlavičku
- Podpisy webhooků – Ověření podpisu HMAC-SHA256
- Ověřování domén – DNS ověřování SPF, DKIM a DMARC
- Whitelisting IP – Dostupné pro plány s vyhrazenou IP
- Šifrování TLS – Všechny API koncové body vyžadují HTTPS
- Rotace klíčů – Pravidelně rotujte API klíče přes řídicí panel Mailgun