Connecteur Mailgun

Connectez Mailgun à Brevo via Tajo pour unifier vos données d’emails transactionnels et marketing, synchroniser les événements de livraison et les métriques d’engagement, et consolider votre infrastructure email dans une vue client unique.

Vue d’ensemble

PropriétéValeur
PlateformeMailgun (par Sinch)
CatégorieEmail Marketing
Complexité de configurationFacile
Intégration officielleNon
Données synchroniséesÉvénements, Contacts, Délivrabilité, Campagnes
Méthode d’authentificationClé API (HTTP Basic Auth)

Fonctionnalités

  • Synchronisation des événements de livraison - Suivi des événements delivered, bounced, opened et clicked
  • Métriques d’engagement - Synchronisation des taux d’ouverture et de clic vers les attributs de contact Brevo
  • Gestion des rebonds - Suppression automatique des adresses rejetées dans Brevo
  • Gestion des plaintes - Synchronisation des plaintes spam pour l’hygiène de liste
  • Réputation de domaine - Surveillance de la santé du domaine d’envoi et de la délivrabilité
  • Suivi des emails transactionnels - Corrélation des envois transactionnels avec les données marketing

Prérequis

Avant de commencer, assurez-vous d’avoir :

  1. Un compte Mailgun avec un domaine d’envoi vérifié
  2. Une clé API Mailgun depuis le Mailgun Dashboard
  3. Un compte Brevo avec accès API
  4. Un compte Tajo avec permissions de connecteur

Authentification

Authentification par clé API

Mailgun utilise l’authentification HTTP Basic avec api comme nom d’utilisateur et votre clé API comme mot de passe :

Terminal window
# Obtenez votre clé API sur 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
// Format HTTP Basic Auth
const headers = {
'Authorization': `Basic ${Buffer.from(
`api:${process.env.MAILGUN_API_KEY}`
).toString('base64')}`
};
// Ou en utilisant curl
// curl -s --user 'api:YOUR_API_KEY' ...

Types de clés API

Mailgun fournit des clés d’envoi spécifiques au domaine et des clés API de niveau compte. Utilisez les clés d’envoi de domaine pour les opérations de messagerie et la clé API de compte pour les opérations de gestion.

Configuration

Configuration de base

connectors:
mailgun:
enabled: true
api_key: "${MAILGUN_API_KEY}"
domain: "${MAILGUN_DOMAIN}"
region: "us" # ou "eu" pour la région UE
sync:
events: true
contacts: true
bounces: true
complaints: true
schedule: "*/15 * * * *" # Toutes les 15 minutes
webhook:
signing_key: "${MAILGUN_WEBHOOK_SIGNING_KEY}"
lists:
engaged: 30
bounced: 31
complained: 32

Mappage de champs

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

Endpoints API

EndpointMéthodeDescription
https://api.mailgun.net/v3/{domain}/messagesPOSTEnvoyer des messages email
https://api.mailgun.net/v3/{domain}/eventsGETInterroger les logs d’événements
https://api.mailgun.net/v3/{domain}/bouncesGETLister les rebonds
https://api.mailgun.net/v3/{domain}/complaintsGETLister les plaintes
https://api.mailgun.net/v3/{domain}/unsubscribesGETLister les désinscriptions
https://api.mailgun.net/v3/{domain}/tagsGETLister les tags
https://api.mailgun.net/v3/{domain}/tags/{tag}/statsGETObtenir les statistiques d’un tag
https://api.mailgun.net/v3/listsGETLister les mailing lists
https://api.mailgun.net/v3/domainsGETLister les domaines
https://api.mailgun.net/v4/address/validatePOSTValider une adresse email

Région UE

Pour les comptes Mailgun basés dans l’UE, utilisez https://api.eu.mailgun.net au lieu de https://api.mailgun.net pour tous les endpoints API.

Exemples de code

Initialiser le connecteur

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

Envoyer un message via l’API Mailgun

// Envoyer un email en utilisant l'API Messages de 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.' }

Synchroniser les événements email vers Brevo

// Interroger les événements Mailgun et synchroniser les données d'engagement
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;
}
}
// Suivre la pagination pour plus d'événements
if (paging.next) {
// Récupérer la page suivante en utilisant l'URL paging.next
}

Gérer les webhooks Mailgun

const crypto = require('crypto');
app.post('/webhooks/mailgun', async (req, res) => {
// Vérifier la signature du webhook
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
});
// Gérer la suppression des rebonds
if (event === 'failed' && eventData.severity === 'permanent') {
await tajo.contacts.update(email, {
attributes: { MG_BOUNCE_TYPE: 'hard_bounce' },
emailBlacklisted: true
});
}
res.status(200).send('OK');
});

Synchroniser les rebonds et plaintes

// Synchroniser les adresses rejetées pour l'hygiène de liste
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')
});
}

Limites de taux

EndpointLimiteNotes
API MessagesVarie selon le plan100/h (gratuit), illimité (payant)
API EventsPas de limite expliciteUtilisez la pagination avec 300 éléments max
API ValidationBasée sur le planPaiement par validation
WebhooksTemps réelPas de limite de taux à la livraison
API SuppressionsPas de limite expliciteLimite de taux standard s’applique

Limites d'envoi

Mailgun applique des limites d’envoi basées sur votre plan et la réputation de votre domaine. Les nouveaux domaines commencent avec des limites plus basses qui augmentent à mesure que votre réputation d’expéditeur s’améliore. Surveillez les statistiques de votre domaine dans le tableau de bord Mailgun.

Dépannage

ProblèmeCauseSolution
401 UnauthorizedClé API invalideVérifiez la clé API dans le tableau de bord Mailgun
Domaine non vérifiéEnregistrements DNS manquantsAjoutez les enregistrements TXT, CNAME, MX requis
Webhook non reçuURL non accessibleAssurez-vous que l’URL du webhook est accessible publiquement
Événements manquantsPlage de temps trop étroiteÉlargissez les paramètres begin/end
Faible délivrabilitéRéputation de domaineVérifiez les stats du domaine et l’authentification

Mode debug

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

Bonnes pratiques

  1. Vérifiez les domaines d’envoi - Complétez la vérification DNS pour une délivrabilité optimale
  2. Utilisez les webhooks pour les événements - Livraison webhook en temps réel vs polling de l’API Events
  3. Gérez les rebonds de manière proactive - Supprimez immédiatement les hard bounces dans Brevo
  4. Taguez vos messages - Utilisez les tags pour catégoriser et analyser la performance email
  5. Surveillez la réputation du domaine - Suivez les métriques de délivrabilité dans le tableau de bord Mailgun
  6. Utilisez la validation d’email - Validez les adresses avant de les ajouter aux listes Brevo

Sécurité

  • HTTP Basic Auth - Clé API transmise via l’en-tête Authorization
  • Signatures webhook - Vérification de signature HMAC-SHA256
  • Vérification de domaine - Authentification DNS SPF, DKIM et DMARC
  • Liste blanche d’IP - Disponible pour les plans avec IP dédiée
  • Chiffrement TLS - Tous les endpoints API nécessitent HTTPS
  • Rotation des clés - Faites tourner les clés API périodiquement via le tableau de bord Mailgun

Ressources liées

Subscribe to updates

developer-docs

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

auto-detect
Assistant AI

Bonjour ! Posez-moi vos questions sur la documentation.