Aller au contenu

API d'email transactionnel

Votre produit a ses propres emails : un rapport est prêt, un import a échoué, un statut a changé. Envoyez-les par Canopus depuis votre domaine, sur un flux dont la réputation ne se mélange jamais à vos campagnes, et retirez l'outil d'email que vous payiez à côté pour ça.

De zéro au premier email

Quatre étapes, dont trois sont déjà faites si vos campagnes partent.

  1. Vérifiez votre domaine d'envoi

    Réglages, puis Domaine d'envoi : ajoutez votre domaine, publiez les enregistrements affichés, attendez « Vérifié ». Vos campagnes l'utilisent déjà.

  2. Activez le flux transactionnel

    Sur le même écran, activez le flux. Il reçoit son propre sous-domaine (tx.votredomaine.com) avec quelques enregistrements de plus, pour que sa réputation vive à part, puis réglez son nom et son adresse d'expédition.

  3. Créez une clé d'API

    Réglages, puis API : créez une clé et copiez-la immédiatement ; elle se montre une fois et se stocke hachée. Rangez-la dans l’environnement de votre serveur, jamais dans du code client.

  4. Envoyez le premier email

    Le curl ci-dessous, avec votre clé. La réponse porte un id ; faites un GET dessus pour regarder la délivrance arriver.

Authentification

Chaque requête porte votre clé en bearer token. Une clé appartient à un projet, commence par cnp_live_, et se révoque à tout moment depuis l'écran API ; une clé révoquée répond 401 à sa requête suivante.

Les trois échecs (absente, malformée, révoquée) répondent le même 401, exprès : la réponse ne doit aider personne à deviner quelles clés existent.

Authorization: Bearer cnp_live_...

POST /api/v1/emails

Envoie un email, de façon synchrone : le 202 revient quand notre infrastructure a accepté le message, avec l'id que vous interrogerez. Un destinataire par appel, 256 Ko par corps.

Le From est l'expéditeur transactionnel configuré, sur votre sous-domaine tx. Il ne se choisit pas par requête : cette adresse est ce qui garde la réputation du flux à part, et c'est de la configuration, pas de la charge utile.

to *
Une adresse destinataire.
subject *
Jusqu’à 300 caractères.
html
Le corps HTML. Au moins un de html et text est requis.
text
Le corps texte. Envoyer les deux sert la délivrabilité.
replyTo
Où vont les réponses, si ce n’est pas l’expéditeur.
headers
En-têtes additionnels. Seuls les noms x-* sont gardés ; le reste est à nous.
idempotencyKey
Bouclier de rejeu ; l’en-tête Idempotency-Key prime quand les deux sont donnés.
curl -X POST https://www.canopushq.io/api/v1/emails \
  -H "Authorization: Bearer $CANOPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-2026-10-04-42" \
  -d '{
    "to": "ada@customer.example",
    "subject": "Your weekly report",
    "html": "<p>Twelve new signups this week.</p>",
    "text": "Twelve new signups this week."
  }'
{
  "id": "0192f3a1-7c2e-7b1a-9f44-3d2a8c1b6e90",
  "status": "sent",
  "to": "ada@customer.example",
  "createdAt": "2026-10-04T09:30:12.000Z"
}

GET /api/v1/emails/{id}

Où en est un envoi. Le statut démarre à sent, puis passe à delivered, bounced ou complained à mesure que le fournisseur de boîtes répond, en général en quelques secondes. Un rebond ou une plainte porte un objet detail avec la raison du fournisseur.

{
  "id": "0192f3a1-7c2e-7b1a-9f44-3d2a8c1b6e90",
  "status": "delivered",
  "to": "ada@customer.example",
  "subject": "Your weekly report",
  "createdAt": "2026-10-04T09:30:12.000Z",
  "occurredAt": "2026-10-04T09:30:14.000Z"
}

Idempotence

Donnez à chaque envoi une Idempotency-Key stable (l'id du rapport, l'id de l'évènement). Une relance avec la même clé rend l'envoi original au lieu d'envoyer deux fois, quoi qu'il soit arrivé à la première réponse en chemin.

C'est aussi la réponse à un 500 : rejouez avec la même clé jusqu'au 202. La clé est propre à votre projet : aucune collision possible avec d'autres clients.

Erreurs

Une seule forme pour tout échec : {"error": {"code", "message"}}. Le code est le contrat ; le message est pour vos journaux. Branchez sur le code, jamais sur le message.

CodeStatutCe que ça veut dire, et quoi faire
unauthorized401La clé manque, est malformée ou révoquée. La réponse ne dit jamais laquelle des trois.
invalid_payload422Le corps n'est pas du JSON ou ne respecte pas le contrat. `details` nomme chaque champ.
payload_too_large413Le corps de la requête dépasse 256 Ko.
recipient_suppressed422Cette adresse a rebondi dur ou s'est plainte. L'envoi est refusé ; cessez de lui écrire.
stream_not_ready409Le flux transactionnel n'est pas activé, pas vérifié, suspendu, ou sans expéditeur. Ça se règle dans les Réglages, pas dans le code.
quota_exceeded429Le plafond mensuel est atteint. `Retry-After` pointe le premier du mois ; monter de palier le lève tout de suite.
subscription_required402Aucun abonnement actif ne couvre ce projet, donc rien ne part. Choisir une offre, ou remettre le projet sous votre abonnement, le relance.
rate_limited429Trop de requêtes pour cette clé ou cette adresse. `Retry-After` dit quand revenir.
not_found404Aucun email de cet id pour cette clé. Un id qui n'est pas à vous ressemble exactement à un id inexistant.
internal_error500Notre côté a échoué. Rejouez avec la même Idempotency-Key : la relance ne peut pas doubler l'envoi.

Limites de débit

  • 120 requêtes par minute et par clé sur le POST, 300 par minute sur le GET.
  • Un 429 porte Retry-After en secondes. Respectez-le ; une boucle de relance serrée ne fait que dépenser votre budget plus vite.
  • Ces limites servent une boucle produit. L'envoi en masse appartient aux campagnes, qui ont leur propre pipeline, leur planification et leur désabonnement.

Le quota mensuel

Les envois transactionnels comptent dans le même quota mensuel que vos campagnes : un plan, un chiffre. La différence est ce qui se passe à la ligne : les campagnes s'arrêtent à 100 %, le mail de votre produit continue de partir.

Au-delà du quota vous êtes dans un dépassement toléré, sans facturation, avec une notification pour monter de palier. À deux fois le quota, l'API répond quota_exceeded : ce plafond existe pour qu'une boucle dans votre code ne tourne pas sans borne.

Suppression

Une adresse qui rebondit dur ou se plaint est supprimée pour tout votre projet, les deux flux à la fois : le fait, c'est l'adresse, pas le canal. Les envois suivants répondent recipient_suppressed.

Un désabonnement marketing ne supprime pas le transactionnel : la personne a refusé vos campagnes, pas son propre rapport ni la réinitialisation de son mot de passe.

Depuis Node

Pas besoin de SDK : l'API est un fetch. Si vous migrez depuis un outil d'email, ceci remplace l'appel d'envoi un pour un.

const response = await fetch("https://www.canopushq.io/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CANOPUS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `report-${reportId}`,
  },
  body: JSON.stringify({
    to: user.email,
    subject: "Your weekly report",
    html: renderedReport,
  }),
})

if (response.status === 422) {
  const { error } = await response.json()
  if (error.code === "recipient_suppressed") {
    // The address bounced or complained before: stop writing to it.
  }
}