Bookivox Documentation

À quoi ça sert

L’intégration Maileroo permet à vos agents d’envoyer un e-mail depuis votre domaine vérifié, 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 créez une clé d’envoi dans Maileroo, 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 la clé enregistrée, 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
Clé d’envoi	Maileroo : Domains → Sending Keys	Chaîne affichée une seule fois à sa création
Domaine vérifié	Maileroo : Domains, avec les enregistrements DNS validés	Le domaine de l’adresse expéditrice doit être vérifié
E-mail expéditeur	Votre choix, sur le domaine vérifié	Adresse simple, ex. `contact@votre-domaine.fr`
Nom affiché	Votre choix	Nom que le destinataire voit à côté de l’adresse, ex. `Cabinet Martin`

La vérification de connexion liste les e-mails planifiés de votre domaine. Une clé rattachée à un domaine évite toute restriction ; une clé rattachée à l’application exige un domaine lié, que Bookivox déduit automatiquement de l’adresse expéditrice.

Connecter Maileroo

Vérifier le domaine

Dans Maileroo, ouvrez Domains, ajoutez votre domaine et validez les enregistrements DNS.

Créer la clé d'envoi

Dans Domains → Sending Keys, créez une clé dédiée à Bookivox et copiez-la immédiatement : elle n’est plus affichée ensuite.

Saisir la clé et l'expéditeur

Dans Intégrations → Maileroo, collez la clé, 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 les e-mails planifiés de votre domaine avec votre clé : un bandeau vert confirme la création, une erreur est affichée sinon. La clé disparaît du formulaire : elle reste chiffrée.

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 le récapitulatif par e-mail. »

L’agent fournit to, subject, html et, s’il le souhaite, plain. L’expéditeur (from) n’est jamais un paramètre : il est injecté par le preset figé.

Chez Maileroo, to est un objet : { "address": "client@exemple.fr", "display_name": "Nom" }. address est obligatoire ; display_name est facultatif.

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` sous forme d’objet, un `subject` et un `html`.	Le client reçoit la confirmation pendant l’appel, avec le nom d’expéditeur attendu.
Envoyer un récapitulatif de commande	L’agent appelle `send_email` avec le détail en `html` et une version `plain`.	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 `html`.	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, avec `display_name`.	Le destinataire voit un nom lisible plutôt qu’une adresse brute.

Comment ça marche

Bookivox crée une credential custom_header contenant l’en-tête Authorization: Bearer <clé d'envoi>.
L’expéditeur est figé dans un paramètre preset de type objet : from = { "address": "…", "display_name": "…" }, construit à partir des valeurs saisies par le client.
À chaque appel, ce preset écrase les arguments produits par le modèle : aucun autre expéditeur n’est possible.
La requête part vers l’URL fixe https://smtp.maileroo.com/api/v2/emails en POST, avec un timeout de 10 000 ms.
Un outil http_api est créé avec config.provider = "maileroo" et config.operation = "send_email".
Si vous ajoutez une action à la même connexion plus tard, Bookivox relit l’identité d’expédition déjà enregistrée : vous n’avez pas à la ressaisir.

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 un récapitulatif
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
Clé exposée	Elle vit dans une credential chiffrée, jamais dans la définition de l’outil ni dans un prompt. Elle n’est jamais réaffichée.
Usurpation d’expéditeur	`from` est figé dans un preset objet 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 domaine	L’URL est figée sur `https://smtp.maileroo.com/api/v2` : l’outil ne peut pas viser un autre service.
Erreur silencieuse	La connexion est testée avant validation : aucune intégration n’est créée tant que Maileroo ne répond pas correctement.

Créez une clé dédiée à Bookivox et révoquez-la en cas de doute depuis Maileroo. Une clé partagée avec un autre usage ne peut pas être révoquée sans interrompre cet autre usage.

Ce qui est déconseillé

Usage	Pourquoi
Domaine non vérifié	Maileroo refuse l’envoi tant que le domaine n’est pas validé.
Clé d’application sans domaine lié	Le test de connexion échoue : la clé doit pouvoir lister un domaine.
Adresse expéditrice hors domaine	Maileroo refuse une adresse qui n’appartient pas à un domaine vérifié.
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`	Clé erronée ou révoquée.	Recréer une clé d’envoi et recréer la connexion.
Erreur `403`	Domaine non vérifié, ou clé non rattachée à ce domaine.	Valider le domaine et recréer une clé sur ce domaine.
Erreur `422`	Corps malformé : `to`, `subject` ou `html` manquant, ou `to` mal formé.	Vérifier les paramètres produits par l’agent.
Erreur `429`	Trop de requêtes.	Espacer les envois ; Maileroo applique ses propres quotas.
Erreur `5xx`	Incident côté Maileroo.	Réessayer plus tard ; contacter Maileroo si cela dure.
Le test échoue : « domaine requis »	Clé rattachée à l’application sans domaine lié.	Utiliser une clé rattachée à un domaine, ou saisir une adresse expéditrice sur un domaine lié.
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 : Maileroo

À quoi ça sert

Ce qu’il faut préparer

Connecter Maileroo

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 Maileroo

​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 Maileroo

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