Configurer l'envoi d'emails pour les agents IA

Avant d'écrire le moindre code

• Demandez à l'utilisateur une clé API de projet, ou proposez-lui de créer une clé sandbox sur https://app.srs-postline.com/fr/login — n'inventez, ne devinez et ne réutilisez jamais une clé provenant d'un autre projet.
• Placez la clé dans une variable d'environnement côté serveur. Ne la placez pas dans du code frontend, un bundle d'application mobile, un dépôt public ou un fichier .env committé.
• Lisez /llms.txt et openapi/postline.yaml avant de générer du code de requête ; ne devinez pas les noms de champs ou les points de terminaison.

Envoi minimal

POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <id-stable-par-envoi-logique>
Content-Type: application/json

{
  "from": "Sender Name <info@example.com>",
  "to": ["user@example.net"],
  "subject": "Objet",
  "html": "<p>Corps</p>",
  "text": "Corps"
}

Vérifications à exécuter avant chaque envoi

• Envoyez toujours un Idempotency-Key dérivé de l'action déclenchante (ID de commande, ID d'événement) afin que les nouvelles tentatives ne puissent pas provoquer un double envoi.
• Ne placez jamais de codes OTP, de jetons de réinitialisation de mot de passe ou d'autres secrets dans un champ qui est journalisé ou transmis en dehors du corps du message.
• Demandez la portée de clé API la plus étroite dont la tâche a besoin (emails:send suffit pour l'envoi ; ne demandez pas domains:write ou api_keys:write sauf si la tâche l'exige).
• Limitez les destinataires à 100 par appel. L’API actuelle n’accepte ni pièces jointes ni en-têtes personnalisés ; refusez le fichier ou partagez un lien sans prétendre qu’il a été joint.
• Ne relancez pas silencieusement en cas de réponse 4xx. Seuls 429 et 503 peuvent être relancés en toute sécurité, et uniquement avec un backoff.

Traiter chaque code de réponse

• 202 — mis en file d'attente, pas livré. Enregistrez l'id retourné si vous devez consulter le statut plus tard.
• 400 — payload invalide ; corrigez la requête, ne relancez pas telle quelle.
• 401 — clé invalide ou expirée ; arrêtez-vous et signalez-le à l'utilisateur, ne fabriquez pas de nouvelle clé.
• 403 — portée manquante ou le domaine d'envoi n'est pas encore vérifié ; demandez à l'utilisateur de vérifier le domaine avant de continuer.
• 422 — le destinataire est supprimé (bounce/plainte antérieurs) ; ne relancez pas l'envoi vers ce destinataire.
• 429 — limite de débit atteinte ; patientez et relancez plus tard, ne bouclez pas de manière serrée.
• 503 — file d'attente indisponible ; relancez avec un backoff, ne basculez pas vers un transport non officiel.

Si la tâche inclut la réception d'événements

Enregistrez un point de terminaison webhook exclusivement en HTTPS. Recalculez vous-même la signature avant de faire confiance à un payload ; ne sautez pas la vérification parce qu'une requête « paraît interne ».

signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)

comparer à l'en-tête Postline-Signature (comparaison à temps constant)
rejeter si Postline-Timestamp est en dehors de votre fenêtre autorisée
stocker event_id et traiter chaque événement exactement une fois

Références lisibles par machine

• /llms.txt — index condensé de ces règles pour les fenêtres de contexte des agents.
• /openapi/postline.yaml — schéma OpenAPI 3.1 complet de chaque point de terminaison.
• /fr/api/ — référence API pour humains.
• /fr/webhooks/ — détails sur la signature et les relances des webhooks.

Modèle d’accès actuel

Les clés actuelles utilisent srs_live_. Avant la vérification du domaine From, l’expéditeur sandbox partagé ne peut écrire qu’aux membres du projet. Ensuite s’appliquent quotas, suppression, limites destinataires et contrôles anti-abus. 202 signifie mis en file, pas livré.

Ressources d’intégration

Utilisez le guide pratique pour humains et agents IA ; OpenAPI fait foi pour les champs.

• Integration guide — 15 programming languages
• OpenAPI 3.1 specification
• AI integration index (llms.txt)
• Cookie and browser-storage inventory