Un message utile.
Un contrat explicite.

Le contrat utilise Authorization: Bearer avec une clé de service créée dans l’application. Ses scopes, son espace et son échéance limitent les opérations. Les exemples ci-dessous ne contiennent aucune clé utilisable.

messages.send autorise une intention transactionnelle ; messages.read sert à lire un message et ses événements. statistics.read et events.write couvrent leurs endpoints respectifs. Une clé ne remplace pas l’approbation humaine d’une campagne marketing.

Le POST requiert un destinataire, un expéditeur autorisé, une version de modèle transactionnel déjà publiée et une catégorie compatible. Un email promotionnel ne devient pas un message de service en changeant seulement son étiquette.

Utilisez la même Idempotency-Key pour la même opération logique et le même corps. Une nouvelle clé est une nouvelle intention. Réutiliser la clé avec un corps différent provoque un conflit.

POST /api/v1/messages HTTP/1.1
Host: mailie.app
Authorization: Bearer MAILIE_SERVICE_KEY_PLACEHOLDER
Idempotency-Key: demo-order-42
Content-Type: application/json

{
  "type": "transactional",
  "category": "order_confirmation",
  "fromSenderId": "11111111-1111-4111-8111-111111111111",
  "to": {
    "email": "recipient@example.invalid",
    "name": "Recipient example"
  },
  "template": {
    "id": "22222222-2222-4222-8222-222222222222",
    "version": 1
  },
  "variables": {
    "reference": "ORDER-EXAMPLE-42"
  },
  "metadata": {
    "external_reference": "demo_order_42"
  }
}

GET /api/v1/messages/{messageId}
GET /api/v1/messages/{messageId}/events

Authorization: Bearer MAILIE_READ_KEY_PLACEHOLDER

202 indique que le message et sa file durable ont été créés. Lisez ensuite l’état et les événements via l’identifiant retourné. Une acceptation par le transport reste distincte d’une livraison au destinataire.

Une réponse perdue autour de la remise peut produire un état incertain. Vérifiez l’intention existante et ses événements avant toute décision de renvoi. Les ouvertures et clics individuels ne sont pas des critères de succès disponibles.

Les erreurs utilisent un format Problem Details avec un code et une référence de requête. Les limites et quotas viennent de la politique de l’espace ; cette page ne promet pas de capacité illimitée.

Les webhooks clients du chantier utilisent une signature et un identifiant d’événement. Un callback dupliqué doit rester idempotent. Validez la signature et conservez l’identité logique avant de produire un effet dans votre système.

Une erreur HTTP marquée comme réessayable ne prouve pas qu’une remise précédente n’a jamais été acceptée. Conservez l’identité logique et vérifiez toute issue incertaine.