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 |
|---|---|
| Plateforme | Mailgun (par Sinch) |
| Catégorie | Email Marketing |
| Complexité de configuration | Facile |
| Intégration officielle | Non |
| Données synchronisées | Événements, Contacts, Délivrabilité, Campagnes |
| Méthode d’authentification | Clé 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 :
- Un compte Mailgun avec un domaine d’envoi vérifié
- Une clé API Mailgun depuis le Mailgun Dashboard
- Un compte Brevo avec accès API
- 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 :
# Obtenez votre clé API sur 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// Format HTTP Basic Authconst 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: 32Mappage 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_UNSUBSCRIBEDEndpoints API
| Endpoint | Méthode | Description |
|---|---|---|
https://api.mailgun.net/v3/{domain}/messages | POST | Envoyer des messages email |
https://api.mailgun.net/v3/{domain}/events | GET | Interroger les logs d’événements |
https://api.mailgun.net/v3/{domain}/bounces | GET | Lister les rebonds |
https://api.mailgun.net/v3/{domain}/complaints | GET | Lister les plaintes |
https://api.mailgun.net/v3/{domain}/unsubscribes | GET | Lister les désinscriptions |
https://api.mailgun.net/v3/{domain}/tags | GET | Lister les tags |
https://api.mailgun.net/v3/{domain}/tags/{tag}/stats | GET | Obtenir les statistiques d’un tag |
https://api.mailgun.net/v3/lists | GET | Lister les mailing lists |
https://api.mailgun.net/v3/domains | GET | Lister les domaines |
https://api.mailgun.net/v4/address/validate | POST | Valider 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 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.' }Synchroniser les événements email vers Brevo
// Interroger les événements Mailgun et synchroniser les données d'engagementconst 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énementsif (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 listeconst 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
| Endpoint | Limite | Notes |
|---|---|---|
| API Messages | Varie selon le plan | 100/h (gratuit), illimité (payant) |
| API Events | Pas de limite explicite | Utilisez la pagination avec 300 éléments max |
| API Validation | Basée sur le plan | Paiement par validation |
| Webhooks | Temps réel | Pas de limite de taux à la livraison |
| API Suppressions | Pas de limite explicite | Limite 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ème | Cause | Solution |
|---|---|---|
| 401 Unauthorized | Clé API invalide | Vérifiez la clé API dans le tableau de bord Mailgun |
| Domaine non vérifié | Enregistrements DNS manquants | Ajoutez les enregistrements TXT, CNAME, MX requis |
| Webhook non reçu | URL non accessible | Assurez-vous que l’URL du webhook est accessible publiquement |
| Événements manquants | Plage de temps trop étroite | Élargissez les paramètres begin/end |
| Faible délivrabilité | Réputation de domaine | Vérifiez les stats du domaine et l’authentification |
Mode debug
connectors: mailgun: debug: true log_level: verbose log_webhooks: true log_events: trueBonnes pratiques
- Vérifiez les domaines d’envoi - Complétez la vérification DNS pour une délivrabilité optimale
- Utilisez les webhooks pour les événements - Livraison webhook en temps réel vs polling de l’API Events
- Gérez les rebonds de manière proactive - Supprimez immédiatement les hard bounces dans Brevo
- Taguez vos messages - Utilisez les tags pour catégoriser et analyser la performance email
- Surveillez la réputation du domaine - Suivez les métriques de délivrabilité dans le tableau de bord Mailgun
- 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