Connecteur SendGrid

Connectez votre compte SendGrid à Brevo via Tajo pour la migration d’infrastructure email, la synchronisation des contacts, le transfert de données de campagnes et des analytiques d’engagement unifiées sur les deux plateformes.

Vue d’ensemble

Fonctionnalités

• Migration de contacts - Migration des contacts SendGrid Marketing vers Brevo avec les champs personnalisés
• Synchronisation email transactionnel - Suivi des événements d’emails transactionnels pour un reporting unifié
• Données de campagnes - Synchronisation des données de performance des campagnes Single Send et Automation
• Webhooks d’événements - Transfert des événements email (delivered, opened, clicked, bounced) vers Brevo
• Synchronisation des suppressions - Migration des listes de rebonds, blocages et désinscriptions pour la conformité
• Migration de templates - Export des Dynamic Transactional Templates pour utilisation dans Brevo
• Vérification d’expéditeur - Synchronisation des identités d’expéditeur vérifiées et de l’authentification de domaine
• Synchronisation des statistiques - Import des statistiques d’engagement historiques vers les attributs Brevo

Prérequis

Avant de commencer, assurez-vous d’avoir :

1. Un compte SendGrid (Free, Essentials, Pro ou Premier)
2. Une clé API SendGrid avec les permissions requises
3. Un compte Brevo avec accès API
4. Un compte Tajo

Authentification

Authentification par clé API

SendGrid utilise l’authentification par bearer token.

curl https://api.sendgrid.com/v3/marketing/contacts \
  -H "Authorization: Bearer SG.YOUR_API_KEY" \
  -H "Content-Type: application/json"

Créez les clés API dans SendGrid Settings > API Keys avec des niveaux de permission spécifiques :

• Full Access - Accès API complet
• Restricted Access - Contrôle de permissions granulaire
• Billing Access - Opérations de facturation uniquement

Permissions requises

Marketing: Full Access
  - Contacts (read)
  - Single Sends (read)
  - Automations (read)
Mail Send: Full Access
  - Mail Send (read)
Stats: Read Access
Suppressions: Read Access
Tracking: Read Access

Configuration

Configuration de base

connectors:
  sendgrid:
    enabled: true
    api_key: "${SENDGRID_API_KEY}"

    # Options de synchronisation des données
    sync:
      contacts: true
      campaigns: true
      transactional: true
      suppressions: true
      statistics: true

    # Mappage de listes vers Brevo
    list_mapping:
      "All Contacts": 60
      "Newsletter": 61
      "Transactional": 62

Mappage de champs

Mappez les champs de contact SendGrid aux attributs de contact Brevo :

Mappage de champs personnalisés

field_mapping:
  # Champs standards
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone_number: SMS

  # Champs de localisation
  city: CITY
  state_province_region: STATE
  country: COUNTRY
  postal_code: POSTAL_CODE

  # Métriques d'engagement
  avg_open_rate: AVG_OPEN_RATE
  avg_click_rate: AVG_CLICK_RATE

  # Champs personnalisés
  custom_fields.company: COMPANY_NAME
  custom_fields.plan: PLAN_TYPE

Endpoints API

Marketing Contacts

Email transactionnel (Mail Send)

Campagnes (Single Sends)

Statistiques

Suppressions

Événements

Événements email (via Event Webhook)

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

// Connecter SendGrid
await tajo.connectors.connect('sendgrid', {
  apiKey: process.env.SENDGRID_API_KEY
});

Migrer les contacts vers Brevo

// Migration complète des contacts de SendGrid vers Brevo
await tajo.connectors.sync('sendgrid', {
  type: 'full',
  resources: ['contacts', 'suppressions'],
  options: {
    includeCustomFields: true,
    migrateListMemberships: true,
    migrateSuppressions: true
  }
});

// Vérifier le statut de migration
const status = await tajo.connectors.status('sendgrid');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsMigrated: 45000,
//   suppressionsSynced: 3200,
//   listsMapped: 8
// }

Transférer les événements email

// Gérer l'Event Webhook SendGrid
app.post('/webhooks/sendgrid', async (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');

  // Vérifier la signature du webhook (ECDSA)
  if (!verifySendGridSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  // Traiter le batch d'événements
  for (const event of req.body) {
    await tajo.connectors.handleWebhook('sendgrid', {
      type: event.event,
      email: event.email,
      timestamp: event.timestamp,
      payload: event
    });
  }

  res.status(200).send('OK');
});

Limites de taux

Limites de taux de l’API SendGrid :

Dépannage

Problèmes courants

Mode debug

Activer la journalisation détaillée :

connectors:
  sendgrid:
    debug: true
    log_level: verbose
    log_webhooks: true

Tester la connexion

tajo connectors test sendgrid
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Lists accessible
# ✓ Statistics readable
# ✓ Suppressions accessible

Bonnes pratiques

1. Migrez les suppressions en premier - Assurez-vous que les rebonds, blocages et désinscriptions sont dans Brevo avant d’envoyer
2. Utilisez les téléversements de contacts en batch - PUT jusqu’à 30 000 contacts par requête pour l’efficacité
3. Vérifiez l’Event Webhook - Activez les webhooks signés avec vérification ECDSA
4. Mappez les champs personnalisés - Créez les attributs Brevo correspondants avant la migration des contacts
5. Synchronisez les données d’engagement - Importez les stats historiques pour la segmentation dans Brevo
6. Gérez les exports asynchrones - Les exports de contacts sont asynchrones ; interrogez jusqu’à complétion

Sécurité

• Authentification par clé API - Bearer token avec niveaux de permission granulaires
• Signature de l’Event Webhook - Vérification de signature ECDSA pour les payloads de webhook
• Chiffrement TLS - Toutes les communications API chiffrées via HTTPS
• Gestion d’accès par IP - Restriction de l’accès au Dashboard et à l’API par IP
• Authentification à deux facteurs - 2FA disponible pour l’accès au compte

Ressources liées

• Documentation API SendGrid
• Guide Event Webhook SendGrid
• Connecteur Brevo
• Connecteur Mailchimp
• Compétence de synchronisation client