Relier des boîtes mail

Comment fonctionne la connexion d'une boîte mail

Campbooks lit et envoie Gmail et Zoho Mail via l'API du fournisseur lui-même. Toute autre boîte mail (Yahoo, AOL, iCloud, Fastmail, GMX, WEB.DE, Yandex, un domaine personnalisé) se connecte en IMAP et SMTP avec un mot de passe d'application : voir Boîtes mail IMAP. Outlook et Microsoft 365 arrivent bientôt.

Pour Gmail et Zoho, il n'y a rien de plus à enregistrer. Le client OAuth que vous avez configuré pour la Connexion est le même client que celui qui relie la boîte mail. Il utilise la même URI de redirection, le même ID client et le même fichier de secret. Un fournisseur propose la liaison du courrier dès que son client est configuré, pas avant.

• Ajouter une boîte mail. Dans l'application, ouvrez Réglages, puis Boîtes mail, et choisissez Ajouter une boîte mail. L'adresse est demandée d'abord. Une adresse Gmail ou Zoho passe à l'écran de consentement du fournisseur, qui demande l'accès au courrier ; toute autre adresse reçoit l'étape du mot de passe d'application. Gmail et Zoho ne sont proposés que lorsque votre instance a configuré leur client. Étapes pour les membres : Connecter votre boîte aux lettres.
• Se connecter aussi avec ce compte. L'étape de liaison comporte une case, « Utiliser aussi ce compte pour se connecter », cochée par défaut. Décochez-la pour une boîte partagée, comme support@. Elle est reliée, mais ne devient jamais un moyen de connexion.
• Qui la voit. Une liaison appartient à l'espace de travail et enregistre qui l'a faite. Les propriétaires et les administrateurs voient toutes les boîtes mail de l'espace de travail.
• Identifiants. L'autorisation que Campbooks reçoit du fournisseur, ou le mot de passe d'une boîte mail IMAP, est scellée avec la clé secrète de l'instance. Si vous perdez la clé, les liaisons ne peuvent plus être ouvertes et chaque personne doit les refaire. Voir La clé secrète de l'instance.
• Déconnecter. Déconnecter arrête la synchronisation et révoque l'autorisation chez le fournisseur. Vous choisissez si les e-mails déjà dans Campbooks sont supprimés (par défaut) ou gardés en historique en lecture seule. Les e-mails chez Gmail ou Zoho ne sont jamais touchés. Quitter l'espace de travail, ou le supprimer, révoque aussi les autorisations.
• État. Chaque boîte mail affiche l'un de quatre états : Synchronisation en cours, Le membre doit la reconnecter, Ralentie par le fournisseur ou En échec. Une boîte qui doit être reconnectée a un bouton Reconnecter pour la personne qui l'a reliée.

Relier du courrier demande la connexion intégrée. Si vous définissez CAMPBOOKS_AUTH__ISSUER sur un émetteur externe, la liaison des boîtes mail est désactivée.

Gmail

Cela fonctionne avec Gmail personnel et avec les comptes Google Workspace.

Ce que Campbooks demande à Google

Campbooks demande openid, email et profile pour identifier le compte, et un scope Gmail :

https://www.googleapis.com/auth/gmail.modify

Ce scope lit le courrier, modifie les libellés et envoie. Il ne peut pas supprimer de courrier définitivement.

Configurer le projet Google Cloud

1. Dans la console Google Cloud, créez un projet, ou choisissez celui que vous utilisez pour la connexion.

2. Ouvrez APIs & Services, puis Library, et activez la Gmail API pour ce projet. Sans elle, Google refuse toutes les requêtes de courrier.

3. Ouvrez OAuth consent screen (dans les consoles récentes, Google Auth Platform). Choisissez le type d'utilisateur :

   • External pour les comptes Gmail personnels, ou pour des utilisateurs Workspace extérieurs à votre organisation.
   • Internal si toutes les personnes qui vont se relier sont dans votre propre organisation Google Workspace. Une application interne n'a pas besoin de validation.

4. Ajoutez les scopes openid, email, profile et https://www.googleapis.com/auth/gmail.modify.

5. Définissez l'état de publication. Voir la section suivante.

6. Ouvrez Credentials, puis Create credentials, puis OAuth client ID. Choisissez Web application et ajoutez cette URI de redirection autorisée :

   https://campbooks.example.com/auth/callback/google

   Utilisez votre propre CAMPBOOKS_PUBLIC_URL. L'URI doit correspondre exactement, sans barre oblique finale.

