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êteCe que ça fait
POST https://sendhaste.com/api/v1/emailsEnvoie un e-mail : votre propre contenu, ou l’un de vos modèles avec des valeurs.
GET https://sendhaste.com/api/v1/templatesListe les e-mails connectés aux modèles, et les valeurs que chacun utilise.
GET https://sendhaste.com/api/v1/sendersListe les adresses depuis lesquelles la clé peut envoyer.
GET https://sendhaste.com/api/v1/openapi.jsonToute 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

  1. Un super admin de l’organisation ouvre Paramètres → Clés API.
  2. 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é.
  3. 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
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."
  }'
JavaScript (Node.js 18+)
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.

  1. 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.
  2. 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.
  3. Sous Envoyer un test, envoyez-le-vous avec quelques valeurs pour voir le rendu.
  4. Votre site envoie template avec le nom, et params avec les valeurs. L’objet du modèle est utilisé, sauf si vous envoyez un subject.
curl
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 de params si 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

  1. Créez un modèle nommé Welcome, avec l’objet Welcome, {{params.first_name|there}}!, un titre Hi {{params.first_name|there}} et un bouton vers {{params.verify_url}}.
  2. Connectez-le sous le nom welcome dans Paramètres → Clés API, et créez une clé qui envoie depuis votre adresse.
  3. Mettez la clé dans les paramètres de votre site (par exemple une variable d’environnement SENDHASTE_API_KEY).
  4. Là où votre site enregistre un nouvel utilisateur, envoyez la requête. Choisissez votre langage :
JavaScript (Node.js 18+)
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 },
  }),
});
PHP
$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);
Python
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 :

JSON
{"data": [{"name": "welcome", "template_name": "Welcome", "subject": "Welcome, {{params.first_name|there}}!", "params": ["first_name", "verify_url"], "updated_at": "…", "scope": "domain", "for": "yourshop.com"}]}
ChampCe que c’est
nameCe qu’il faut envoyer comme template.
template_nameLe nom du modèle dans SendHaste.
subjectL’objet du modèle, balises pas encore remplies.
paramsLes noms {{params.…}} utilisés par le modèle : envoyez-les dans params.
updated_atDate de la dernière modification du modèle.
scopePour qui il est connecté : organization (toutes les adresses de vos domaines), domain ou address.
forLe 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.

JSON
{"data": [{"address": "info@yourcompany.com"}, {"address": "noreply@yourcompany.com"}], "domains": [{"domain": "yourcompany.com"}]}
ChampCe que c’est
dataToutes 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.
domainsLes 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

ChampRequisCe que c’est
fromouiUne de vos adresses, avec un nom si vous le souhaitez : Your Company <info@yourcompany.com>. Elle doit avoir une boîte mail dans SendHaste.
toouiUne adresse, ou une liste d’adresses.
cc, bccnonUne adresse, ou une liste. Les destinataires en Cci ne sont pas visibles des autres.
reply_tononOù vont les réponses, si ce n’est pas à l’adresse From.
subjectoui, sauf avec templateLa ligne d’objet. Avec un modèle, elle remplace l’objet du modèle.
texttext ou htmlLa version en texte brut.
htmltext ou htmlLa version HTML. Envoyez les deux si possible ; avec seulement le HTML, la version texte est créée à partir de celui-ci.
attachmentsnonUne liste de fichiers : filename, content, content_type. Le contenu est encodé en base64.
templatenonLe nom d’un e-mail connecté dans Paramètres → Clés API, par ex. welcome. À la place de text et html.
paramsnonAvec 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.

StatutcodeQue faire
401missing_api_key, invalid_api_keyVérifiez l’en-tête Authorization, ou créez une nouvelle clé : celle-ci a été révoquée.
403from_not_allowedEnvoyez 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.
403api_disabledL’envoi via l’API n’est pas activé pour votre organisation : demandez-le-nous depuis la page Assistance.
400invalid_jsonEnvoyez un objet JSON.
415unsupported_media_typeDéfinissez Content-Type: application/json.
422invalid_field, mailbox_not_foundCorrigez le champ indiqué par le message, ou créez d’abord la boîte mail de l’expéditeur (From).
404template_not_foundConnectez 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.
413too_largeEnvoyez des pièces jointes plus petites.
429rate_limited, daily_limitTrop 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, 503send_failed, mailbox_not_readyNon 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.