> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/sending-invites.md). # Envoi d'invitations (API e-mail) Déclenchez des e-mails d'invitation à des enquêtes personnalisés depuis vos propres systèmes. L’API d’invitation transforme BAI Analytics en la branche d’envoi de votre propre flux de travail : votre système décide *qui* à qui envoyer un e-mail et *quand* (un ticket d’assistance fermé, une commande livrée, un onboarding terminé), et BAI Analytics génère le modèle d’invitation, l’envoie, suit la livraison et rattache les réponses à vos contacts. La répartition des responsabilités est délibérée : **la conception se fait dans le tableau de bord, le déclenchement dans l’API.** Le modèle d’e-mail, l’identité visuelle et l’enquête sont créés dans la plateforme, où ils peuvent être prévisualisés et relus ; l’API ne fournit que les destinataires et les variables. Ainsi, une clé compromise ne peut jamais réécrire ce que reçoivent vos clients. *** ### Prérequis Trois conditions doivent être remplies pour que le premier envoi fonctionne. Les trois sont consultables via `GET /sources/{id}/invite-template`, donc intégrez cela à vos vérifications de configuration : 1. **Un `send`-clé API à portée spécifique.** L’envoi d’e-mails à des humains est séparé du push de données ; `all` l’inclut. Voir [Authentification et clés API](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/authentication.md). 2. **Le domaine d’envoi vérifié de votre organisation.** Les envois via l’API n’utilisent jamais l’expéditeur partagé de BAI Analytics : le volume automatisé repose sur votre réputation d’envoi, pas sur la nôtre. Tant que le domaine n’est pas vérifié, vous recevrez une `SENDER_DOMAIN_NOT_VERIFIED` erreur. Configurez-le sous **Détails de l’organisation → Envoi d’e-mails** ([Paramètres](/boundaryai-docs/boundaryai-docs-fr/compte-et-administration/updating-settings.md#email-sending)). 3. **Un modèle d’invitation sur la source**, conçu dans la plateforme. La vérification du modèle renvoie ses **clés de variables** (par exemple, `first_name`, `order_id`) afin que votre intégration puisse valider ses données avant l’envoi. *** ### Le flux d’envoi #### 1. Vérifier la disponibilité ```bash curl https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/9021/invite-template \\ -H "Authorization: Bearer $BAI_API_KEY" ``` Indique si un modèle est `configuré`, son `variables`, `sender_domain_verified`, `sending_enabled`, ainsi que l’utilisation du quota du jour. #### 2. Prévisualiser avec `dry_run` ```bash curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/9021/invites \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -d '{ "dry_run": true, "recipients": [ {"email": "jamie@example.com", "external_id": "cus_310", "variables": {"first_name": "Jamie", "order_id": "A-1042"}} ] }' ``` Un essai à blanc génère les e-mails et indique ce qui *ferait* se passerait (`would_accept`, `skipped_already_invited`, `invalide`) sans rien envoyer. Utilisez-le dans l’intégration continue et avant le premier envoi en production. #### 3. Envoyer Supprimez `dry_run` et le même appel renvoie **202** avec une `distribution_id`. Les envois sont transactionnels : 1 à 1 000 destinataires par appel, chacun avec son propre `variables`. **lien d’enquête personnalisé**, qui rattache ensuite leur réponse à votre `external_id`. #### 4. Suivre le résultat * `GET /invites/{distribution_id}`: état global et compteurs (`total`, `envoyés`, `échoués`, `ignoré`). * `GET /invites/{distribution_id}/recipients`: résultats par destinataire, y compris le **statut de livraison** signalé par le fournisseur de messagerie (délivré, rejeté, différé) et votre `external_id`, paginé par curseur. * Ou évitez l’interrogation : le **`invites.completed`** webhook se déclenche lorsque la distribution est terminée, et **`invite.bounced`** se déclenche pour chaque rebond ou plainte pour spam. Voir [Webhooks](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/webhooks.md). *** ### Garde-fous (et pourquoi ils ne sont pas optionnels) Ils existent pour qu’un bug d’automatisation ne puisse pas nuire à votre réputation d’envoi, ce qui prend des mois à reconstruire : * **Jamais de double invitation par défaut.** Une adresse qui a déjà reçu cette enquête est ignorée ; passez `resend: true` uniquement lorsque c’est bien votre intention explicite. * **La suppression est toujours appliquée.** Les adresses désabonnées, rejetées ou ayant signalé un abus ne sont jamais recontactées par e-mail, même si votre système continue de les envoyer. * **Quota glissant sur 24 heures** par organisation (2 000 invitations par défaut ; augmentable sur demande). La vérification du modèle affiche l’utilisation du jour, et les envois au-delà du quota échouent proprement avec `INVITE_QUOTA_EXCEEDED` plutôt que d’être mis en file d’attente. * **Mise en pause automatique en cas de taux de plaintes.** Si les plaintes pour spam augmentent sur une fenêtre de 30 jours, les envois sont suspendus avant que les fournisseurs de boîtes mail ne pénalisent votre domaine. * **1 000 destinataires par appel.** Découpez les listes plus volumineuses en plusieurs appels ; chacun renvoie son propre `distribution_id`. *** ### Rattacher les réponses à vos données Le `external_id` que vous définissez pour chaque destinataire traverse tout le processus : il figure dans les lignes de résultat des destinataires, dans le `invite.bounced` payload, et, comme le lien d’enquête est personnalisé, dans la réponse elle-même. Utilisez le même identifiant que celui que vous utilisez dans [les envois de feedback](/boundaryai-docs/boundaryai-docs-fr/api-et-webhooks/pushing-feedback.md) (`customer_id`) et vous pouvez relier *invité → répondu → ce qu’ils ont dit* entièrement dans votre propre entrepôt de données.