Documentation pour les développeurs

Pour commencer

1. Créez un compte et une marque, puis vérifiez le domaine depuis lequel vous voulez envoyer.
2. Dans la console, créez une clé API pour cette marque et choisissez les capacités dont elle a besoin. Les capacités ne se modifient pas ensuite : pour les changer, créez une nouvelle clé.
3. Appelez l'API avec la clé dans l'en-tête Authorization.

Adresse de base

https://api.mailronix.com

Authentification

Authorization: Bearer mrx_live_…

Le premier envoi

L'expéditeur doit se trouver sur le domaine vérifié de la marque à laquelle la clé est liée. Une réponse 202 signifie que le message est en file d'attente, pas qu'il a été remis.

curl -X POST https://api.mailronix.com/email/send \
  -H "Authorization: Bearer mrx_live_<la-tua-chiave>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-4821" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Conferma ordine #4821",
    "html_body": "<p>Il tuo ordine #4821 è confermato.</p>"
  }'

Le même envoi en Node.js, sans dépendance :

const risposta = await fetch('https://api.mailronix.com/email/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILRONIX_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ordine-4821',
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Conferma ordine #4821',
    html_body: '<p>Il tuo ordine #4821 è confermato.</p>',
  }),
})

if (!risposta.ok) {
  const { error } = await risposta.json()
  throw new Error(`${error.code}: ${error.message}`)
}
console.log(await risposta.json()) // { status: 'queued', email_log_id: '…' }

Réponse

202 Accepted
{ "status": "queued", "email_log_id": "9c4e2f1a-7d3b-4a5e-8f6c-1b2a3d4e5f6a" }

Pour réessayer sans risque de doublon, envoyez l'en-tête Idempotency-Key : une nouvelle requête avec la même clé et le même corps, dans les 24 heures, renvoie la réponse du premier appel.

Nom de l'expéditeur, réponses et pièces jointes

Trois champs facultatifs de POST /email/send. Si vous ne les envoyez pas, le comportement reste celui d'avant.

Exemple avec les trois champs

{
  "from": "[email protected]",
  "from_name": "Acme Assistenza",
  "reply_to": "[email protected]",
  "to": "[email protected]",
  "subject": "La tua fattura",
  "html_body": "<p>In allegato la fattura.</p>",
  "attachments": [
    {
      "filename": "fattura-2026-0412.pdf",
      "content_type": "application/pdf",
      "content": "JVBERi0xLjcK…"
    }
  ]
}

• from_name : le nom que le destinataire lit à la place de l'adresse, de 1 à 78 caractères (les accents sont acceptés ; ni @, < >, ni guillemets, retours à la ligne ou adresses web). S'il manque, le nom défini sur la marque est utilisé.
• reply_to : l'adresse à laquelle vont les réponses, sur n'importe quel domaine sauf celui de Mailronix. Il faut l'activer dans la console, dans les réglages de la marque, avec « Autoriser reply_to dans la requête » : désactivé par défaut et impossible à activer avec une clé API, car une clé volée ne doit pas pouvoir rediriger les réponses (sans consentement, la réponse est 403 reply_to_not_allowed).
• attachments : jusqu'à 5 pièces jointes par message, 7 Mo de fichiers au total et l'e-mail complet sous 10 Mo (dans l'e-mail, les pièces jointes pèsent environ un tiers de plus). Types acceptés : PDF, PNG, JPEG, GIF, texte, CSV et calendrier. Uniquement pour les messages transactionnels, sur toutes les offres : avec "marketing": true, la réponse est 400 attachments_not_allowed_for_marketing.
• Les pièces jointes ne restent chez nous que le temps de l'envoi et jamais plus de 24 heures ; le journal du message conserve nom, type, taille et empreinte, jamais le contenu. Il n'y a pas d'analyse antivirus : le contenu est sous votre responsabilité. Pour réessayer avec la même Idempotency-Key, renvoyez les mêmes octets.

Ce que peut faire une clé

Chaque clé ne porte que les capacités choisies à sa création. Sans la bonne capacité, l'API répond 403 capability_not_granted.

POST /email/send

Envoyer un e-mail transactionnel, avec un contenu direct ou à partir d'un modèle avec variables.

Capacité: email:send

GET /email/{id}

Lire l'état d'un envoi.

Capacité: email:read

POST /contacts

Créer un contact. Il naît non confirmé : la demande de confirmation part de Mailronix.

Capacité: contacts:write

POST /contacts/revoke

Enregistrer la désinscription d'une adresse.

Capacité: contacts:unsubscribe

POST /contacts/delete

Supprimer un contact. Exige aussi la capacité de désinscription.

Capacité: contacts:delete

GET /contacts/revocations

Lister les révocations de la marque de la clé, par curseur.

Capacité: revocations:read

Règles à connaître

• Une clé écrit toujours et uniquement sous la marque à laquelle elle a été liée à sa création. Si vous avez plusieurs marques, vous créez une clé par marque.
• Un message est transactionnel par défaut. Avec "marketing": true, il n'est envoyé qu'aux contacts qui ont confirmé leur inscription et comporte le lien de désinscription.
• Vous ne pouvez pas déclarer un consentement recueilli ailleurs : le consentement ne vaut que si le destinataire le confirme par son propre clic.
• language (facultatif, sur POST /email/send et POST /contacts) : it, en, es, de ou fr. Il choisit la langue des textes de service et des pages liées ; il ne traduit ni le HTML ni les modèles. Sans ce champ, la langue de la marque s'applique ; toute autre valeur renvoie 400 invalid_language.
• Les erreurs ont toujours la même forme, avec un code stable à lire par le programme et un message pour les personnes.
• La limite de requêtes s'applique par clé (429 rate_limited). Une fois le quota mensuel de l'offre épuisée, les envois sont refusés (403 plan_limit_exceeded) jusqu'au mois civil UTC suivant ; l'offre Free a aussi une limite de 500 destinataires uniques par jour.

{ "error": { "code": "rate_limited", "message": "…" } }

Ce qui ne se fait pas par l'API

Les campagnes, la création et la révocation des clés API, les modèles, la configuration des webhooks et la facturation se gèrent uniquement depuis la console, avec une session. C'est un choix de sécurité : une clé volée ne doit pouvoir ni créer des identifiants ni rediriger les données de vos envois.

Référence de l'API

Chaque endpoint, champ et réponse, générés à partir de la spécification et lisibles sans la télécharger.

Spécification OpenAPI

La spécification OpenAPI 3.1 décrit chaque endpoint, champ et erreur : importez-la dans votre client ou votre outil de test. Elle est rédigée en italien.

Webhooks sortants

Pour éviter le polling, vous pouvez enregistrer dans la console des adresses HTTPS auxquelles Mailronix envoie les événements de votre compte, avec une signature HMAC et des nouvelles tentatives automatiques.