7. Mettez l'ID client dans .env et le secret du client dans deploy/secrets/google-client-secret, puis lancez docker compose up -d. Les permissions du fichier et les lignes de .env sont celles de Se connecter avec Google, Microsoft ou Zoho :

   CAMPBOOKS_GOOGLE__CLIENT_ID=your-client-id
   CAMPBOOKS_GOOGLE__CLIENT_SECRET_FILE=/run/secrets/campbooks/google-client-secret

Testing, publication et validation

Google traite gmail.modify comme un scope restreint. Cela décide qui peut se relier :

• Testing. Seuls les utilisateurs de test que vous listez peuvent se relier, jusqu'à 100. Les refresh tokens durent 7 jours : toutes les liaisons s'arrêtent donc au bout d'une semaine et doivent être refaites. N'utilisez Testing que pour essayer.
• En production, non validée. Tout le monde peut se relier, mais voit l'écran « Google n'a pas validé cette application » et doit choisir Avancé puis continuer. Les refresh tokens n'expirent pas au bout de 7 jours. Pour une instance personnelle avec peu d'utilisateurs, c'est en général acceptable. Google limite aussi les applications non validées à 100 utilisateurs au total.
• En production, validée. Google retire l'avertissement après avoir examiné l'application. Pour un scope restreint, Google exige une évaluation de sécurité. Cela vaut rarement la peine pour une instance auto-hébergée.

Pour une configuration durable, publiez l'application (Publish app sur l'écran de consentement) et acceptez l'avertissement.

Comment il se synchronise

Campbooks interroge Gmail à intervalles réguliers. Il n'y a pas de push à configurer ni rien à enregistrer chez Google pour cela. Après une synchronisation qui a trouvé des changements, la suivante a lieu dans la minute. Quand rien ne change, l'intervalle s'allonge, jusqu'à quatre heures. Une nouvelle liaison lit par défaut les 90 derniers jours. Vous pouvez changer cela dans le Réglage fin.

Zoho Mail

Ce que Campbooks demande à Zoho

Campbooks demande openid, email et profile, et quatre scopes Zoho Mail :

Scope	À quoi il sert
ZohoMail.accounts.READ	Lister les comptes mail de l'identifiant.
ZohoMail.folders.READ	Lire les dossiers.
ZohoMail.messages.ALL	Lire, modifier et envoyer des messages.
ZohoMail.tags.ALL	Lire et créer des libellés, pour les flux.

L'écran de consentement de Zoho est tout ou rien. Si un scope manque dans l'autorisation, Campbooks la refuse et vous demande de relier de nouveau.

Configurer l'application Zoho

1. Ouvrez la console API de Zoho de votre région, par exemple https://api-console.zoho.eu pour l'Europe. Ajoutez un client de type Server-based Applications.

2. Activez Multi-DC, pour qu'un seul client fonctionne dans tous les centres de données Zoho. Sans lui, le client ne fonctionne que dans le centre de données où vous l'avez créé.

3. Ajoutez l'URI de redirection :

   https://campbooks.example.com/auth/callback/zoho

4. Une application Zoho de type serveur reçoit ses scopes à chaque requête : il n'y a donc rien de plus à enregistrer pour eux.

5. Mettez l'ID client dans .env et le secret du client dans deploy/secrets/zoho-client-secret, puis lancez docker compose up -d :

   CAMPBOOKS_ZOHO__CLIENT_ID=your-client-id
   CAMPBOOKS_ZOHO__CLIENT_SECRET_FILE=/run/secrets/campbooks/zoho-client-secret

Centres de données

Zoho garde chaque compte dans un centre de données, et Campbooks y lit le courrier. Ces serveurs de comptes sont acceptés :

Région	Serveur de comptes
États-Unis	https://accounts.zoho.com (par défaut)
Europe	https://accounts.zoho.eu
Inde	https://accounts.zoho.in
Australie	https://accounts.zoho.com.au
Japon	https://accounts.zoho.jp
Canada	https://accounts.zoho.ca
Arabie saoudite	https://accounts.zoho.sa
Royaume-Uni	https://accounts.zoho.uk

Avec Multi-DC activé, laissez CAMPBOOKS_ZOHO__ACCOUNTS_SERVER non défini. Sans Multi-DC, définissez-le sur le serveur de comptes du centre de données où vous avez enregistré le client :

CAMPBOOKS_ZOHO__ACCOUNTS_SERVER=https://accounts.zoho.eu

Plusieurs comptes mail sous un même identifiant

Un identifiant Zoho peut avoir plusieurs comptes mail. Chaque compte mail devient sa propre boîte de réception dans Campbooks. Une personne peut relier plus d'un identifiant Zoho.

Quand quelqu'un s'inscrit avec Zoho, Zoho demande une seconde fois l'accès au courrier, et seulement si le compte est nouveau. Se reconnecter ne le demande jamais.

