Bookivox Documentation

À quoi ça sert

L’intégration Postmark permet à vos agents d’envoyer un e-mail transactionnel depuis votre serveur Postmark, pendant l’appel. L’agent rédige l’objet et le corps ; le destinataire est fourni par le client. Comme pour les autres intégrations, vous branchez votre propre compte : Bookivox ne fournit aucun identifiant. Vous copiez le jeton du serveur d’envoi, vous indiquez l’adresse expéditrice et le nom affiché, puis vous cochez l’action à exposer.

L’expéditeur est figé dans la connexion : une fois le jeton enregistré, l’agent ne peut pas envoyer depuis une autre adresse. Seuls le destinataire, l’objet et le corps varient d’un appel à l’autre.

Ce qu’il faut préparer

Élément	D’où il vient	Format attendu
Jeton serveur	Postmark : votre serveur → API Tokens	Chaîne de type UUID, ex. `aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa`
Signature d’expédition	Postmark : Sender Signatures, validée par e-mail	L’adresse expéditrice doit être une signature validée sur ce serveur
E-mail expéditeur	Une adresse autorisée sur le serveur	Adresse simple, ex. `contact@votre-domaine.fr`
Nom affiché	Votre choix	Nom que le destinataire voit à côté de l’adresse, ex. `Cabinet Martin`

Postmark refuse un expéditeur qui n’est pas une signature validée du serveur : l’envoi échoue en 403. Validez la signature avant de créer l’intégration.

Connecter Postmark

Choisir le serveur

Dans Postmark, ouvrez le serveur d’envoi qui portera les e-mails de Bookivox.

Copier le jeton

Ouvrez API Tokens et copiez le jeton du serveur (pas celui du compte).

Valider la signature

Dans Sender Signatures, ajoutez l’adresse expéditrice et validez l’e-mail de confirmation.

Saisir le jeton et l'expéditeur

Dans Intégrations → Postmark, collez le jeton, l’e-mail expéditeur et le nom affiché. Le formulaire vérifie le format avant l’enregistrement.

Cocher l'action

Sélectionnez Envoyer un e-mail. Elle devient un outil indépendant.

Vérifier la connexion

Cliquez sur Créer les outils. Bookivox interroge GET /server avec votre jeton : un bandeau vert confirme la création, une erreur est affichée sinon. Le jeton disparaît du formulaire : il reste chiffré.

Attacher l'outil

Rattachez l’outil à un nœud agent. Il s’exécute pendant l’appel.

Ce que l’agent peut faire

Action	Usage	Exemple de demande
Envoyer un e-mail (`send_email`)	Envoie un e-mail HTML et texte depuis l’adresse enregistrée	« Envoyez-moi la confirmation par e-mail. »

L’agent fournit To, Subject, HtmlBody et, s’il le souhaite, TextBody. L’expéditeur (From) n’est jamais un paramètre : il est injecté par la credential.

Cas d’usage

Cas d’usage	Ce que fait l’agent	Résultat pour le client
Confirmer un rendez-vous par écrit	L’agent appelle `send_email` avec `To`, `Subject` et `HtmlBody`.	Le client reçoit la confirmation pendant l’appel, avec l’expéditeur vérifié dans Postmark.
Envoyer un récapitulatif de commande	L’agent appelle `send_email` avec `HtmlBody` et `TextBody`.	Le client garde une trace lisible, même sans rendu HTML.
Transmettre les prérequis d’un rendez-vous	L’agent appelle `send_email` avec les documents et consignes en `HtmlBody`.	Le client arrive préparé, ce qui réduit les rappels.
Adresser un document à un tiers	L’agent envoie le même contenu à l’adresse d’un collaborateur indiqué par le client.	L’information circule sans que le client ait à transférer l’e-mail.

Comment ça marche

Bookivox crée une credential custom_header contenant l’en-tête X-Postmark-Server-Token et un champ de corps From égal à Nom <adresse>.
À chaque appel, le champ From de la credential écrase les arguments produits par le modèle : aucun autre expéditeur n’est possible.
La requête part vers l’URL fixe https://api.postmarkapp.com/email en POST, avec l’en-tête Accept: application/json et un timeout de 10 000 ms.
Un outil http_api est créé avec config.provider = "postmark" et config.operation = "send_email".
Le flux d’envoi par défaut est outbound. Postmark renvoie un identifiant de message que l’outil restitue à l’agent.

