Envoyer des e-mails transactionnels depuis Node.js, Python et cURL

Les e-mails transactionnels sont les messages que votre produit envoie parce qu’un utilisateur a fait quelque chose : il s’est inscrit, a réinitialisé son mot de passe, a payé une facture, a été invité dans un espace de travail. Ils doivent partir vite, depuis votre propre domaine, et sans ralentir la requête qui les a déclenchés.

Cet article montre comment les envoyer via l’API REST Inbixio depuis les langages les plus utilisés par les équipes, puis transforme l’appel ponctuel en un petit helper que vous pouvez intégrer à n’importe quelle base de code.

La requête, en un coup d’œil

Tous les exemples ci-dessous envoient la même requête HTTP :

• Méthode et URL : POST https://backend.inbixio.com/api/send-email/, barre oblique finale comprise
• Authentification : un en-tête X-API-Key avec une clé disposant de la permission Send (envoyer)
• Corps : du JSON avec to_email, subject et message (HTML)

Un appel réussi renvoie 200 avec {"message": "Email queued successfully."}. Si vous n’avez pas encore créé de clé ni connecté de serveur SMTP, commencez par le guide de démarrage en cinq minutes.

Dans tous les exemples, la clé est lue depuis une variable d’environnement nommée INBIXIO_API_KEY. Gardez-la côté serveur ; ne l’envoyez jamais dans un navigateur ou une application mobile.

cURL

Pratique pour tester une clé, déboguer depuis un serveur, ou appeler l’API depuis un script shell ou une tâche cron :

curl -sS -X POST https://backend.inbixio.com/api/send-email/ \
  -H "X-API-Key: $INBIXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 15 \
  -d '{
    "to_email": "ada@example.com",
    "subject": "Your invoice is ready",
    "message": "<p>Hi Ada, your invoice for October is ready.</p>"
  }'

-sS masque la barre de progression tout en affichant les erreurs, et --max-time évite qu’un script reste bloqué si le réseau ne répond plus.

Node.js

Node.js 18 et versions ultérieures intègrent fetch : aucune bibliothèque HTTP n’est nécessaire.

// send-email.js
const INBIXIO_URL = 'https://backend.inbixio.com/api/send-email/';

export async function sendEmail({ to, subject, html }) {
  const res = await fetch(INBIXIO_URL, {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.INBIXIO_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ to_email: to, subject, message: html }),
    signal: AbortSignal.timeout(15_000),
  });

  const body = await res.json().catch(() => ({}));
  if (!res.ok) {
    const reason = body.error || body.detail || res.statusText;
    throw new Error(`Inbixio ${res.status}: ${reason}`);
  }
  return body; // { message: 'Email queued successfully.' }
}

Et son utilisation depuis une route Express :

app.post('/signup', async (req, res) => {
  const user = await createUser(req.body);
  await sendEmail({
    to: user.email,
    subject: 'Welcome aboard',
    html: `<h1>Welcome, ${escapeHtml(user.name)}!</h1><p>Your account is ready.</p>`,
  });
  res.status(201).json({ id: user.id });
});

Remarquez escapeHtml. Le champ message est interprété comme du HTML : tout ce qu’un utilisateur a saisi, comme son nom, doit être échappé avant d’être inséré dans le corps.

Python

Avec requests :

# send_email.py
import os
import requests

INBIXIO_URL = "https://backend.inbixio.com/api/send-email/"

class EmailError(Exception):
    pass

def send_email(to: str, subject: str, html: str) -> dict:
    res = requests.post(
        INBIXIO_URL,
        headers={"X-API-Key": os.environ["INBIXIO_API_KEY"]},
        json={"to_email": to, "subject": subject, "message": html},
        timeout=15,
    )
    if not res.ok:
        try:
            body = res.json()
        except ValueError:
            body = {}
        reason = body.get("error") or body.get("detail") or res.reason
        raise EmailError(f"Inbixio {res.status_code}: {reason}")
    return res.json()

Passer json= définit l’en-tête Content-Type à votre place. Définissez toujours un timeout : par défaut, requests attend indéfiniment.

Dans Django, appelez-le une fois la transaction de base de données validée, pour ne jamais envoyer d’e-mail à propos d’une ligne qui a été annulée :

from django.db import transaction

transaction.on_commit(lambda: send_email(user.email, "Welcome!", render_welcome(user)))

PHP

<?php
function send_email(string $to, string $subject, string $html): array {
    $ch = curl_init('https://backend.inbixio.com/api/send-email/');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . getenv('INBIXIO_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'to_email' => $to,
            'subject'  => $subject,
            'message'  => $html,
        ]),
    ]);
    $body = json_decode(curl_exec($ch), true) ?? [];
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($status !== 200) {
        throw new RuntimeException("Inbixio $status: " . ($body['error'] ?? $body['detail'] ?? 'request failed'));
    }
    return $body;
}

Envoyer à plusieurs personnes

Chaque requête est délivrée à un seul to_email. Pour notifier une liste d’utilisateurs, envoyez une requête par destinataire. C’est de toute façon ce que vous voulez pour des e-mails transactionnels : chaque utilisateur reçoit son propre message, personne ne voit l’adresse des autres, et une adresse invalide ne bloque pas le reste.

Limitez la concurrence pour ne pas surcharger votre propre serveur SMTP. Un petit pool de 5 à 10 requêtes en parallèle suffit à la plupart des applications.

N’envoyez pas pendant la requête utilisateur

L’appel à l’API est rapide, mais il reste un aller-retour réseau. Pour tout ce qui n’est pas urgent, placez l’envoi dans une tâche en arrière-plan (BullMQ, Celery, Sidekiq, une file d’attente cloud) afin que :

• la page de l’utilisateur se charge sans attendre l’e-mail,
• une erreur temporaire puisse être relancée sans que l’utilisateur le remarque, et
• un pic soudain, comme un gros import qui déclenche des milliers d’e-mails de bienvenue, s’écoule à un rythme régulier.

Pour les codes OTP et les réinitialisations de mot de passe, les utilisateurs attendent activement : envoyez immédiatement et affichez un message d’erreur clair en cas d’échec. Gérer les erreurs et les limites d’une API e-mail explique quelles erreurs relancer et lesquelles remonter.

Checklist avant la mise en production

• La clé API provient d’une variable d’environnement ou d’un gestionnaire de secrets, et elle ne dispose que de la permission Send.
• Chaque valeur fournie par l’utilisateur dans le HTML est échappée.
• Les requêtes ont un timeout de 10 à 15 secondes.
• Les réponses autres que 200 sont journalisées avec leur corps, pour ne pas perdre les messages error et detail.
• Votre domaine d’envoi a SPF, DKIM et DMARC configurés, pour que les e-mails arrivent en boîte de réception.