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.

POST GET (dev) https://mailsender.beartson.com/api/v1/send

Authentification

Trois possibilités, prises dans cet ordre :

  1. Authorization: Bearer ms_ab12cd34e.VOTRE_CLE_SECRETE — recommandé
  2. X-Api-Key: ms_ab12cd34e.VOTRE_CLE_SECRETE
  3. ?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.