Intégration domotique Google Mail, gratuite et open source

Gmail dans Gladys : notifications par e-mail, réponse d’absence, scènes, widgets.

• Publiée par William-De71
• Messagerie
• Version 0.1.0
• Nécessite Gladys >=5.2.0
• ★ 0

Voir sur GitHubToutes les intégrations

Présentation

Cette intégration relie un compte Gmail à Gladys par l’API Gmail officielle et OAuth 2.0 : aucun mot de passe d’application, et chaque autorisation est choisie et révocable.

• Notifications par e-mail : chaque utilisateur saisit dans « Mon compte » l’adresse qui recevra ses notifications Gladys ; elles partent du compte Gmail connecté (image de caméra jointe si la notification en a une).
• Réponse automatique d’absence : l’activer ou la désactiver depuis une scène (objet, message, dates facultatives, contacts seulement) ou depuis un widget.
• Déclencheur « nouveau mail reçu », filtrable par adresse de l’expéditeur, libellé Gmail et catégorie (Principale, Promotions…), avec l’expéditeur, l’objet, l’extrait et les libellés comme variables.
• Actions de scène : envoyer un mail (destinataires, copie, copie cachée, texte ou HTML simple), lire les mails non lus, marquer comme lu, ajouter un libellé, archiver.
• Widgets : les mails non lus de la boîte de réception ou d’un libellé, et l’état de la réponse d’absence avec ses boutons.
• Cloud : les données transitent entre les serveurs de Google et votre Gladys, avec votre propre client Google ; rien ne passe par un serveur tiers.

Ce qui la distingue des intégrations SMTP et IMAP du store : « SMTP » envoie les notifications par n’importe quel serveur de messagerie (avec un mot de passe d’application pour Gmail), sans déclencheur, widget ni réponse d’absence ; « IMAP Mail » lit jusqu’à trois boîtes avec un mot de passe d’application. Google Mail cible Gmail seul, mais sans mot de passe d’application, avec des autorisations limitées au strict nécessaire (le corps des mails n’est jamais lu), la réponse automatique d’absence, les libellés et catégories Gmail, et l’envoi, la lecture et l’organisation dans une seule intégration.

Prérequis

• Gladys 5.2.0 ou plus récent (formulaires des widgets).
• Un compte Gmail (personnel ou Google Workspace, si l’administrateur autorise les applications tierces).
• Un projet Google Cloud gratuit dans lequel vous créez votre propre client OAuth : Google ne permet pas de partager une clé, et l’intégration n’en embarque aucune. Comptez une dizaine de minutes, une seule fois.

Configuration

1. Projet Google Cloud et API

1. Ouvrez la console Google Cloud et créez un projet (par exemple « Gladys »).
2. Dans API et services → Bibliothèque, cherchez Gmail API et cliquez sur Activer (lien direct).

2. Écran de consentement (Google Auth Platform)

1. Ouvrez Google Auth Platform (lien) et cliquez sur Commencer : nom de l’application (« Gladys »), adresse e-mail d’assistance, audience Externe, adresse de contact, acceptez les conditions, puis Créer.
2. Dans Audience, cliquez sur Publier l’application pour la passer En production. C’est indispensable : une application laissée En test reçoit des autorisations qui expirent au bout de 7 jours, et seuls les utilisateurs test peuvent se connecter.
3. Ne demandez pas la validation de Google : l’application reste « non validée », ce qui convient à un usage personnel (100 utilisateurs au plus). Google affichera un avertissement à la connexion (étape 4). Les autorisations de lecture de Gmail sont dites restreintes : pour une application publique, Google exigerait un audit de sécurité ; pour votre propre application non validée, il affiche seulement un avertissement plus marqué.

3. Client OAuth

1. Dans Google Auth Platform → Clients, cliquez sur Créer un client.

2. Type d’application : Application Web, nom : « Gladys ».

