Aide › Pour les développeurs
API d’envoi
Envoyez des e-mails depuis vos propres applications et sites, depuis vos propres adresses, avec vos propres modèles.
Vos applications, sites web et scripts peuvent envoyer des e-mails depuis les adresses de votre organisation avec une seule requête HTTPS : confirmations de commande, réinitialisations de mot de passe, formulaires de contact, rapports. Les e-mails partent de la même façon que ceux que vous écrivez dans SendHaste.
| Requête | Ce que ça fait |
|---|---|
POST https://sendhaste.com/api/v1/emails | Envoie un e-mail : votre propre contenu, ou l’un de vos modèles avec des valeurs. |
GET https://sendhaste.com/api/v1/templates | Liste les e-mails connectés aux modèles, et les valeurs que chacun utilise. |
GET https://sendhaste.com/api/v1/senders | Liste les adresses depuis lesquelles la clé peut envoyer. |
GET https://sendhaste.com/api/v1/openapi.json | Toute l’API dans un fichier OpenAPI 3.1, pour Postman, les générateurs de code et les autres outils de développement. Aucune clé nécessaire. |
1. Créer une clé API
- Un super admin de l’organisation ouvre Paramètres → Clés API.
- Cliquez sur Créer une clé API, donnez-lui un nom (par ex. Formulaire de contact du site) et choisissez Envoie depuis : n’importe quelle adresse de vos domaines, n’importe quelle adresse d’un domaine, ou une seule adresse. Cliquez sur Créer la clé.
- Une fenêtre affiche la nouvelle clé, avec son nom et l’adresse depuis laquelle elle envoie. Cliquez sur Copier, puis sur Terminé. La clé commence par
sh_et n’est affichée qu’une seule fois : si vous la perdez, révoquez-la et créez-en une nouvelle.
Pour les e-mails automatiques d’un domaine (confirmations de commande, alertes, rapports), ouvrez Paramètres → Domaines, choisissez le domaine et cliquez sur Créer une clé API pour yourdomain.com : la clé peut envoyer depuis n’importe quelle adresse de ce domaine, et d’aucun autre. Ajoutez d’abord une boîte mail pour l’adresse d’envoi, comme noreply@yourdomain.com. Seul l’expéditeur est limité : les e-mails peuvent aller à n’importe qui, dans votre entreprise ou en dehors.
Gardez la clé sur votre serveur, dans un paramètre ou une variable d’environnement. Ne la mettez jamais dans une page web, une application mobile ou un dépôt de code public : quiconque la possède peut envoyer des e-mails en votre nom. En cas de fuite, cliquez sur Révoquer : elle cesse aussitôt de fonctionner.
2. Envoyer un e-mail
Envoyez une requête POST à https://sendhaste.com/api/v1/emails, avec la clé dans l’en-tête Authorization: Bearer sh_… et l’e-mail en JSON :
curl https://sendhaste.com/api/v1/emails \
-H "Authorization: Bearer sh_your_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Your Company <info@yourcompany.com>",
"to": ["client@example.com"],
"subject": "Your booking is confirmed",
"html": "<p>Thank you! See you on <b>Monday</b>.</p>",
"text": "Thank you! See you on Monday."
}'const res = await fetch("https://sendhaste.com/api/v1/emails", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SENDHASTE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
from: "Your Company <info@yourcompany.com>",
to: "client@example.com",
subject: "Your booking is confirmed",
text: "Thank you! See you on Monday.",
}),
});
const result = await res.json(); // { id, from, to, recipients } or { error: { code, message } }3. Envoyer vos modèles
Au lieu d’écrire l’e-mail dans votre code, concevez-le une fois dans Modèles et laissez votre site l’envoyer par son nom : un e-mail de bienvenue, une réinitialisation du mot de passe, une confirmation de commande. Pour le changer plus tard, modifiez le modèle ou connectez le nom à un autre ; rien ne change sur le site.
- Dans Modèles, concevez l’e-mail. Là où va une valeur de votre site, tapez
{{params.first_name}}; après une barre, ce qu’il faut utiliser si elle manque :{{params.first_name|there}}. Cela marche dans l’objet, le texte et les adresses des boutons et des liens. - Un Org Super Admin ouvre Paramètres → Clés API, et sous E-mails envoyés par vos sites clique sur Connecter un e-mail, saisit un Nom de l’e-mail (par ex.
welcome), choisit le Modèle, choisit sous Envoyé depuis toutes les adresses de vos domaines, un domaine ou une adresse, et clique sur Connecter. - Sous Envoyer un test, envoyez-le-vous avec quelques valeurs pour voir le rendu.
- Votre site envoie
templateavec le nom, etparamsavec les valeurs. L’objet du modèle est utilisé, sauf si vous envoyez unsubject.
curl https://sendhaste.com/api/v1/emails \
-H "Authorization: Bearer sh_your_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Your Shop <hello@yourshop.com>",
"to": "aysel@example.com",
"template": "welcome",
"params": { "first_name": "Aysel", "verify_url": "https://yourshop.com/verify?t=8f2c" }
}'- Les balises intégrées fonctionnent aussi :
{{first_name}},{{name}},{{company}},{{email}}.{{email}}est la première adresse À ; les noms viennent deparamssi vous les envoyez, sinon du contact de la personne dans SendHaste. - Les valeurs sont insérées comme texte : le HTML d’une valeur s’affiche tel quel, et un lien doit commencer par https://, http:// ou mailto:.
- Une valeur sans valeur de repli reste vide : testez d’abord avec Envoyer un test.
Exemple : un e-mail de bienvenue pour les nouvelles inscriptions
- Créez un modèle nommé Welcome, avec l’objet
Welcome, {{params.first_name|there}}!, un titreHi {{params.first_name|there}}et un bouton vers{{params.verify_url}}. - Connectez-le sous le nom
welcomedans Paramètres → Clés API, et créez une clé qui envoie depuis votre adresse. - Mettez la clé dans les paramètres de votre site (par exemple une variable d’environnement
SENDHASTE_API_KEY). - Là où votre site enregistre un nouvel utilisateur, envoyez la requête. Choisissez votre langage :
await fetch("https://sendhaste.com/api/v1/emails", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SENDHASTE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
from: "Your Shop <hello@yourshop.com>",
to: user.email,
template: "welcome",
params: { first_name: user.firstName, verify_url: verifyUrl },
}),
});$ch = curl_init("https://sendhaste.com/api/v1/emails");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SENDHASTE_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode([
"from" => "Your Shop <hello@yourshop.com>",
"to" => $user["email"],
"template" => "welcome",
"params" => ["first_name" => $user["first_name"], "verify_url" => $verifyUrl],
]),
]);
$result = json_decode(curl_exec($ch), true);import os, requests
requests.post(
"https://sendhaste.com/api/v1/emails",
headers={"Authorization": f"Bearer {os.environ['SENDHASTE_API_KEY']}"},
json={
"from": "Your Shop <hello@yourshop.com>",
"to": user.email,
"template": "welcome",
"params": {"first_name": user.first_name, "verify_url": verify_url},
},
timeout=10,
)Envoyez-le après l’enregistrement de l’utilisateur, et ne laissez pas un e-mail échoué bloquer l’inscription : notez l’erreur et continuez. L’id de la réponse nous aide à retrouver un e-mail si vous nous écrivez.
Lister vos modèles
GET https://sendhaste.com/api/v1/templates avec la même clé renvoie les e-mails connectés dans Paramètres → Clés API, et les valeurs que chacun utilise :
{"data": [{"name": "welcome", "template_name": "Welcome", "subject": "Welcome, {{params.first_name|there}}!", "params": ["first_name", "verify_url"], "updated_at": "…", "scope": "domain", "for": "yourshop.com"}]}| Champ | Ce que c’est |
|---|---|
name | Ce qu’il faut envoyer comme template. |
template_name | Le nom du modèle dans SendHaste. |
subject | L’objet du modèle, balises pas encore remplies. |
params | Les noms {{params.…}} utilisés par le modèle : envoyez-les dans params. |
updated_at | Date de la dernière modification du modèle. |
scope | Pour qui il est connecté : organization (toutes les adresses de vos domaines), domain ou address. |
for | Le domaine ou l’adresse pour lequel il est connecté ; null pour toute l’organisation. |
Votre code peut l’appeler au démarrage, ou dans un test, pour vérifier que chaque e-mail envoyé est connecté et reçoit toutes ses valeurs.
Chaque e-mail est connecté pour toutes les adresses de vos domaines, pour un domaine ou pour une adresse (Envoyé depuis). Une clé ne liste et n’envoie que les e-mails des adresses depuis lesquelles elle peut envoyer : des sites sur des domaines différents voient donc chacun les leurs. Un même nom peut être connecté à chaque niveau : un e-mail envoyé depuis info@yourshop.com utilise celui de cette adresse, sinon celui de son domaine, sinon celui de l’organisation.
Lister vos adresses
GET https://sendhaste.com/api/v1/senders avec la même clé renvoie les adresses depuis lesquelles elle peut envoyer. Utilisez-la pour laisser choisir l'adresse d'expédition au lieu de l'écrire dans votre code.
{"data": [{"address": "info@yourcompany.com"}, {"address": "noreply@yourcompany.com"}], "domains": [{"domain": "yourcompany.com"}]}| Champ | Ce que c’est |
|---|---|
data | Toutes les adresses ayant une boîte mail depuis lesquelles la clé peut envoyer : l'adresse unique pour laquelle elle a été créée, toutes les boîtes de son domaine, ou toutes les boîtes de vos domaines. |
domains | Les domaines depuis lesquels la clé peut envoyer. Vide pour une clé créée pour une seule adresse. |
Chaque adresse d'expédition doit avoir sa propre boîte mail dans SendHaste. Une adresse ajoutée à une boîte sous Reçoit aussi ne peut pas servir, pas plus que catchall@. Pour une adresse d'envoi seul comme noreply@yourdomain.com, ajoutez-lui une boîte dans Paramètres → Domaines ; elle apparaît aussitôt dans data.
Les champs
| Champ | Requis | Ce que c’est |
|---|---|---|
from | oui | Une de vos adresses, avec un nom si vous le souhaitez : Your Company <info@yourcompany.com>. Elle doit avoir une boîte mail dans SendHaste. |
to | oui | Une adresse, ou une liste d’adresses. |
cc, bcc | non | Une adresse, ou une liste. Les destinataires en Cci ne sont pas visibles des autres. |
reply_to | non | Où vont les réponses, si ce n’est pas à l’adresse From. |
subject | oui, sauf avec template | La ligne d’objet. Avec un modèle, elle remplace l’objet du modèle. |
text | text ou html | La version en texte brut. |
html | text ou html | La version HTML. Envoyez les deux si possible ; avec seulement le HTML, la version texte est créée à partir de celui-ci. |
attachments | non | Une liste de fichiers : filename, content, content_type. Le contenu est encodé en base64. |
template | non | Le nom d’un e-mail connecté dans Paramètres → Clés API, par ex. welcome. À la place de text et html. |
params | non | Avec un modèle : les valeurs de ses balises {{params.…}}, par ex. {"first_name": "Aysel"}. Jusqu’à 100 valeurs. |
La réponse
Quand l’e-mail est envoyé : statut 200 et {"id": "…", "from": "info@yourcompany.com", "to": ["client@example.com"], "recipients": 1, "status": "sent"}. Avec un modèle, "template": "welcome" aussi.
Quand la limite quotidienne du jour est épuisée mais que celle de demain a encore de la place : statut 202 et les mêmes champs, avec "status": "queued", "deliverAfter": "2026-10-13T00:00:00Z". L’e-mail est accepté et SendHaste le garde ; il part à deliverAfter (le prochain minuit UTC), ou dès que le serveur de messagerie l’accepte ensuite. Considérez 202 comme un succès et ne le renvoyez pas : une nouvelle tentative le livrerait deux fois.
Sinon : un statut d’erreur, et {"error": {"code": "…", "message": "…"}}. Le code reste le même, votre code peut donc le vérifier ; le message indique quoi corriger.
| Statut | code | Que faire |
|---|---|---|
401 | missing_api_key, invalid_api_key | Vérifiez l’en-tête Authorization, ou créez une nouvelle clé : celle-ci a été révoquée. |
403 | from_not_allowed | Envoyez depuis une adresse de vos domaines (pas catchall@, qui ne fait que recevoir), ou depuis le domaine ou la seule adresse à laquelle la clé est limitée. |
403 | api_disabled | L’envoi via l’API n’est pas activé pour votre organisation : demandez-le-nous depuis la page Assistance. |
400 | invalid_json | Envoyez un objet JSON. |
415 | unsupported_media_type | Définissez Content-Type: application/json. |
422 | invalid_field, mailbox_not_found | Corrigez le champ indiqué par le message, ou créez d’abord la boîte mail de l’expéditeur (From). |
404 | template_not_found | Connectez le nom de l’e-mail à un modèle dans Paramètres → Clés API, pour l’adresse From, son domaine ou toute l’organisation, ou vérifiez l’orthographe. |
413 | too_large | Envoyez des pièces jointes plus petites. |
429 | rate_limited, daily_limit | Trop de requêtes : attendez le nombre de secondes indiqué dans l’en-tête Retry-After. Limite quotidienne : les e-mails d’aujourd’hui et de demain sont tous épuisés, ou la limite quotidienne du serveur de messagerie pour l’adresse est atteinte ; attendez le nombre de secondes indiqué dans Retry-After (jusqu’à minuit UTC) et envoyez-le alors. |
502, 503 | send_failed, mailbox_not_ready | Non envoyé : réessayez dans quelques minutes. Si cela continue, écrivez-nous. Un e-mail accepté par le serveur de messagerie ne reçoit jamais cette réponse, même quand sa réponse a tardé. |
Limites
- Jusqu’à 60 requêtes par minute et par clé.
- Jusqu’à 50 destinataires par e-mail (to, cc et bcc ensemble).
- Jusqu’à 20 pièces jointes et 25 Mo par e-mail.
- Chaque domaine peut envoyer jusqu’à 300 e-mails par jour, depuis SendHaste ou par l’API, et chacune de ses boîtes mail peut écrire à autant de personnes que la limite du domaine, ou moins si un Super admin de l’organisation règle Personnes que chaque boîte peut contacter par jour sur la page du domaine. Un domaine nouvellement connecté commence plus bas ; sa page dans Paramètres → Domaines indique E-mails aujourd’hui par rapport à sa limite, Refusés aujourd’hui, Retenus pour demain, et En chauffe pendant qu’elle augmente.
- Un e-mail au-delà de la limite du jour n’est pas perdu : SendHaste le garde et l’envoie après minuit UTC, compté sur la limite de demain (statut
202). Si le serveur de messagerie est encore à sa propre limite à ce moment-là, il part dès que le serveur l’accepte. Il n’est refusé (daily_limit) que lorsque la limite de demain est elle aussi épuisée. - Les e-mails en attente de cette façon sont listés sous Programmés dans la barre latérale de la boîte mail, sous Retenus par la limite quotidienne d’envoi ; rien à faire, ils partent d’eux-mêmes.
Vous préférez SMTP ? De nombreuses applications et frameworks peuvent plutôt envoyer via une boîte mail en SMTP : voir Outlook, Apple Mail et applications sur téléphone pour le serveur et le port. Les mêmes limites quotidiennes s’appliquent.
Vous ne trouvez pas ce qu’il vous faut ? Envoyez-nous un message.