Référence de l'API

Un seul point d'entrée : POST /api/send.php.

endpoint

POST https://mailer.echange.online/api/send.php

GET est également accepté (pratique pour un test rapide depuis un navigateur), mais POST est la méthode recommandée : une requête GET fait apparaître la clé API et le contenu du message dans les journaux du serveur, l'historique du navigateur et les en-têtes Referer.

Authentification

Chaque appel doit porter une clé API valide, de préférence dans un en-tête :

bash

-H "X-API-Key: msk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Le paramètre api_key dans le corps de la requête est accepté en repli, pour les environnements où l'on ne maîtrise pas les en-têtes. La clé est liée à un compte SMTP et à un utilisateur : c'est elle qui détermine le serveur d'envoi, le quota et les limites de débit appliquées.

Formats de requête acceptés

`Content-Type`	Usage
`application/x-www-form-urlencoded`	Le plus courant. `curl -d`, formulaires HTML, clients HTTP classiques.
`multipart/form-data`	Obligatoire pour envoyer un fichier en pièce jointe par upload. `curl -F`.
`application/json`	Corps JSON. Autorise les tableaux d'adresses et l'objet `vars` sans ré-encodage.

En cas de doublon, la priorité est : corps JSON > corps de formulaire > paramètres d'URL.

Paramètres

Message

Paramètre	Type	Requis	Description
`from`	adresse	oui	Expéditeur affiché. Une seule adresse. Forme `Nom <adresse>` acceptée.
`to`	adresses	oui	Destinataires, séparés par des virgules (ou tableau JSON).
`cc`	adresses	non	Copie visible.
`bcc`	adresses	non	Copie cachée, absente des en-têtes du message.
`reply_to`	adresses	non	Adresse de réponse, si différente de `from`.
`subject`	texte	oui*	Objet du message. *Facultatif si un `template` en fournit un.
`body`	texte	oui*	Corps du message. *Facultatif si un `template` en fournit un.
`format`	`text` \| `html`	non	Format d'envoi. Défaut : `text`.
`text_body`	texte	non	Version texte d'un email HTML. Générée automatiquement depuis le HTML si absente.
`html`	booléen	non	Ancien paramètre, équivalent à `format=html`. Conservé par compatibilité.

Templates

Paramètre	Type	Requis	Description
`template`	texte	non	Identifiant (slug) ou id numérique d'un de vos templates.
`vars`	objet JSON	non	Valeurs des variables `{nom}`. Valeurs simples uniquement (texte, nombre).
`strict_vars`	booléen	non	Défaut `1` : une variable sans valeur provoque une erreur. `0` : le placeholder est laissé tel quel.

Pièces jointes

Paramètre	Type	Requis	Description
`attachments[]`	fichier(s)	non	Un ou plusieurs fichiers, en `multipart/form-data`.
`attachments`	tableau JSON	non	Objets `{filename, content_base64, content_type}`, en `application/json`.

Réponse en cas de succès

json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "message_id": "<3f0a1c...@mondomaine.com>",
  "format": "html",
  "template": "confirmation-commande",
  "recipients": { "to": 2, "cc": 1, "bcc": 0 },
  "attachments": { "count": 1, "bytes": 184320 },
  "quota": { "used": 128, "quota": 20000 }
}

Champ	Description
`message_id`	En-tête `Message-ID` du message envoyé. À conserver pour tout rapprochement ultérieur.
`format`	Format effectivement utilisé.
`template`	Slug du template utilisé, ou `null`.
`recipients`	Nombre d'adresses par champ.
`attachments`	Nombre et taille cumulée (avant encodage) des pièces jointes.
`quota`	Consommation du mois en cours après cet envoi. `quota: 0` signifie « illimité ».

Réponse en cas d'erreur

json

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Au moins un destinataire \"to\" est requis."
  }
}

Le champ error.code est stable : testez-le dans votre code plutôt que le message, qui peut être reformulé. La liste complète se trouve sur Codes d'erreur.

Ordre des contrôles

Comprendre cet ordre aide à interpréter les erreurs — et garantit qu'une requête refusée ne consomme pas de quota :

Méthode HTTP et lisibilité du corps de la requête ;
clé API valide et active ;
compte utilisateur actif ;
adresse IP autorisée pour cette clé ;
template demandé (existence, forfait) ;
validation du message (adresses, format, variables, pièces jointes) ;
quota mensuel, puis limites de débit ;
envoi SMTP.

À savoir

Le quota et le débit ne sont décomptés qu'une fois la requête entièrement validée. Une erreur 4xx de validation ne coûte donc rien. En revanche, un échec SMTP (502) intervient après le décompte : l'envoi a bien été tenté.

Journalisation

Chaque appel, réussi ou non, est journalisé avec : horodatage, clé API utilisée, IP source, user-agent, compte SMTP, sujet, format, template, nombre de destinataires, nombre et taille des pièces jointes, Message-ID, réponse du serveur SMTP et durée. Ces informations sont consultables depuis le tableau de bord.