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.
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à.
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.
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.
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.
| Code | Statut | Ce que ça veut dire, et quoi faire |
|---|---|---|
| unauthorized | 401 | La clé manque, est malformée ou révoquée. La réponse ne dit jamais laquelle des trois. |
| invalid_payload | 422 | Le corps n'est pas du JSON ou ne respecte pas le contrat. `details` nomme chaque champ. |
| payload_too_large | 413 | Le corps de la requête dépasse 256 Ko. |
| recipient_suppressed | 422 | Cette adresse a rebondi dur ou s'est plainte. L'envoi est refusé ; cessez de lui écrire. |
| stream_not_ready | 409 | Le 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_exceeded | 429 | Le plafond mensuel est atteint. `Retry-After` pointe le premier du mois ; monter de palier le lève tout de suite. |
| subscription_required | 402 | Aucun abonnement actif ne couvre ce projet, donc rien ne part. Choisir une offre, ou remettre le projet sous votre abonnement, le relance. |
| rate_limited | 429 | Trop de requêtes pour cette clé ou cette adresse. `Retry-After` dit quand revenir. |
| not_found | 404 | Aucun email de cet id pour cette clé. Un id qui n'est pas à vous ressemble exactement à un id inexistant. |
| internal_error | 500 | Notre 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.
}
}