API d'envoi — v1
Une seule requête HTTP suffit pour envoyer un email. La clé d'API détermine le compte SMTP utilisé et l'adresse d'expéditeur.
https://mailsender.beartson.com/api/v1/send
Authentification
Trois possibilités, prises dans cet ordre :
Authorization: Bearer ms_ab12cd34e.VOTRE_CLE_SECRETE— recommandéX-Api-Key: ms_ab12cd34e.VOTRE_CLE_SECRETE?api_key=ms_ab12cd34e.VOTRE_CLE_SECRETE— nécessaire en GET
Paramètres
| Nom | Requis | Type | Description |
|---|---|---|---|
| to | oui | string · tableau | Destinataire(s). Plusieurs adresses séparées par une virgule, ou un tableau JSON. |
| subject | oui | string | Sujet du message (500 caractères maximum). |
| text | l'un | string | Corps en texte brut. |
| html | ou l'autre | string | Corps en HTML. Si seul html est fourni, une version texte est générée. |
| cc | non | string · tableau | Copie. |
| bcc | non | string · tableau | Copie cachée (jamais visible dans les en-têtes). |
| reply_to | non | string | Adresse de réponse. |
| from_name | non | string | Nom affiché de l'expéditeur. L'adresse, elle, est fixée par le compte SMTP. |
| attachments | non | tableau | POST uniquement : [{"filename":"f.pdf","content":"<base64>","type":"application/pdf"}]. |
| log_body_preview | non | booléen | Mettre à 0 pour qu'aucun extrait du corps ne soit conservé dans le journal, même si la clé l'autorise. Équivaut à l'en-tête X-Log-Body-Preview: 0. |
Exemples
curl -X POST https://mailsender.beartson.com/api/v1/send \
-H "Authorization: Bearer ms_ab12cd34e.VOTRE_CLE_SECRETE" \
-H "Content-Type: application/json" \
-d '{
"to": "client@exemple.fr",
"subject": "Confirmation de commande",
"html": "<h1>Merci !</h1><p>Votre commande est confirmée.</p>",
"text": "Merci ! Votre commande est confirmée.",
"reply_to": "support@exemple.fr"
}'
Réponse en cas de succès — HTTP 202
{
"success": true,
"message_id": 1284,
"accepted": ["client@exemple.fr"],
"quota": {
"hour_remaining": 97,
"day_remaining": 981
}
}
Réponse en cas d'erreur
{
"success": false,
"error": {
"code": "rate_limited",
"message": "Quota horaire atteint pour cette clé."
}
}
Codes d'erreur
| 401 | missing_api_key | Aucune clé fournie. |
| 401 | invalid_api_key | Clé inconnue. |
| 403 | key_revoked | Clé désactivée. |
| 403 | key_expired | Clé arrivée à expiration. |
| 403 | ip_not_allowed | IP appelante hors de la liste autorisée. |
| 403 | smtp_disabled | Compte SMTP désactivé. |
| 405 | get_disabled | GET coupé sur le serveur. |
| 405 | get_not_allowed_for_key | GET non activé sur cette clé. |
| 422 | invalid_request | Paramètre manquant ou invalide. |
| 429 | rate_limited | Quota horaire ou journalier atteint. |
| 502 | send_failed | Le serveur SMTP a refusé le message. |
Journal d'envoi
Chaque requête présentant une clé connue laisse une ligne dans le journal : les envois réussis, les échecs SMTP, mais aussi les refus (quota atteint, clé révoquée ou expirée, adresse IP non autorisée, méthode GET refusée). Le bouton « Colonnes » permet de choisir ce qui est affiché ; le choix est conservé pour votre compte.
Aperçu du corps
Une clé peut journaliser les 20 premiers caractères du corps de chaque message, ce qui aide à retrouver un envoi précis. L'option se règle sur la clé (« Journaliser les 20 premiers caractères du corps ») et se coupe d'un clic depuis l'écran des clés : l'envoi suivant n'en garde plus rien.
Côté code, une requête peut aussi couper l'aperçu au cas par cas — utile quand un message précis transporte des données sensibles :
# Par paramètre
curl -X POST https://mailsender.beartson.com/api/v1/send \
-H "Authorization: Bearer ms_ab12cd34e.VOTRE_CLE_SECRETE" \
-d "to=client@exemple.fr" -d "subject=Facture" \
-d "text=Votre code est 4821" \
-d "log_body_preview=0"
# Ou par en-tête
-H "X-Log-Body-Preview: 0"
Ce réglage ne peut que désactiver l'aperçu : une requête ne peut jamais faire archiver un corps que le propriétaire de la clé a choisi de ne pas conserver.
Autres points d'entrée
-
GET /api/v1/ping— vérifie que le service répond (aucune authentification). -
GET /api/v1/quota— consommation courante de la clé fournie.