3. Dans URI de redirection autorisés, ajoutez exactement :

   https://my.gladysassistant.com/redirect/oauth

   C’est la page HTTPS de Gladys qui renvoie votre navigateur vers votre instance, quelle que soit son adresse (Google refuse les adresses en http:// et les adresses IP). Si vous accédez à Gladys en HTTPS et activez l’option avancée « adresse de l’instance » de l’écran de configuration, déclarez plutôt l’adresse qu’il affiche.

4. Cliquez sur Créer, puis copiez le Client ID et le Code secret du client (il commence par GOCSPX-).

4. Dans Gladys

1. Ouvrez l’intégration Google Mail, collez le Client ID et le Client secret, choisissez Ce que Gladys peut faire, puis enregistrez.
2. Cliquez sur Se connecter avec Google et choisissez votre compte.
3. Google prévient qu’il n’a pas validé cette application : c’est la vôtre. Cliquez sur Paramètres avancés, puis sur Accéder à Gladys (non sécurisé).
4. Cochez toutes les autorisations Gmail proposées, puis Continuer. Vous revenez dans Gladys, connecté.
5. Chaque utilisateur qui veut recevoir ses notifications par e-mail saisit son adresse dans le bloc Mon compte de la page de l’intégration.

Champ	Par défaut	Rôle
Client ID	—	Le Client ID de votre client OAuth (se termine par .apps.googleusercontent.com).
Client secret	—	Son code secret (GOCSPX-…), jamais affiché ni écrit dans les journaux.
Ce que Gladys peut faire	Lecture	Le niveau d’accès (tableau ci-dessous). Reconnectez-vous après un changement.
Se connecter avec Google	—	Le bouton de connexion.
Chercher les nouveaux mails toutes les (min)	2	De 1 à 60. Chaque vérification coûte 3 unités de quota Gmail, plus 20 par nouveau mail.
Objet des notifications	Gladys	L’objet des mails envoyés comme notifications.
Mon compte → Adresse e-mail	—	Pour chaque utilisateur : l’adresse qui reçoit ses notifications (laissez vide pour ne rien recevoir).

Niveaux d’accès et autorisations

L’intégration ne demande que les autorisations du niveau choisi, les plus étroites que propose Gmail :

Niveau	Autorisations Google	Ce qui fonctionne
Envoi et réponse d’absence seulement	gmail.send, gmail.settings.basic	Notifications, action « envoyer un mail », réponse d’absence (scènes et widget)
+ lire expéditeurs, objets et libellés	les mêmes + gmail.metadata (restreinte)	+ déclencheur « nouveau mail », mails non lus (action et widget), sans extrait
+ lire et organiser	gmail.send, gmail.settings.basic, gmail.modify (restreinte)	+ extrait des mails, marquer comme lu, ajouter un libellé, archiver

gmail.metadata ne donne accès qu’aux en-têtes et aux libellés, jamais au corps des mails. gmail.modify permet de lire les mails et de changer leurs libellés ; l’intégration ne s’en sert que pour l’extrait (snippet) et pour les libellés, et ne supprime jamais rien. Les jetons et le curseur de lecture sont conservés dans /data (le volume de l’intégration), jamais dans les journaux.

Utilisation

Notifications par e-mail

L’intégration est un canal de communication « envoi seul » : quand Gladys envoie un message à un utilisateur (action de scène « Envoyer un message », alertes…), il part par e-mail à l’adresse saisie dans Mon compte, avec l’objet configuré. Une image jointe à la notification (instantané de caméra) est ajoutée en pièce jointe. Gladys ne lit pas les réponses : répondre au mail ne pilote pas la maison.

Widgets

• Mails non lus : le nombre de non lus de la boîte de réception (ou du libellé choisi dans les réglages du widget, par son nom), les cinq plus récents (expéditeur, objet, date, extrait, lien vers Gmail), les boutons Marquer comme lus (niveau « lire et organiser »), Actualiser et Ouvrir Gmail.
• Réponse d’absence : état (activée, programmée, terminée, désactivée), objet, dates, destinataires, avec Activer (formulaire : objet, message, durée en jours, contacts seulement) et Désactiver.

Déclencheur de scène

Gmail : nouveau mail reçu se déclenche pour chaque mail arrivé dans la boîte de réception ou dans un libellé (un filtre Gmail peut ignorer la boîte de réception), vérifié toutes les 2 minutes par défaut. Les brouillons, les mails envoyés, le spam, la corbeille et les mails envoyés par Gladys elle-même ne le déclenchent pas.

• Filtres : adresse de l’expéditeur (exacte, en minuscules), libellé Gmail (le nom exact du premier libellé du mail, ou INBOX pour un mail sans libellé), catégorie (Principale, Réseaux sociaux, Promotions, Notifications, Forums).
• Variables : nom et adresse de l’expéditeur, expéditeur complet, destinataires, objet, extrait (niveau « lire et organiser »), libellé, tous les libellés, catégorie, important, date de réception, identifiant du mail et de la conversation, nombre de non lus de la boîte.

Actions de scène

• Envoyer un mail : destinataires (séparés par des virgules), Cc, Cci, objet, message, format texte ou HTML simple. Sorties : identifiant du mail et de la conversation.
• Activer la réponse d’absence : objet, message, début et fin facultatifs (AAAA-MM-JJ, JJ/MM/AAAA, avec une heure HH:MM facultative, ou +3 pour dans 3 jours ; fuseau horaire de Gladys ; une fin sans heure s’arrête à 23 h 59), contacts seulement. Sorties : début et fin (ISO 8601).
• Désactiver la réponse d’absence : l’objet et le message sont conservés.
• Lire les mails non lus : de la boîte de réception ou d’un libellé. Sorties : nombre, expéditeur, objet et identifiant du plus récent.
• Marquer lu, libeller, archiver : sur l’identifiant d’un mail (la variable du déclencheur), marquer comme lu, ajouter un libellé existant, retirer de la boîte de réception.

Ces actions ne déclenchent jamais le déclencheur « nouveau mail », même un mail envoyé à votre propre adresse.

Exemples de scènes

• Quand un mail arrive de [email protected] → envoyer une notification « Nouvelle facture : {{objet}} » et appliquer le libellé « Factures ».
• Quand le mode de la maison passe à « Vacances » → activer la réponse d’absence jusqu’à +14 ; au retour → la désactiver.
• Quand l’alarme se déclenche → envoyer un mail à toute la famille, avec un message en HTML simple.

Dépannage

• « Erreur 400 : redirect_uri_mismatch » : l’URI de redirection du client OAuth n’est pas identique à celle de Gladys. Vérifiez https://my.gladysassistant.com/redirect/oauth, sans barre finale, dans URI de redirection autorisés d’un client Application Web.
• « Erreur 403 : access_denied » : l’application est encore En test et votre compte n’est pas utilisateur test. Publiez-la (Audience → Publier l’application).
• « Google n’a pas validé cette application » : normal, c’est votre propre application ; Paramètres avancés → Accéder à Gladys (non sécurisé).
• « Google n’a pas accordé toutes les autorisations » : une case n’était pas cochée sur l’écran de consentement, ou le niveau d’accès a changé depuis la connexion. Reconnectez-vous et cochez tout.
• « Google a révoqué l’accès » toutes les semaines : l’application est restée En test (7 jours). Publiez-la, puis reconnectez-vous.
• « L’API Gmail n’est pas activée » : activez Gmail API dans le projet du client OAuth, attendez quelques minutes, puis Tester la connexion.
• Compte Google Workspace : l’administrateur peut bloquer les applications non validées ou les autorisations restreintes ; demandez-lui d’autoriser votre client OAuth.
• Un nouveau mail met quelques minutes à déclencher sa scène : c’est l’intervalle de vérification (2 minutes par défaut).
• Pour un rapport de bug : cliquez sur Diagnostic (résumé anonymisé dans les journaux, sans jeton, adresse ni contenu de mail), puis joignez les journaux de l’intégration, la version de Gladys et celle de l’intégration.

Limites

• Jamais testée avec un vrai compte Google : le code suit la documentation de l’API Gmail et des tests sur un faux Google ; vos retours sont les bienvenus.
• Pas de notification poussée de Gmail (elle passe par Google Cloud Pub/Sub, hors de portée d’un serveur domestique) : un nouveau mail est vu au plus tard après l’intervalle de vérification. Si l’intégration est arrêtée plus d’une semaine environ, Gmail peut refuser l’ancien curseur : les mails reçus entre-temps ne déclenchent rien.
• Au plus 20 nouveaux mails lus par vérification : au-delà (import massif), les plus anciens ne déclenchent rien.
• Le filtre « libellé » compare le premier libellé du mail ; pour un mail qui en a plusieurs, utilisez la variable « tous les libellés » dans une condition.
• Le corps des mails n’est jamais lu ; pas de pièces jointes à l’envoi depuis une scène (seule l’image d’une notification est jointe) ; pas de brouillons ni de suppression.
• Gladys ne reçoit pas de messages par e-mail (canal « envoi seul ») : un mail ne peut pas piloter la maison, sauf par vos propres scènes sur le déclencheur.
• Un seul compte Google par intégration.

Paramètres de configuration

Voici les paramètres demandés par Google Mail dans son écran de configuration dans Gladys.

Paramètre	Type	Obligatoire	Description
1. Votre client OAuth Google Cloud	section	Non	Google ne fournit pas de clé partagée : créez un projet gratuit dans la console Google Cloud, activez l’API Gmail, configurez l’écran de consentement (Externe) et publiez-le « En production » (sinon l’accès expire au bout de 7 jours), puis créez un client OAuth de type « Application Web » dont l’URI de redirection autorisée est exactement https://my.gladysassistant.com/redirect/oauth. La documentation détaille chaque étape.
Client ID	string	Oui	Se termine par .apps.googleusercontent.com.
Client secret	secret	Oui	Affiché par Google à la création du client (il commence par GOCSPX-).
Ce que Gladys peut faire	select	Non	Détermine les autorisations demandées à la connexion : reconnectez-vous après un changement. Lire la boîte (déclencheur, mails non lus) demande une autorisation Gmail « restreinte » : Google affiche un avertissement plus marqué pour votre propre application non validée.
2. Connectez votre compte Google	section	Non	Enregistrez d’abord, puis cliquez sur le bouton. Google prévient qu’il « n’a pas validé cette application » : c’est votre propre application, cliquez sur Paramètres avancés puis Accéder à… (non sécurisé), et cochez toutes les autorisations Gmail. Reconnectez-vous si Gladys signale un accès révoqué.
Se connecter avec Google	oauth2	Non	Gladys ne lit jamais le corps de vos mails et ne supprime jamais rien.
3. Options	section	Non	Chaque utilisateur saisit l’adresse qui recevra ses notifications Gladys dans le bloc « Mon compte » ci-dessous. Avec un accès en lecture, l’intégration relit l’historique de la boîte à intervalle régulier (Gmail ne pousse rien vers un serveur domestique).
Chercher les nouveaux mails toutes les (minutes)	number	Non	Chaque vérification coûte 3 unités de quota Gmail, plus 20 par nouveau mail : très en dessous des limites d’un projet personnel.
Objet des notifications	string	Non	L’objet des mails que Gladys envoie comme notifications.

Comment installer Google Mail dans Gladys

1. Dans Gladys, ouvrez Intégrations : Google Mail apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/william-de71/gladys-google-mail:0.1.0), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration).
3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/William-De71/gladys-google-mail.

Google Mail nécessite Gladys >=5.2.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.

Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.

À propos des intégrations externes

Google Mail est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par William-De71, et non par l'équipe cœur de Gladys.

• Parcourir toutes les intégrations, natives et communautaires
• Créer et publier votre propre intégration externe
• Code source sur GitHub — source de cette documentation

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