Rédiger la description de l’outil

La description décide quand l’agent envoie l’e-mail. Rédigez-la comme une consigne :

Utiliser cet outil quand le client demande à recevoir une confirmation
par e-mail. Toujours demander l'adresse du destinataire, la relire,
puis confirmer l'envoi à voix haute.

Un envoi d’e-mail est irréversible. Précisez dans le prompt de l’agent qu’il doit relire l’adresse du destinataire avant d’appeler l’outil.

Sécurité

Risque	Ce que fait le preset
Jeton exposé	Il vit dans une credential chiffrée, jamais dans la définition de l’outil ni dans un prompt. Il n’est jamais réaffiché.
Usurpation d’expéditeur	`From` est figé dans la credential et écrase toujours les arguments du modèle.
Injection d’en-tête	Le nom affiché refuse les chevrons, guillemets, barres obliques inverses, accolades et retours à la ligne : impossible d’ajouter une seconde adresse.
Mauvais serveur	L’URL est figée sur `https://api.postmarkapp.com` : l’outil ne peut pas viser un autre service.
Format de réponse	L’en-tête `Accept: application/json` est épinglé par le preset : l’agent reçoit du JSON, pas du XML.
Erreur silencieuse	La connexion est testée avant validation : aucune intégration n’est créée tant que Postmark ne répond pas correctement.

Créez un serveur Postmark dédié à Bookivox et régénérez son jeton en cas de doute. Un jeton partagé avec un autre usage ne peut pas être révoqué sans interrompre cet autre usage.

Ce qui est déconseillé

Usage	Pourquoi
Jeton du compte au lieu du serveur	Le jeton de compte n’a pas les droits d’envoi attendus.
Signature non validée	Postmark refuse l’envoi (`403`) tant que la signature n’est pas confirmée.
Adresse expéditrice hors domaine autorisé	Postmark refuse un expéditeur non autorisé sur le serveur.
Nom avec chevrons ou guillemets	Le formulaire le refuse : ces caractères permettraient de réécrire l’en-tête `From`.
Envoi sans confirmation	L’e-mail est irréversible : faites relire l’adresse au client.
Tâches planifiées	Un outil d’agent s’exécute pendant l’appel, pas en tâche de fond.

Limites et dépannage

Symptôme	Cause probable	Correction
Erreur `401`	Jeton erroné ou révoqué.	Recopier le jeton API Tokens du serveur et recréer la connexion.
Erreur `403`	Signature d’expédition non validée.	Valider la signature dans Postmark.
Erreur `422`	Corps malformé : `To`, `Subject`, `HtmlBody` ou `From`.	Vérifier les paramètres produits par l’agent.
Erreur `429`	Trop de requêtes.	Espacer les envois ; Postmark applique ses propres quotas.
Erreur `5xx`	Incident côté Postmark.	Réessayer plus tard ; contacter Postmark si cela dure.
Le test de connexion échoue	Le jeton ne correspond pas à un serveur actif.	Vérifier que le serveur existe et que le jeton est bien celui du serveur.
L’agent répond « de tête »	L’outil n’est pas attaché à l’agent, ou il est inactif.	L’activer et l’attacher au nœud agent.

Intégrations

Toutes les intégrations et les catégories d’outils.

API HTTP

Comprendre les outils HTTP : paramètres, presets, credentials.

Prise en main

LABS

Construire

Préparer

Piloter

Revendeur (White-label)

Intégration : Postmark

À quoi ça sert

Ce qu’il faut préparer

Connecter Postmark

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage

Intégrations

API HTTP

​À quoi ça sert

​Ce qu’il faut préparer

​Connecter Postmark

​Ce que l’agent peut faire

​Cas d’usage

​Comment ça marche

​Rédiger la description de l’outil

​Sécurité

​Ce qui est déconseillé

​Limites et dépannage

Intégrations

API HTTP

À quoi ça sert

Ce qu’il faut préparer

Connecter Postmark

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage