Brevo : Guide Complet de l'API Marketing pour Développeurs

Brevo (anciennement Sendinblue) est une plateforme de marketing automation et d'email marketing qui offre une API puissante pour gérer vos campagnes, contacts et communications. Si vous cherchez à intégrer l'email marketing dans votre application, Brevo est une solution robuste et flexible. Ce guide vous expliquera comment utiliser l'API Brevo comme un pro.

Qu'est-ce que Brevo ?

Brevo est une plateforme tout-en-un qui combine :

Email Marketing : campagnes et newsletters
Marketing Automation : workflows automatisés
CRM : gestion des contacts
SMS Marketing : communications par SMS
Chat en Direct : support client
API REST : intégration programmatique

Pour un développeur, l'intérêt principal réside dans l'API REST v3, qui permet de :

Créer et gérer des contacts
Envoyer des emails transactionnels
Déclencher des workflows d'automatisation
Tracker des événements
Gérer des listes de contacts

Configuration Initiale : Obtenir vos Credentials

Avant de commencer à coder, vous devez :

Créer un compte Brevo : Allez sur brevo.com
Générer une clé API : Accédez à Settings → SMTP & API → Clés API
Copier votre API Key : Vous en aurez besoin pour tous les appels

# Stockez votre clé API en variable d'environnement (ne la commitez jamais !)
export BREVO_API_KEY="votre_cle_api_ici"

Exemple Simple 1 : Envoyer un Email Transactionnel

Commençons par l'utilisation la plus basique : envoyer un email.

Avec Node.js/JavaScript

const axios = require('axios');

const sendEmail = async (to, subject, htmlContent) => {
  const apiKey = process.env.BREVO_API_KEY;
  
  try {
    const response = await axios.post(
      'https://api.brevo.com/v3/smtp/email',
      {
        to: [{ email: to }],
        sender: { name: 'Mon App', email: 'noreply@monapp.com' },
        subject: subject,
        htmlContent: htmlContent
      },
      {
        headers: {
          'api-key': apiKey,
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Email envoyé avec succès:', response.data.messageId);
    return response.data.messageId;
  } catch (error) {
    console.error('Erreur lors de l\'envoi:', error.response?.data);
    throw error;
  }
};

// Utilisation
sendEmail(
  'user@example.com',
  'Bienvenue sur notre plateforme !',
  '<h1>Bienvenue!</h1><p>Merci de vous être inscrit.</p>'
);

Avec Python

import requests
import os

def send_email(to_email, subject, html_content):
    api_key = os.getenv('BREVO_API_KEY')
    
    payload = {
        'to': [{'email': to_email}],
        'sender': {'name': 'Mon App', 'email': 'noreply@monapp.com'},
        'subject': subject,
        'htmlContent': html_content
    }
    
    headers = {
        'api-key': api_key,
        'Content-Type': 'application/json'
    }
    
    response = requests.post(
        'https://api.brevo.com/v3/smtp/email',
        json=payload,
        headers=headers
    )
    
    if response.status_code == 201:
        print(f"Email envoyé: {response.json()['messageId']}")
        return response.json()['messageId']
    else:
        print(f"Erreur: {response.json()}")
        raise Exception(response.text)

# Utilisation
send_email(
    'user@example.com',
    'Bienvenue!',
    '<h1>Bienvenue!</h1>'
)

Avec cURL

curl --request POST \
  --url https://api.brevo.com/v3/smtp/email \
  --header "api-key: $BREVO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": [{"email": "user@example.com"}],
    "sender": {"name": "Mon App", "email": "noreply@monapp.com"},
    "subject": "Bienvenue!",
    "htmlContent": "<h1>Bienvenue!</h1>"
  }'

Exemple 2 : Gérer les Contacts

La gestion des contacts est essentielle pour le marketing automation.

// Créer ou mettre à jour un contact
const upsertContact = async (email, attributes) => {
  const apiKey = process.env.BREVO_API_KEY;
  
  try {
    const response = await axios.post(
      'https://api.brevo.com/v3/contacts',
      {
        email: email,
        attributes: attributes,
        updateEnabled: true // Met à jour si existe déjà
      },
      {
        headers: { 'api-key': apiKey }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Erreur:', error.response?.data);
    throw error;
  }
};

// Utilisation
upsertContact('john@example.com', {
  FIRSTNAME: 'John',
  LASTNAME: 'Doe',
  PHONE: '+33612345678',
  COMPANY: 'Tech Corp',
  CUSTOM_FIELD: 'Valeur personnalisée'
});

Exemple 3 : Ajouter un Contact à une Liste

Pour segmenter votre audience :

const addContactToList = async (listId, email) => {
  const apiKey = process.env.BREVO_API_KEY;
  
  const response = await axios.post(
    `https://api.brevo.com/v3/contacts/lists/${listId}/contacts/add`,
    {
      emails: [email]
    },
    {
      headers: { 'api-key': apiKey }
    }
  );
  
  return response.data;
};

// Utilisation - Ajouter à la liste "Premium Users" (ID: 42)
addContactToList(42, 'john@example.com');

Cas Avancé 1 : Workflow d'Automatisation au Inscription

Déclenchez automatiquement un workflow quand un utilisateur s'inscrit :

const triggerWorkflow = async (workflowId, email, attributes = {}) => {
  const apiKey = process.env.BREVO_API_KEY;
  
  const response = await axios.post(
    `https://api.brevo.com/v3/automations/workflows/${workflowId}/trigger`,
    {
      email: email,
      attributes: attributes
    },
    {
      headers: { 'api-key': apiKey }
    }
  );
  
  return response.data;
};

// Déclencher le workflow "Onboarding" au signup
app.post('/signup', async (req, res) => {
  const { email, name } = req.body;
  
  // Créer le contact
  await upsertContact(email, { FIRSTNAME: name });
  
  // Déclencher le workflow
  await triggerWorkflow(123, email, { SIGNUP_DATE: new Date() });
  
  res.json({ success: true });
});

Cas Avancé 2 : Envoyer des Emails en Masse Efficacement

Pour envoyer à plusieurs destinataires sans surcharger l'API :

const sendBulkEmails = async (recipients, subject, htmlContent) => {
  const apiKey = process.env.BREVO_API_KEY;
  
  // Brevo supporte jusqu'à 150 destinataires par appel
  const chunkSize = 150;
  
  for (let i = 0; i < recipients.length; i += chunkSize) {
    const batch = recipients.slice(i, i + chunkSize).map(email => ({
      email: email
    }));
    
    try {
      await axios.post(
        'https://api.brevo.com/v3/smtp/email',
        {
          to: batch,
          sender: { name: 'Mon App', email: 'noreply@monapp.com' },
          subject: subject,
          htmlContent: htmlContent
        },
        {
          headers: { 'api-key': apiKey }
        }
      );
      
      console.log(`Batch ${Math.floor(i / chunkSize) + 1} envoyé`);
    } catch (error) {
      console.error(`Erreur batch ${Math.floor(i / chunkSize) + 1}:`, error.message);
    }
    
    // Respecter les rate limits (attendre entre les batches)
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
};

// Utilisation
const emails = ['user1@example.com', 'user2@example.com', /* ... */];
sendBulkEmails(emails, 'Nouvelle promotion!', '<h1>50% de réduction!</h1>');

Cas Avancé 3 : Tracker les Événements pour l'Automatisation

Déclenchez des actions en fonction du comportement utilisateur :

const trackEvent = async (email, eventName, properties = {}) => {
  const apiKey = process.env.BREVO_API_KEY;
  
  const response = await axios.post(
    'https://api.brevo.com/v3/crm/events',
    {
      email: email,
      event: eventName,
      properties: properties,
      eventTime: new Date().toISOString()
    },
    {
      headers: { 'api-key': apiKey }
    }
  );
  
  return response.data;
};

// Exemples d'utilisation
trackEvent('john@example.com', 'purchase', {
  product: 'Premium Plan',
  price: 99.99,
  currency: 'EUR'
});

trackEvent('john@example.com', 'page_visit', {
  page: '/pricing',
  source: 'organic'
});

Pièges Courants et Solutions

1. Rate Limiting

Brevo applique des limites de débit. Respectez-les :

// ❌ MAUVAIS : appels simultanés illimités
recipients.forEach(email => sendEmail(email, subject, html));

// ✅ BON : utiliser une queue avec délai
const queue = [];
for (const email of recipients) {
  await delay(100); // 100ms entre les appels
  queue.push(sendEmail(email, subject, html));
}
await Promise.all(queue);

2. Gestion des Erreurs

Ne pas capturer les erreurs correctement :

// ❌ MAUVAIS
sendEmail(email, subject, html);

// ✅ BON
try {
  await sendEmail(email, subject, html);
} catch (error) {
  if (error.response?.status === 429) {
    console.log('Rate limited, réessayer plus tard');
  } else if (error.response?.status === 400) {
    console.log('Email invalide:', error.response.data.message);
  } else {
    console.error('Erreur inconnue:', error.message);
  }
}

3. Sécurité de la Clé API

// ❌ MAUVAIS : hardcoder la clé
const apiKey = 'sk_live_xxxxx';

// ✅ BON : utiliser des variables d'environnement
const apiKey = process.env.BREVO_API_KEY;

// ✅ MEILLEUR : utiliser un gestionnaire de secrets
const apiKey = await secretsManager.getSecret('brevo-api-key');

Ressources Complémentaires

Documentation Officielle : https://developers.brevo.com
API Reference : https://api.brevo.com/v3/swagger.json
Postman Collection : Importable depuis la documentation
Limites de l'API : 300 appels/minute

Conclusion

Brevo offre une API flexible et bien documentée pour intégrer l'email marketing dans vos applications. Commencez simple avec l'envoi d'emails, puis progressez vers des workflows d'automatisation sophistiqués. L'essentiel est de respecter les limites de l'API, gérer proprement les erreurs et sécuriser votre clé API.

Que vous construisiez un SaaS, un e-commerce ou une plateforme d'engagement client, Brevo peut devenir votre partenaire fiable pour la communication par email.