Reconnecter une fois, pour les libellés

Les liaisons Zoho faites avant l'ajout du scope des libellés continuent de se synchroniser, mais sans libellés ni flux. Pour les obtenir, reconnectez la boîte mail une fois depuis Réglages, puis Boîtes mail. Campbooks ajoute alors des libellés Campbooks/<Flux> dans Zoho pour les flux auxquels Zoho n'offre pas de place propre.

Comment il se synchronise

Campbooks interroge Zoho à intervalles réguliers, car Zoho n'a pas de push. Zoho n'a pas non plus de journal des changements : Campbooks relit donc aussi toute la fenêtre de chaque boîte mail toutes les 6 heures par défaut. Il respecte 60 requêtes par minute pour chaque identifiant Zoho. Changez cela dans le Réglage fin.

Réglage fin

Tout cela est facultatif, et les valeurs par défaut conviennent à la plupart des instances. Ajoutez-les à .env et lancez docker compose up -d. Elles sont aussi listées dans Configuration.

Variable	Valeur par défaut	Rôle
CAMPBOOKS_CONNECTORS__GMAIL__BACKFILL_DAYS	90	Jusqu'où lit une nouvelle liaison Gmail. De 1 à 3650.
CAMPBOOKS_CONNECTORS__POLL__MIN_SECONDS	60	Intervalle après une synchronisation qui a trouvé des changements.
CAMPBOOKS_CONNECTORS__POLL__MAX_SECONDS	14400	Intervalle le plus long d'une boîte mail inactive.
CAMPBOOKS_CONNECTORS__ZOHO__BACKFILL_DAYS	90	Jusqu'où lit une nouvelle boîte Zoho. De 1 à 3650.
CAMPBOOKS_CONNECTORS__ZOHO__REQUESTS_PER_MINUTE	60	Requêtes que chaque identifiant Zoho peut faire par minute.
CAMPBOOKS_CONNECTORS__ZOHO__SWEEP_MINUTES	360	Minutes entre deux relectures complètes de la fenêtre d'une boîte Zoho.

Les limites de taille, le budget de quota Google et les seuils d'échec sont dans Configuration.

Dépannage

Ce que vous voyez	Cause et solution
Google : Error 400: redirect_uri_mismatch	L'URI de redirection du client Google n'est pas exactement ${CAMPBOOKS_PUBLIC_URL}/auth/callback/google. Vérifiez le https://, l'hôte et l'absence de barre oblique finale.
Google : access_denied, ou « This app is blocked » ou « has not completed the Google verification process »	L'application est en Testing et la personne n'est pas un utilisateur de test. Ajoutez-la aux utilisateurs de test de l'écran de consentement, ou publiez l'application.
Google : la synchronisation échoue avec 403 accessNotConfigured, ou « Gmail API has not been used in project »	La Gmail API n'est pas activée dans le projet qui possède le client. Activez-la dans APIs & Services, puis Library, et attendez quelques minutes.
Google : les liaisons s'arrêtent au bout de 7 jours environ	L'application est en Testing, qui limite les refresh tokens à 7 jours. Publiez l'application, puis reliez de nouveau chaque boîte mail.
Zoho : invalid_client	Le client a été enregistré dans un autre centre de données. Activez Multi-DC, ou définissez CAMPBOOKS_ZOHO__ACCOUNTS_SERVER sur le serveur de comptes du centre de données où vous avez créé le client.
Zoho : une erreur de redirection sur l'écran de consentement	L'URI de redirection du client Zoho n'est pas exactement ${CAMPBOOKS_PUBLIC_URL}/auth/callback/zoho.
« Campbooks n'a pas reçu l'accès à ce que vous avez choisi »	La personne a laissé de côté une permission sur l'écran de consentement. Reliez de nouveau et autorisez tout.
« Le membre doit la reconnecter » sur une boîte mail	Le fournisseur a révoqué l'autorisation ou elle a expiré. La personne qui l'a reliée choisit Reconnecter (ou appuie sur R) dans Réglages, puis Boîtes mail.
« Campbooks ne reconnaît pas le centre de données Zoho de ce compte »	Le compte est dans un centre de données absent de la liste ci-dessus.
Le fournisseur n'est pas proposé sous Relier	Son ID client ou son secret n'est pas défini, ou le serveur n'a pas été redémarré. Vérifiez docker compose logs server.

Autres boîtes mail

Toute autre boîte mail se connecte en IMAP et SMTP avec un mot de passe d'application. C'est activé par défaut et il suffit de la clé secrète de l'instance. Voir Boîtes mail IMAP. Le courrier Outlook ou Microsoft 365 arrive bientôt.