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

VlastnostHodnota
PlatformaMailgun (od Sinch)
KategorieE-mailový marketing
Složitost nastaveníSnadná
Oficiální integraceNe
Synchronizovaná dataUdá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:

  1. Účet Mailgun s ověřenou odesílající doménou
  2. API klíč Mailgun z Řídicího panelu Mailgun
  3. Účet Brevo s přístupem k API
  4. Úč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:

Terminal window
# Získejte API klíč na 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
// Formát HTTP Basic Auth
const 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: 32

Mapová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_UNSUBSCRIBED

Koncové body API

Koncový bodMetodaPopis
https://api.mailgun.net/v3/{domain}/messagesPOSTOdeslání e-mailových zpráv
https://api.mailgun.net/v3/{domain}/eventsGETDotaz na protokoly událostí
https://api.mailgun.net/v3/{domain}/bouncesGETVýpis odrazů
https://api.mailgun.net/v3/{domain}/complaintsGETVýpis stížností
https://api.mailgun.net/v3/{domain}/unsubscribesGETVýpis odhlášení
https://api.mailgun.net/v3/{domain}/tagsGETVýpis štítků
https://api.mailgun.net/v3/{domain}/tags/{tag}/statsGETStatistiky štítku
https://api.mailgun.net/v3/listsGETVýpis poštovních seznamů
https://api.mailgun.net/v3/domainsGETVýpis domén
https://api.mailgun.net/v4/address/validatePOSTOvěř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 Mailgun
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.' }

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 seznamu
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')
});
}

Omezení rychlosti

Koncový bodLimitPoznámky
Messages APIZávisí na plánu100/hod (zdarma), neomezeno (placené)
Events APIŽádný explicitní limitPoužívejte stránkování s max. 300 položkami
Validation APINa základě plánuPlatba za ověření
WebhookyReálný časŽádný limit rychlosti při doručení
Suppressions APIŽádný explicitní limitPlatí 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émPříčinaŘešení
401 UnauthorizedNeplatný API klíčOvěřte API klíč v řídicím panelu Mailgun
Doména není ověřenaChybějící DNS záznamyPřidejte požadované TXT, CNAME, MX záznamy
Webhook nebyl přijatURL není přístupnáUjistěte se, že URL webhooku je veřejně dostupná
Chybějící událostiPříliš úzký časový rozsahRozšiřte parametry begin/end
Nízká doručitelnostReputace doményZkontrolujte statistiky domény a ověřování

Režim ladění

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

Osvědčené postupy

  1. Ověřte odesílající domény – Dokončete DNS ověřování pro optimální doručitelnost
  2. Používejte webhooky pro události – Doručení webhooků v reálném čase vs. pollování Events API
  3. Proaktivně zpracovávejte odrazy – Okamžitě potlačujte tvrdé odrazy v Brevo
  4. Tagujte zprávy – Používejte štítky pro kategorizaci a analýzu výkonu e-mailů
  5. Monitorujte reputaci domény – Sledujte metriky doručitelnosti v řídicím panelu Mailgun
  6. 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

Související zdroje

Subscribe to updates

developer-docs

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

auto-detect
AI asistent

Ahoj! Zeptejte se mě na dokumentaci.