LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Outlook
Google Agenda
Rejoindre la communauté SlackAPI Gmail Notifications push: Guide Complet de Pub/Sub, Watch & History (2026)
Configurer les notifications push de l'API Gmail de bout en bout : créer un sujet Pub/Sub, enregistrer un point de terminaison de surveillance, décoder les charges utiles des webhooks, réconcilier les changements avec historique.utilisateurs.liste, automatiser le renouvellement des montres et éviter entièrement la configuration GCP avec une alternative de webhook unifiée.
// 1. Enregistrer la surveillance Gmail via Unipile
const res = await fetch('https://api8.unipile.com:13815/api/v1'
+ '/comptes/{id}/regarder', {
method: POST,
headers: {
'X-API-KEY': 'VOTRE_CLÉ_API',
'Content-Type': 'application/json'
},
body: JSON.filtrer({
URL de webhook : 'https://app.you.com/webhooks/gmail'
})
});
2. Recevoir la charge utile unifiée du webhook
application.poste('/webhooks/gmail', (req, res) => {
const { événement, identifiant_compte, e-mail } = req.body;
// événement : "nouveau_courrier" | historyId abstrait
gérerNouvelE-mail(courriel);
});Quelles sont les notifications push de l'API Gmail ?
Avant de mettre en œuvre les notifications push de l'API Gmail en production, il est utile de comprendre exactement ce qu'elles sont, en quoi elles diffèrent d'une simple interrogation (polling) et quelle infrastructure elles nécessitent.
Les notifications push de l'API Gmail sont un mécanisme de livraison en temps réel qui utilise Google Cloud Pub/Sub pour envoyer des événements de modification de boîte aux lettres à un point de terminaison HTTPS contrôlé par le développeur. Lorsqu'un nouveau message arrive ou qu'un message existant est modifié, Gmail publie une notification contenant un flux encodé identifiantHistorique à un sujet Pub/Sub que vous possédez, qui transmet ensuite cet événement à votre webhook. Votre serveur appelle historique.utilisateurs.liste pour récupérer les modifications réelles.
Les notifications push de l'API Gmail éliminent le besoin de rappeler à plusieurs reprises messages.liste sur une base planifiée. Les événements sont livrés dans les secondes suivant la modification de la boîte aux lettres, réduisant ainsi la latence et l'utilisation des quotas d'API.
Le canal de distribution est Google Cloud Pub/Sub, et non un rappel HTTP direct de Gmail. Cela ajoute de la durabilité : si votre point de terminaison est temporairement indisponible, Pub/Sub peut retenter la distribution conformément à son délai de confirmation d'abonnement.
Un point de terminaison de "watch" de l'API Gmail expire après 7 jours. Votre application doit le renouveler de manière proactive avec un cron job quotidien ou risquer de manquer des événements silencieusement. Il s'agit d'un détail opérationnel critique couvert dans la section "Renouvellement".
Les notifications push de l'API Gmail diffusent les événements dans les 1 à 10 secondes suivant le changement. L'absence d'interrogation constante signifie une consommation de quota plus faible sur l'API Gmail et un temps de réaction plus rapide pour votre application. Idéal pour tout cas d'utilisation en temps réel au niveau de la boîte de réception : synchronisation CRM, systèmes de billetterie, automatisation des flux de travail.
Sondage messages.liste toutes les 60 secondes est plus simple à configurer, mais introduit un délai artificiel, gaspille le quota sur des réponses vides et évolue mal pour un grand nombre de comptes d'utilisateurs authentifiés. Acceptable uniquement pour les prototypes à faible volume.
Architecture : watch + Pub/Sub + historyId dans un seul flux
Les notifications push de l'API Gmail impliquent quatre couches distinctes fonctionnant en séquence. Comprendre chaque couche avant d'écrire du code permet d'éviter les erreurs d'implémentation les plus courantes.
Vous publiez sur https://gmail.googleapis.com/gmail/v1/users/me/watch avec le nom de votre sujet Pub/Sub et éventuellement un filtre d'étiquette. Gmail renvoie une identifiantHistorique et un expiration Horodatage Unix. Stocker les deux. Cette montre expire dans 7 jours.
Chaque fois qu'un changement survient dans la boîte aux lettres surveillée (nouveau message, changement d'étiquette, basculement lecture/non lu), Gmail publie une notification JSON sur votre sujet Cloud Pub/Sub. La charge utile est un objet encodé en base64 contenant l'adresse e-mail de l'utilisateur et un nouveau identifiantHistorique.
Votre abonnement Pub/Sub transfère le message à un point de terminaison push HTTPS enregistré. Il s'agit de votre URL de webhook, qui doit répondre avec un code HTTP 200-299 dans le délai d'accusé de réception (par défaut 10 à 600 secondes). Une réponse non 2xx déclenche des nouvelles tentatives automatiques.
Décoder les données du message Pub/Sub en base64. Extraire le nouveau identifiantHistorique. Comparez-le à dernierIdHistorique stockées dans votre base de données pour cet utilisateur.
Appel historique.utilisateurs.liste avec identifiantDébutHistorique à votre valeur stockée. Gmail renvoie toutes les modifications (nouveaux messages, ajouts d'étiquettes, suppressions) entre les deux identifiants. Mettez à jour votre stock dernierIdHistorique à la nouvelle valeur. N'utilisez jamais l'historyId de la notification Pub/Sub comme identifiantDébutHistorique directement.
Planifier une tâche cron quotidienne pour appeler utilisateurs.regarder à nouveau pour chaque compte utilisateur authentifié. Le renouvellement de la surveillance est idempotent : un nouvel appel remplace l'expiration précédente. Le retour identifiantHistorique devient votre nouvelle référence.
Un entier à croissance monotone attribué par Gmail à chaque modification de boîte aux lettres. C'est votre curseur pour la synchronisation incrémentielle. Stockez toujours le dernier historyId par utilisateur dans votre base de données.
Le point de terminaison de l'API Gmail qui enregistre un abonnement de notification push pour une boîte aux lettres. Renvoie une base d'historique d'historique et un horodatage d'expiration Unix en ms. Doit être renouvelé dans les 7 jours.
Le point de terminaison de réconciliation. Compte tenu d'un startHistoryId, il renvoie toutes les additions, suppressions et changements d'étiquettes de messages qui se sont produits après ce point. C'est là que vous obtenez les données de message réelles.
Prérequis : Projet GCP, sujet Pub/Sub, autorisation IAM
Les notifications push de l'API Gmail nécessitent trois ressources côté GCP avant votre premier utilisateurs.regarder L'échec de la plupart des implémentations remonte à une autorisation IAM manquante sur le sujet Pub/Sub, l'étape que les développeurs oublient le plus souvent.
Dans la Google Cloud Console, créez ou sélectionnez un projet existant. Naviguez vers APIs et services > Bibliothèque et activer le API Gmail. Il vous faut également le API Cloud Pub/Sub activé dans le même projet. Assurez-vous que vos identifiants client OAuth 2.0 incluent https://www.googleapis.com/auth/gmail.readonly portée (ou une portée plus large si vous avez besoin d'un accès en écriture). Pour les applications multi-utilisateurs, consultez notre guide sur Intégration de Gmail via OAuth 2.0 et le Vérification de l'application Google OAuth exigences.
Dans la console GCP, sous Pub/Sub > Rubriques, cliquer Créer un sujet. Donnez-lui un nom comme notifications Gmail. Le nom complet du sujet sera projects/VOTRE_PROJECT_ID/topics/notifications-gmail. Vous transmettrez exactement cette chaîne à utilisateurs.regarder dans le titre du sujet champ.
C'est l'étape que la plupart des développeurs oublient. Gmail utilise un compte de service géré par Google (gmail-api-push@system.gserviceaccount.com) pour publier des notifications sur votre sujet Pub/Sub. Sans accorder à ce compte les Éditeur Pub/Sub rôle dans votre sujet, utilisateurs.regarder réussirat, mais aucune notification ne sera jamais délivrée. Dans la console : Topics > sélectionnez votre topic > Permissions > Add principal > entrez gmail-api-push@system.gserviceaccount.com > attribuer un rôle Éditeur Pub/Sub.
Sous votre rubrique Pub/Sub, créez un Abonnement aux notifications push. Configurez le point de terminaison de notification vers l'URL de votre webhook HTTPS (doit utiliser un certificat TLS valide, les certificats auto-signés sont rejetés). Vous pouvez éventuellement configurer un en-tête de validation de jeton afin que votre point de terminaison puisse vérifier que les requêtes proviennent de Google. Notez le nom de l'abonnement, vous pourriez en avoir besoin pour surveiller les métriques de livraison dans Cloud Monitoring.
Limite de 100 utilisateurs pour les applications non vérifiées : Si votre écran de consentement OAuth est en mode " Test ", seuls 100 comptes Gmail peuvent autoriser votre application. Cette limite s'applique à tous Les champs d'application OAuth, y compris le point de terminaison « watch ». Pour les déploiements en production comptant plus de 100 utilisateurs, vous devez suivre la procédure de vérification de Google. Consultez notre guide complet sur le limite de 100 utilisateurs et chemin de vérification.
Pas de sujet Pub/Sub. Pas d'autorisation IAM. Pas de tâche cron pour le renouvellement de la surveillance tous les 7 jours. Créez des notifications push Gmail à l'aide d'une seule URL de webhook.
Pas à pas : créer un sujet, un abonnement et watch de l'utilisateur
Avec les prérequis GCP en place, voici le code complet pour enregistrer un point de terminaison de surveillance de l'API Gmail en Node.js et Python, en utilisant la bibliothèque cliente Google API.
const { google } = require('googleapis');
// Suppose que le client OAuth2 est déjà autorisé avec un jeton d'accès valide
// Voir : https://www.unipile.com/gmail-oauth-20-integration-complete-guide/
async function enregistrerGmailWatch(authentification, utilisateurId = moi) {
const gmail = Google.gmail({ version : 'v1', auth }) ;
const response = await gmail.utilisateurs.regarder({
identifiantUtilisateur,
CorpsDeLaRequête: {
// Le nom complet de votre sujet Pub/Sub
Nom du sujet : 'projects/YOUR_PROJECT_ID/topics/gmail-notifications',
// Facultatif : filtrer uniquement sur des étiquettes spécifiques
labelIds : ['BOÎTE DE RÉCEPTION'],
labelFiltreComportement : 'INCLURE'
}
});
const { historyId, expiration } = response.data;
// Enregistrez ces données par utilisateur dans votre base de données
await bd.insertion ou mise à jour({
identifiantUtilisateur,
lastHistoryId : historyId,
// La date d'expiration est exprimée sous forme d'horodatage Unix en millisecondes
expirationDeLaVeille: new Date(parseIntexpiration
});
console.log(`Surveillance enregistrée. historyId : ${historyId}, expiration : ${expiration}`);
return response.data ;
}from googleapiclient.discovery import construire
from google.oauth2.credentials import Indentifications
déf s'inscrire_gmail_regarderidentifiants : Identifiants, id_utilisateur : chaîne = moi) -> dict:
"Enregistrer les notifications push de l'API Gmail pour une requête d'utilisateur authentifié."
service = construire('Gmail', 'v1', identifiants=identifiants)
corps = {
'nomSujet': 'projects/YOUR_PROJECT_ID/topics/gmail-notifications',
'labelIds': ['BOÎTE DE RÉCEPTION'],
'Comportement du filtre d'étiquettes': 'INCLURE'
}
résultat = service.utilisateurs().regarder(userId=user_id, corps=corps).exécutez()
# : Enregistrer les données par utilisateur dans votre base de données
db_upsert(user_id=user_id,
last_history_id=résultat['identifiant historique'],
expiration_de_la_montre=entier(résultat['expiration']) // 1000)
return résultatGérer la charge utile de la notification push de l'API Gmail
Lorsqu'un e-mail déclenche une notification push Gmail, votre point de terminaison HTTPS reçoit un message push Pub/Sub. Les données de changement réelles de Gmail sont doublement encodées : l'enveloppe Pub/Sub contient une chaîne JSON encodée en base64 qui contient elle-même l'e-mail de l'utilisateur et l'history_id.
application.poste('/webhooks/gmail', async (req, res) => {
Accuser réception immédiatement : tentatives de Pub/Sub sur les codes non 2xx
res.statut(200).Fin();
essayer {
const message = req.body.message;
si (!message?.data) retourner ;
// Décoder le champ de données Pub/Sub encodé en base64
const décodé =
Tampon.from(message.données, base64).toString('utf-8');
const charge utile = JSON.analyser(décodé);
// payload = { emailAddress: "user@gmail.com", historyId: "12345" }
const { emailAddress, historyId } = chargeutile;
// Réconciliation de la file d'attente (ne pas bloquer l'accusé de réception)
await file.enfiler({ adresseCourriel, historiqueId });
} catch (err) {
// Enregistrer mais ne pas relancer : ack a déjà été envoyé
console.erreur('Erreur d'analyse du webhook', err);
}
});import base64, json
from flasque import Flask, requête, jsonify
appliquer Flasque(__name__)
@app.itinéraire('/webhooks/gmail', méthodes=[POST])
déf gmail_webhook():
# Répondre immédiatement
données = requête.get_json(silencieux=Vrai) ou {}
message = donnée.obtenir('message', {})
si 'données' en message :
# : Décoder le format Base64 et analyser le JSON
brut = base64.b64decodermessage['données'] + '==')
charge utile = json.chargescru
# { "emailAddress": "user@gmail.com", "historyId": "12345" }
e-mail = charge utile.obtenir('adresse électronique')
history_id = payload.obtenir('identifiant historique')
# Mise en file d'attente du rapprochement asynchrone
mettre en attente de réconciliation(e-mail, id_historique)
return jsonify({}), 200Rapprochement des changements avec les utilisateurs.historique.lister
La notification Pub/Sub vous dit seulement quelque chose a changé. Il ne vous dit pas quoi. Vous devez appeler historique.utilisateurs.liste avec votre stocké dernierIdHistorique en tant que curseur pour obtenir le delta réel.
async function réconcilierHistorique(auth, adresseCourriel, nouvelIdHistorique) {
const gmail = Google.gmail({ version : 'v1', auth }) ;
// Récupérer notre lastHistoryId stocké pour cet utilisateur
const utilisateur = await bd.trouverParEmail(adresseCourriel);
const startHistoryId=user.lastHistoryId;
essayer {
const response = await gmail.users.history.list({
userId : moi,
// Utiliser l'ID stocké comme curseur : PAS le nouvel historique des notifications historyId
débutIdentifiantHistorique,
// Filtrer uniquement les ajouts de messages (facultatif)
typesD'histoire : ['messageAjouté']
});
const histories = response.data.history || [];
pour (const (registre des histoires) {
pour (const added of (record.messagesAdded || [])) {
// added.message = { id, threadId, labelIds }
await traiterNouveauMessage(auth, id.du.message.ajouté) ;
}
}
// Mettre à jour le curseur vers le nouvel historyId de la notification
await bd.miseAJourDernierIdHistorique(adresseEmail, nouvelIdentifiantHistorique);
} catch (err) {
si (err.code === 404) {
// identifiant de l'historique trop ancien (> 7 jours). Réinitialisation à partir de messages.list
await réinitialiserDepuisMessages(authentification, adresse courriel);
} sinon {
lancer Erreur ;
}
}
}L'historyId dans la notification Pub/Sub est l courant état identifiantDébutHistorique doit être le précédent valeur que vous avez stockée. Utiliser directement historyId de la notification comme startHistoryId signifie que vous manquerez toutes les modifications entre votre dernier point traité et maintenant.
Pub/Sub peut livrer la même notification plus d'une fois. Votre logique de réconciliation doit être idempotente : le traitement d'un même ID de message deux fois ne doit avoir aucun effet. Utilisez une contrainte d'unicité sur les ID de message dans votre base de données, ou vérifiez l'existence avant d'insérer.
Si vous transmettez un startHistoryId datant de plus de 7 jours, l'API renvoie un 404. Dans ce cas, revenir à messages.liste pour resynchroniser à partir de zéro, puis appeler utilisateurs.regarder à nouveau pour obtenir une nouvelle base de données historyId.
Si de nombreux changements se sont produits entre votre dernier historyId et maintenant, la réponse de history.list peut être paginée. Suivez toujours jetonPageSuivante jusqu'à épuisement avant de mettre à jour votre curseur stocké.
Stratégie de renouvellement de mot de passe : le problème de l'expiration à 7 jours
Une surveillance de l'API Gmail expire silencieusement après 7 jours. Il n'y a pas de renouvellement automatique ni de notification d'avertissement. Si votre cron échoue, de nouveaux e-mails arrivent mais votre application ne reçoit rien - sans aucune erreur des deux côtés. Cela fait du renouvellement la partie la plus critique sur le plan opérationnel de toute implémentation de notifications push Gmail.
Renouveler quotidiennement, pas tous les 7 jours. Exécutez votre cron de renouvellement toutes les 24 heures (pas tous les 6 ou 7 jours). La surveillance du renouvellement est idempotente - un appel utilisateurs.regarder réinitialise simplement le minuteur de 7 jours. Une cadence quotidienne vous donne une marge de sécurité de 6 jours contre les défaillances transitoires.
// Daily cron: 0 3 * * * (runs at 3am daily)
async function renewAllWatches() {
// Get all authenticated users from your database
const users = await db.getAllActiveUsers();
for (const user of users) {
try {
// Refresh the access token if needed
const auth = await getAuthClient(user.id);
const gmail = google.gmail({ version: 'v1', auth });
const res = await gmail.users.watch({
userId: 'me',
requestBody: {
topicName: 'projects/YOUR_PROJECT_ID/topics/gmail-notifications',
labelIds: ['INBOX']
}
});
// Update historyId baseline : new watch returns a fresh historyId
await db.update(user.id, {
lastHistoryId: res.data.historyId,
watchExpiry: new Date(parseInt(res.data.expiration))
});
} catch (err) {
if (err.code === 401) {
// Refresh token revoked : user needs to re-authorize
await db.markUserDisconnected(user.id);
} else if (err.code === 404) {
// Watch expired : call watch again (already doing this, so 404 = retry next run)
console.warn(`Watch already expired for ${user.email}, will retry`);
} else {
// Log and continue : don't abort the entire cron for one user
console.error(`Watch renewal failed for ${user.email}`, err);
}
}
}
}Unipile gère automatiquement le renouvellement des montres pour chaque utilisateur authentifié. Pas besoin de tâche cron.
Dépannage des notifications push de l'API Gmail
Ce sont les quatre classes d'erreurs qui sont responsables de la quasi-totalité des échecs des notifications push de Gmail. La plupart ont une cause racine unique une fois que vous savez quoi chercher.
| Erreur / Symptôme | Cause profonde | Réparer | Sévérité |
|---|---|---|---|
| 403 sur watch de usuarios | Compte de service Gmail gmail-api-push@system.gserviceaccount.com n'a pas reçu le rôle d'éditeur Pub/Sub sur le sujet. |
Dans la console GCP : Pub/Sub > Topics > votre topic > Permissions. Ajoutez le compte de service avec le rôle Pub/Sub Publisher. | Bloqueur |
| la montre réussit mais aucune notification n'est reçue | L'URL du point de terminaison de poussée de l'abonnement Pub/Sub n'est pas enregistrée, a été rejetée par Google (TLS invalide) ou le type d'abonnement de poussée est " Pull " au lieu de " Push ". | Vérifiez que votre abonnement est de type "Push" avec votre URL de webhook comme point de terminaison. Assurez-vous que le certificat TLS est valide (pas auto-signé). Testez que le point de terminaison renvoie 200. | Bloqueur |
| 404 sur history.list - historyId trop ancien | Votre stocké dernierIdHistorique est antérieure à 7 jours. Gmail ne conserve l'historique que pendant 7 jours. |
Revenir en arrière messages.liste pour resynchroniser. Ensuite, appelez utilisateurs.regarder pour une nouvelle base de référence historyId. |
Récupérable |
| Jeton de validation de point de terminaison push rejeté | Google envoie un en-tête X-Goog-Channel-Token. Si votre point de terminaison le valide et que le jeton ne correspond pas, il renvoie un code non-2xx et Pub/Sub retente indéfiniment. | Désactivez la validation des jetons lors de la configuration initiale, ou configurez la même valeur de jeton dans les paramètres de l'abonnement GCP et dans la configuration de votre application. | Récupérable |
gmail-api-push@system.gserviceaccount.com non accordé Éditeur Pub/Sub.Quotas et limites de débit pour les notifications push de l'API Gmail
Les notifications push de l'API Gmail ont des contraintes de quota spécifiques qui diffèrent des compartiments de quota standard de l'API Gmail. La contrainte principale est le débit d'événements par utilisateur.
Débit maximal de notifications Pub/Sub par utilisateur authentifié. Les pics peuvent temporairement le dépasser mais sont limités dans le temps. Si une boîte aux lettres reçoit plus d'un changement par seconde en continu, les notifications seront regroupées ou retardées, pas ignorées.
Expiration maximale de la montre. Toutes les montres doivent être renouvelées avant cette date limite. Gmail conserve histoire.liste données pour la même fenêtre de 7 jours - un historyId plus ancien que 7 jours renvoie un 404.
Quota quotidienne par défaut de l'API Gmail par projet. Chaque historique.utilisateurs.liste un appel coûte 5 unités. utilisateurs.regarder coûte 100 unités par appel. Planifiez votre volume de rapprochement en conséquence.
Pour une analyse plus approfondie des quotas par méthode, des limites par utilisateur et des procédures de demande d'augmentation de quota, consultez notre document dédié Limites et quotas de la Gmail API.
Compromis : Pub/Sub vs IMAP IDLE vs interogation vs webhook unifié
Choisir la bonne stratégie de notifications push Gmail dépend de vos contraintes d'infrastructure, de vos besoins en couverture de fournisseur et de votre tolérance opérationnelle. Voici une comparaison directe des quatre approches.
| Approche | Temps de latence | Complexité d'installation | Multi-fournisseurs | Surcharge d'exploitation |
|---|---|---|---|---|
| Encore pub/sub Gmail | 1-10s | Haut - GCP, IAM, cron | Gmail uniquement | cron de renouvellement de 7 jours |
| IMAP IDLE | 1 à 30 secondes | Moyen - TCP persistant | Serveurs Gmail + IMAP | Gestion de la connexion persistante |
| Sondage | Délai de 30 à 300 secondes | Faible | Tout fournisseur | Quota élevée de dépenses |
| Webhook unifié (Unipile) | 1-10s | Faible - 1 URL de webhook | Gmail + Outlook + IMAP | Aucun - géré |
L'Alternative Unifiée aux Webhooks : Gmail + Outlook + IMAP avec un seul point de terminaison
Si vous avez besoin de notifications push de l'API Gmail ainsi que d'événements en temps réel des boîtes aux lettres Outlook et IMAP – avec un format de charge utile unifié et aucune infrastructure GCP – Unipile's API Gmail résume entièrement la couche Pub/Sub. En tant qu'intermédiaire technique indépendant, Unipile agit pour le compte de chaque utilisateur authentifié pour délivrer des événements d'e-mail via une URL de webhook unique que votre application contrôle déjà.
Pas de sujet Pub/Sub à créer, pas de droits IAM à configurer, pas de projet GCP à maintenir. L'enregistrement et le renouvellement des notifications se font à l'intérieur de l'infrastructure d'Unipile, pas de la vôtre.
L'expiration de la montre de 7 jours est gérée au nom de chaque compte lié. Vous n'avez jamais besoin d'une tâche cron de renouvellement. Si un jeton d'actualisation est révoqué, Unipile déclenche un webhook de statut de compte au lieu d'ignorer silencieusement les événements.
Vous recevez un objet d'e-mail analysé et normalisé - pas un historyId brut. Il n'est pas nécessaire d'appeler historique.utilisateurs.liste ou gérer des curseurs par utilisateur. Unipile résout le delta et livre des données structurées de messages.
Le même point de terminaison de webhook et le même schéma d'événement couvrent Gmail, Outlook (y compris Microsoft 365 / Exchange Online) et IMAP. Pas de logique d'intégration par fournisseur, pas de webhooks distincts pour les abonnements Microsoft Graph par rapport aux notifications pub/sub de Gmail.
// 1. Lier le compte Gmail de l'utilisateur (OAuth pour le compte de l'utilisateur authentifié)
// Voir : https://developer.unipile.com/docs/getting-started
// 2. Configurez votre webhook une seule fois
const config await fetch('https://api8.unipile.com:13815/api/v1/webhooks', {
method: POST,
headers : {
'X-API-KEY': 'VOTRE_CLÉ_API',
'Content-Type': 'application/json'
},
body: JSON.filtrer({
url : 'https://app.you.com/webhooks/email',
événements : ['email.nouveau']
})
});
// 3. Gérer la charge utile unifiée : même forme pour Gmail, Outlook, IMAP
application.poste('/webhooks/email', (req, res) => {
const { événement, id_compte, e_mail } = req.body;
// événement : " email.nouveau "
// provider.email : " gmail " | " outlook " | " imap "
// email.sujet, .de, .a, .corps_html...
// Pas d'historiqueId. Pas de base64. Pas de curseur à gérer.
traiterEmailEntrant(courriel);
res.statut(200).Fin();
});Unipile ne construit pas d'archive d'e-mails parallèle ni ne stocke le contenu des messages indépendamment. L'accès est limité à la session de chaque utilisateur authentifié. Unipile récupère les données d'e-mails pour le compte de chaque compte lié et les livre à votre point de terminaison webhook en temps réel. Aucune donnée n'est conservée au-delà de ce qui est nécessaire pour livrer la charge utile du webhook.
Unipile est un intermédiaire technique indépendant. Il agit pour le compte de chaque utilisateur authentifié qui a autorisé votre application via OAuth. Unipile n'est pas affilié, approuvé ou parrainé par Google. Il utilise les mêmes points de terminaison de l'API Gmail décrits dans ce guide, sur une base individuelle, sous la propre autorisation OAuth de chaque utilisateur. Les identifiants ne sont jamais partagés entre les comptes. Toutes les opérations sont une décision côté client déléguée à l'infrastructure d'Unipile.
Unipile relaie les limites de débit et les contraintes de quota de l'API Gmail à votre application via sa propre couche de gestion de quota. Les décisions concernant le volume des événements, la fréquence des sondages et la gestion des messages restent du ressort du client. Unipile fait remonter les erreurs de quota de l'API Gmail sous forme d'événements webhook structurés afin que votre application puisse y répondre de manière appropriée.
Connectez votre premier compte Gmail en quelques minutes. Pas de projet GCP. Pas de facturation Pub/Sub. Pas de tâche cron de renouvellement de surveillance. Voir notre Guide d'intégration de l'API Gmail et le Présentation du fournisseur d'API d'e-mail pour explorer tous les fournisseurs pris en charge.
Notifications push de l'API Gmail - FAQ
Réponses aux questions les plus fréquentes concernant les notifications push de l'API Gmail, la configuration de Pub/Sub, l'ID d'historique, le renouvellement de la veille et les alternatives de synchronisation d'e-mails en temps réel.
Notifications push de l'API Gmail Google Cloud Pub/Sub pour livrer les événements de changement de boîte aux lettres en temps réel à votre webhook HTTPS. Vous enregistrez un point de terminaison de surveillance via utilisateurs.regarder, qui relie une boîte aux lettres Gmail à un sujet Pub/Sub que vous possédez. Lorsqu'un événement se produit (nouveau message, changement d'étiquette), Gmail publie une notification sur ce sujet, qui la transmet à votre webhook push. Votre webhook appelle ensuite historique.utilisateurs.liste avec un stocké identifiantHistorique curseur pour récupérer le delta du message réel. La notification Pub/Sub elle-même ne contient que l'e-mail de l'utilisateur et un nouvel historyId - pas le contenu du message.
utilisateurs.regarder enregistre un abonnement de notification push pour une boîte aux lettres Gmail et renvoie une valeur de base historyId. C'est le point d'entrée qui connecte Gmail à votre sujet Pub/Sub. historique.utilisateurs.liste le point de terminaison de réconciliation que vous appelez après avoir reçu une notification push Gmail pour obtenir les changements réels (ajout de messages, suppressions, changements d'étiquettes) qui se sont produits depuis votre curseur historyId stocké. Watch indique à Gmail où envoyer les alertes. History vous indique ce qui a réellement changé.
Les points de terminaison de surveillance de l'API Gmail expirent après 7 jours. La meilleure pratique est d'exécuter un tâche cron quotidienne plutôt que tous les 6 ou 7 jours, ainsi vous avez un tampon de plusieurs jours contre les défaillances transitoires. Le renouvellement des certificats est idempotent : un nouveau utilisateurs.regarder seul réinitialise la minuterie et renvoie une nouvelle valeur de base pour historyId. L'expiration se produit silencieusement - il n'y a pas de notification d'avertissement, donc un cron défaillant signifie des événements manqués sans erreurs d'aucun côté.
La cause la plus fréquente est un concession IAM manquante. Gmail utilise le compte de service gmail-api-push@system.gserviceaccount.com pour publier sur votre rubrique Pub/Sub. Sans le Éditeur Pub/Sub Rôle sur votre sujet pour ce compte, utilisateurs.regarder réussit mais aucune notification n'est jamais délivrée. Autres causes : le type d'abonnement est "Pull" au lieu de "Push", certificat TLS invalide sur votre point de terminaison webhook, ou votre point de terminaison renvoie des réponses non-2xx, ce qui empêche Pub/Sub de continuer la livraison.
Le identifiantHistorique est un entier monotone croissant que Gmail attribue à chaque événement de modification de boîte aux lettres. Il sert de curseur de synchronisation incrémental. Lorsque vous enregistrez une utilisateurs.regarder, Gmail renvoie un `historyId` de base représentant l'état actuel. Les notifications push Gmail ultérieures incluent un nouveau `historyId`. Vous transmettez votre `historyId` stocké (précédent) comme identifiantDébutHistorique à historique.utilisateurs.liste pour obtenir toutes les modifications entre les deux points. Vous devez stocker le dernier historyId par utilisateur authentifié dans votre base de données. Les historyIds plus anciens que 7 jours renvoient une erreur 404.
Pas directement via l'API Gmail - Pub/Sub est le canal de diffusion requis pour les notifications push de Gmail. Cependant, vous pouvez éviter complètement l'infrastructure GCP en utilisant une API de messagerie unifiée comme Unipile, qui agit en tant qu'intermédiaire technique indépendant au nom de chaque utilisateur authentifié, abstrait la couche Pub/Sub et livre les notifications push Gmail à votre webhook avec une charge utile normalisée. Aucun projet GCP, aucune autorisation IAM, aucun renouvellement de surveillance cron requis.
Exécute un tâche cron quotidienne ça appelle utilisateurs.regarder pour tous les utilisateurs actifs authentifiés. Stocker le historyId retourné comme nouvelle référence et mettre à jour l'horodatage d'expiration stocké. Gérer les erreurs par utilisateur sans abandonner le lot : un 401 signifie que le jeton de rafraîchissement OAuth a été révoqué (l'utilisateur doit réautoriser), un 404 signifie que la surveillance a déjà expiré. Ne jamais attendre l'expiration de 7 jours pour renouveler - traiter l'exécution quotidienne comme une maintenance, pas une correction réactive.
Les notifications push de l'API Gmail sont limitées à environ 1 événement par seconde par utilisateur authentifié. Les débits supérieurs sont mis en lots ou retardés, pas perdus. Le historique.utilisateurs.liste l'appel coûte 5 unités de quota et utilisateurs.regarder coûte 100 unités par appel. La limite d'utilisation quotidienne par défaut de l'API Gmail est de 1 million d'unités par projet. Pour une description complète des limites par méthode et des procédures d'augmentation des limites, consultez notre Guide des limites de débit de l'API Gmail.
Besoin d'aide pour configurer les notifications push de l'API Gmail pour votre application ? Notre équipe peut vous guider.
FR 
EN 
ES 
DE 
IT 
BR 
NL 
PL 
TR