> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookivox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégration : Maileroo

> Connectez Maileroo à Bookivox pour que vos agents envoient un e-mail depuis votre domaine Maileroo pendant l'appel.

## À 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.

> [!NOTE]
>
> 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` |

> [!NOTE]
>
> 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

**1. Vérifier le domaine**

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

**2. 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.

**3. 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.

**4. Cocher l'action**

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

**5. 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.

**6. 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é.

> [!NOTE]
>
> 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

1. Bookivox crée une **credential** `custom_header` contenant l'en-tête
   `Authorization: Bearer <clé d'envoi>`.
2. 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.
3. À chaque appel, ce preset **écrase** les arguments produits par le modèle :
   aucun autre expéditeur n'est possible.
4. La requête part vers l'URL fixe `https://smtp.maileroo.com/api/v2/emails` en
   `POST`, avec un **timeout de 10 000 ms**.
5. Un **outil `http_api`** est créé avec `config.provider = "maileroo"` et
   `config.operation = "send_email"`.
6. 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.
```

> [!WARNING]
>
> 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. |

> [!WARNING]
>
> **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. |

> [card] [Intégrations](https://docs.bookivox.com/integrations/overview.md)
>
> Toutes les intégrations et les catégories d'outils.

> [card] [API HTTP](https://docs.bookivox.com/integrations/http-api.md)
>
> Comprendre les outils HTTP : paramètres, presets, credentials.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.