LinkedIn
Instagram
WhatsApp
Telegramm
Google Mail
Ausblick
Google Kalender
Slack-Gemeinschaft beitretenGmail-API Push-Benachrichtigungen: Vollständiger Leitfaden zu Pub/Sub, Watch & History (2026)
Gmail API Push-Benachrichtigungen End-to-End einrichten: ein Pub/Sub-Thema erstellen, einen Watch-Endpunkt registrieren, Webhook-Nutzdaten dekodieren, Änderungen abgleichen mit Benutzerverlauf Liste, automatische Uhrenverlängerung, und überspringen Sie die gesamte GCP-Einrichtung mit einer einheitlichen Webhook-Alternative.
// 1. Gmail-Feed über Unipile registrieren
const res = await fetch('https://api8.unipile.com:13815/api/v1'
+ '/konten/{id}/watch', {
method: 'POST',
headers: {
'X-API-KEY': 'DEIN_API_SCHLÜSSEL',
'Content-Type': 'application/json'
},
body: JSON.stringify({
webhook_url: 'https://app.you.com/webhooks/gmail'
})
});
// 2. Einheitliche Webhook-Nutzlast empfangen
App.Beitrag('/webhooks/gmail', (anfrage, antwort) => {
const { Ereignis, Konto_ID, E-Mail } = req.body;
Ereignis: "neue_email" | historyId abstrahiert
neueE-MailBehandeln(E-Mail);
});Was sind Gmail API Push-Benachrichtigungen?
Bevor Sie Gmail API Push-Benachrichtigungen in der Produktion implementieren, ist es hilfreich, genau zu verstehen, was sie sind, wie sie sich vom einfachen Abfragen unterscheiden und welche Infrastruktur sie erfordern.
Gmail API Push-Benachrichtigungen sind ein Echtzeit-Zustellmechanismus, der Google Cloud Pub/Sub verwendet, um Änderungen am Postfach an einen vom Entwickler gesteuerten HTTPS-Endpunkt zu senden. Wenn eine neue Nachricht eintrifft oder eine vorhandene Nachricht geändert wird, veröffentlicht Gmail eine Benachrichtigung, die kodierte historyId an einen Pub/Sub-Topic, der Ihnen gehört, der dieses Ereignis dann an Ihren Webhook weiterleitet. Ihr Server ruft Benutzerverlauf Liste um die tatsächlichen Änderungen abzurufen.
Gmail API Push-Benachrichtigungen machen wiederholte Aufrufe überflüssig Nachrichtenliste Zeitnah. Ereignisse werden innerhalb von Sekunden nach der Änderung des Postfachs geliefert, was sowohl die Latenz als auch die Auslastung des API-Kontingents reduziert.
Der Lieferkanal ist Google Cloud Pub/Sub, nicht ein direkter HTTP-Callback von Gmail. Dies erhöht die Ausfallsicherheit: Wenn Ihr Endpunkt vorübergehend nicht verfügbar ist, kann Pub/Sub die Zustellung gemäß der Bestätigungsfrist Ihres Abonnements wiederholen.
Ein Gmail API Watch-Endpunkt verfällt nach 7 Tagen. Ihre Anwendung muss ihn proaktiv mit einem täglichen Cron-Job erneuern, um stille Ereignisausfälle zu vermeiden. Dies ist ein kritischer operativer Detail, der im Abschnitt „Erneuerung“ behandelt wird.
Gmail API Push-Benachrichtigungen liefern Ereignisse innerhalb von 1-10 Sekunden nach der Änderung. Kein ständiges Abfragen bedeutet geringeren Quotenverbrauch der Gmail API und schnellere Reaktionszeiten für Ihre Anwendung. Ideal für alle Anwendungsfälle, die eine Echtzeit-Benachrichtigung auf Postfachebene erfordern: CRM-Synchronisierung, Ticketing-Systeme, Workflow-Automatisierung.
Abfrage Nachrichtenliste Jede 60 Sekunden ist einfacher einzurichten, führt aber zu künstlicher Verzögerung, verschwendet Kontingente für leere Antworten und skaliert schlecht mit einer großen Anzahl authentifizierter Benutzerkonten. Nur für Prototypen mit geringem Volumen akzeptabel.
Architektur: Watch + Pub/Sub + historyId in einem Fluss
Gmail API Push-Benachrichtigungen umfassen vier unterschiedliche Ebenen, die sequenziell arbeiten. Das Verständnis jeder Ebene vor dem Schreiben von Code verhindert die häufigsten Implementierungsfehler.
Du POSTEST an https://gmail.googleapis.com/gmail/v1/users/me/watch mit Ihrem Pub/Sub-Topic-Namen und optional einem Label-Filter. Gmail gibt ein historyId und ein Ablauf Unix-Zeitstempel. Speichere beide. Diese Quittung verfällt in 7 Tagen.
Wenn eine Änderung in der überwachten Mailbox auftritt (neue Nachricht, Änderung des Labels, Ein-/Ausschalten von gelesen/ungelesen), veröffentlicht Gmail eine JSON-Benachrichtigung an Ihr Cloud Pub/Sub-Thema. Die Nutzlast ist ein Base64-codiertes Objekt, das die E-Mail-Adresse des Benutzers und eine neue enthält historyId.
Ihr Pub/Sub-Abonnement leitet die Nachricht an einen registrierten HTTPS-Push-Endpunkt weiter. Dies ist Ihre Webhook-URL, die innerhalb der Bestätigungszeit (standardmäßig 10–600 Sekunden) mit HTTP 200–299 antworten muss. Eine Antwort, die keine 2xx-Antwort ist, löst automatische Wiederholungsversuche aus.
Dekodieren Sie die Basis64-Pub/Sub-Nachrichtendaten. Extrahieren Sie die neuen historyId. Vergleichen Sie es mit dem letzteHistorieId in Ihrer Datenbank für diesen Benutzer gespeichert.
Rufen Benutzerverlauf Liste mit startVerlaufId auf Ihren gespeicherten Wert gesetzt. Gmail gibt alle Änderungen (neue Nachrichten, Hinzufügungen oder Löschungen von Labels) zwischen den beiden IDs zurück. Aktualisieren Sie Ihren gespeicherten letzteHistorieId zum neuen Wert. Verwenden Sie niemals die historyId aus der Pub/Sub-Benachrichtigung als startVerlaufId direkt.
Einen täglichen Cron-Job einplanen, um aufzurufen Benutzer ansehen nochmals für jedes authentifizierte Benutzerkonto. Die Überwachung der Erneuerung ist idempotent: ein neuer Aufruf ersetzt das vorherige Ablaufdatum. Der zurückgegebene historyId wird zu Ihrer neuen Basislinie.
Eine monoton steigende Ganzzahl, die von Gmail jeder Postfachänderung zugewiesen wird. Sie ist Ihr Cursor für die inkrementelle Synchronisierung. Speichern Sie immer die neueste historyId pro Benutzer in Ihrer Datenbank.
Der Gmail API-Endpunkt, der ein Push-Benachrichtigungsabonnement für ein Postfach registriert. Gibt eine HistoryID-Basislinie und einen Unix-ms-Ablaufzeitstempel zurück. Muss innerhalb von 7 Tagen erneuert werden.
Der Abgleich-Endpunkt. Gegeben eine startHistoryId, gibt er alle Nachrichtenänderungen, -löschungen und -labeländerungen zurück, die nach diesem Zeitpunkt aufgetreten sind. Hier erhalten Sie die eigentlichen Nachrichtendaten.
Voraussetzungen: GCP-Projekt, Pub/Sub-Thema, IAM-Berechtigung
Gmail API Push-Benachrichtigungen erfordern drei Ressourcen auf GCP-Seite, bevor Sie Ihre erste Benutzer ansehen Die meisten Implementierungsfehler sind auf eine fehlende IAM-Berechtigung für das Pub/Sub-Thema zurückzuführen, ein Schritt, den Entwickler am häufigsten überspringen.
In der Google Cloud Console, erstellen oder wählen Sie ein vorhandenes Projekt. Navigieren Sie zu APIs und Dienste > Bibliothek und aktivieren Sie die Gmail-API. Außerdem benötigen Sie die Cloud Pub/Sub API im selben Projekt aktiviert. Stellen Sie sicher, dass Ihre OAuth 2.0-Clientanmeldeinformationen Folgendes enthalten https://www.googleapis.com/auth/gmail.readonly scope (oder einen breiteren Geltungsbereich, falls Sie Schreibzugriff benötigen). Für Multi-User-Anwendungen lesen Sie unseren Leitfaden zu Gmail OAuth 2.0 Integration und die Google OAuth App-Überprüfung Anforderungen.
In der GCP-Konsole unter Pub/Sub > Themen, klicken Thema erstellen. Gib ihm einen Namen wie Gmail-Benachrichtigungen. Der vollständige Thema-Name wird projects/DEINE_PROJEKT_ID/topics/gmail-benachrichtigungen. Sie werden diese exakte Zeichenfolge übergeben an Benutzer ansehen in dem ThemaName Feld.
Dies ist der Schritt, den die meisten Entwickler übersehen. Gmail verwendet ein von Google verwaltetes Dienstkonto (gmail-api-push@system.gserviceaccount.com) Benachrichtigungen an Ihr Pub/Sub-Thema zu senden. Ohne diesem Konto die Pub/Sub Publisher Rolle zu Ihrem Thema, Benutzer ansehen wird erfolgreich sein, aber es werden niemals Benachrichtigungen zugestellt. In der Konsole: Themen > Wählen Sie Ihr Thema aus > Berechtigungen > Prinzipal hinzufügen > Geben Sie ein gmail-api-push@system.gserviceaccount.com Rolle zuweisen Pub/Sub Publisher.
Erstellen Sie unter Ihrem Pub/Sub-Thema ein Push-Abonnement. Setzen Sie den Push-Endpunkt auf Ihre HTTPS-Webhook-URL (muss ein gültiges TLS-Zertifikat verwenden, selbstsignierte Zertifikate werden abgelehnt). Konfigurieren Sie optional eine Token-Validierungsüberschrift, damit Ihr Endpunkt Anfragen von Google überprüfen kann. Notieren Sie sich den Abonnementnamen, den Sie möglicherweise zur Überwachung von Zustellmetriken in Cloud Monitoring benötigen.
100 Nutzer-Obergrenze für nicht verifizierte Apps: Wenn Ihr OAuth-Zustimmungsbildschirm den Status "Testen" hat, können nur 100 Gmail-Konten Ihre App autorisieren. Dieses Limit gilt für alle OAuth-Bereiche, einschließlich Endpunkt für Benachrichtigungen. Für Produktivbereitstellungen mit mehr als 100 Nutzern müssen Sie den Verifizierungsprozess von Google abschließen. Ausführliche Anleitung finden Sie in unserer vollständigen Anleitung unter Begrenzung auf 100 Benutzer und Verifizierungspfad.
Kein Pub/Sub-Thema. Keine IAM-Berechtigung. Kein Cron-Job zur Verlängerung der 7-tägigen Überwachung. Erstellen Sie Gmail-Push-Benachrichtigungen mit einer einzigen Webhook-URL.
Schritt für Schritt: Thema, Abonnement und Benutzer.watch erstellen
Mit den GCP-Voraussetzungen können Sie hier den vollständigen Code zum Registrieren eines Gmail API Watch-Endpunkts in Node.js und Python mithilfe der Google API Client Library einsehen.
const { google } = require('googleapis');
// Geht davon aus, dass der OAuth2-Client bereits mit einem gültigen Zugriffstoken autorisiert ist
// Siehe: https://www.unipile.com/gmail-oauth-20-integration-complete-guide/
async function Gmail registrieren Beobachten(auth, userId = ich) {
const gmail = Google.gmail({ Version: 'v1', auth });
const response = await Gmail-Benutzer.Uhr({
BenutzerId,
requestBody: {
// Ihr vollständiger Pub/Sub-Themenname
ThemaName: 'Projekte/DEINE_PROJEKT_ID/Themen/gmail-benachrichtigungen',
// Optional: Filter nur nach spezifischen Labels
labelIds: ['POSTeingang'],
labelFilterVerhalten: 'EINSCHLIESSEN'
}
});
const { historyId, expiration } = response.data;
// Speichern Sie diese pro Benutzer in Ihrer Datenbank
await Datenbank.Upsert({
BenutzerId,
letzteHistorieId: historienId,
// Ablaufzeit ist ein Unix-Timestamp in Millisekunden
watchExpiry: new Datum(parseInt(Ablaufdatum))
});
Konsole.log(`Beobachtung registriert. historyId: ${historyId}, läuft ab: ${expiration}`);
return response.data;
}from googleapiclient.discovery import bauen
from google.oauth2.anmeldeinformationen import Berechtigungsnachweise
def registriere_gmail_watch(Zugangsdaten: Zugangsdaten, Benutzer-ID: Str = ich) -> dict:
"Gmail API Push-Benachrichtigungen für einen authentifizierten Benutzer registrieren (Watch)."
Dienst = bauen('Gmail', 'v1', Anmeldeinformationen=Anmeldeinformationen)
Körper = {
'Themenname': 'Projekte/DEINE_PROJEKT_ID/Themen/gmail-benachrichtigungen',
'labelIds': ['POSTeingang'],
'labelFilterVerhalten': 'EINSCHLIESSEN'
}
Ergebnis = service.users().Uhr(userId=user_id, body=body).ausführen()
# In Ihrer Datenbank pro Benutzer speichern
db_einfügen_oder_aktualisieren(user_id=user_id,
letzte_historie_id=result['historyId'],
watch_expiry=int(Ergebnis['Ablauf']) // 1000)
return ErgebnisVerarbeitung der Webhook-Payload von Gmail API-Pushbenachrichtigungen
Wenn Gmail eine Push-Benachrichtigung sendet, empfängt Ihr HTTPS-Endpunkt eine Pub/Sub-Push-Nachricht. Die eigentlichen Gmail-Änderungsdaten sind doppelt kodiert: Die Pub/Sub-Hülle enthält eine base64-kodierte JSON-Zeichenfolge, die ihrerseits die E-Mail-Adresse des Benutzers und die historyId enthält.
App.Beitrag('/webhooks/gmail', asynchron (req, res) => {
// Sofort bestätigen: Pub/Sub wiederholt bei Nicht-2xx
res.Status(200).Ende();
versuchen {
const Nachricht = req.body.Nachricht;
wenn (!message?.data) zurückkehren;
// Dekodieren Sie das Base64-Datenfeld von Pub/Sub
const dekodiert =
Puffer.from(Nachricht.Daten, 'base64').toString('utf-8');
const Nutzlast = JSON.parsen(dekodiert);
// Nutzlast = { E-Mail-Adresse: "user@gmail.com", Verlaufs-ID: "12345" }
const { emailAddress, historyId } = payload;
// Warteschlangenabgleich (nicht den Ack blockieren)
await Warteschlange.einstellen({ E-Mail-Adresse, VerlaufID });
} catch (err) {
// Protokolliere, aber werfe nicht erneut: Bestätigung wurde bereits gesendet
Konsole.Fehler('Webhook-Parsingfehler', Fehler);
}
});import base64, json
from Flasche import Flask, Anfrage, jsonify
app Flasche(__name__)
@app.Route('/webhooks/gmail', Methoden=['POST'])
def gmail_webhook():
# Sofort bestätigen
daten = anfrage.get_json(still=True) oder {}
Nachricht = Daten.bekommen.('Nachricht', {})
wenn 'Daten' in Nachricht:
# Base64 entschlüsseln und JSON analysieren
raw = base64.b64decode(Nachricht['Daten'] + '==')
Nutzlast = json.Lasten(roh)
# { "emailAddress": "user@gmail.com", "historyId": "12345" }
E-Mail = Nutzlast.bekommen.('E-Mail-Adresse')
history_id = payload.bekommen.('historyId')
# Asynchrone Abgleichung in die Warteschlange stellen
in die Warteschlange stellen zur Abstimmung(E-Mail, Verlaufs-ID)
return in JSON umwandeln({}), 200Änderungen mit users.history.list abgleichen
Die Pub/Sub-Benachrichtigung teilt Ihnen nur mit Etwas hat sich geändert. Es sagt dir nicht, was. Du musst anrufen Benutzerverlauf Liste mit Ihrem gespeicherten letzteHistorieId als der Cursor, um das tatsächliche Delta zu erhalten.
async function Historie abgleichen(auth, emailAdresse, neueVerlaufID) {
const gmail = Google.gmail({ Version: 'v1', auth });
// Rufe unseren gespeicherten lastHistoryId für diesen Benutzer ab
const Benutzer = await Datenbank.findeNachEmail(emailAdresse);
const startHistoryId = user.lastHistoryId;
versuchen {
const response = await gmail.users.history.list({
userId: ich,
// Verwenden Sie die gespeicherte ID als Cursor: NICHT die neue BenachrichtigungshistorieID
startverlaufid,
// Filterung auf reine Nachrichten-Additions (optional)
historyTypes: ['NachrichtHinzugefügt']
});
const historien = response.data.historie || [];
für (const Aufzeichnungen der Geschichte) {
für (const added of (record.messagesAdded || [])) {
// hinzugefügt.nachricht = { id, threadId, labelIds }
await NachrichtVerarbeiten(auth, added.message.id);
}
}
// Cursor auf die neue historyId aus der Benachrichtigung aktualisieren
await Datenbank.letzteVerlaufIdAktualisieren(emailAddress, neueVerlaufID);
} catch (err) {
wenn (err.code === 404) {
historyId ist zu alt (> 7 Tage). Neuinitialisierung anhand von messages.list
await von Nachrichten neu initialisieren(Benutzername, E-Mail-Adresse);
} else {
werfen Fehler;
}
}
}Die historyId in der Pub/Sub-Benachrichtigung ist die aktuell Zustand. Dein startVerlaufId muss der vorher Der von Ihnen gespeicherte Wert. Die Verwendung der Notification History ID direkt als startHistoryId bedeutet, dass Sie alle Änderungen zwischen Ihrem letzten verarbeiteten Punkt und jetzt verpassen.
Pub/Sub kann dieselbe Benachrichtigung mehr als einmal liefern. Ihre Abgleichlogik muss idempotent sein: Die zweimalige Verarbeitung derselben Nachrichten-ID sollte keine Auswirkung haben. Verwenden Sie eine eindeutige Beschränkung für Nachrichten-IDs in Ihrer Datenbank oder prüfen Sie auf Existenz, bevor Sie etwas einfügen.
Wenn Sie eine startHistoryId übergeben, die älter als 7 Tage ist, gibt die API einen 404 zurück. In diesem Fall greifen Sie auf Nachrichtenliste zur Neusynchronisierung von Grund auf, rufen Sie dann auf Benutzer ansehen um eine neue historyId-Basislinie zu erhalten.
Wenn viele Änderungen zwischen Ihrer letzten historyId und jetzt aufgetreten sind, kann die history.list-Antwort paginiert sein. Folgen Sie immer nächstesSeitenToken bis erschöpft, bevor Sie Ihren gespeicherten Cursor aktualisieren.
Wiederherstellungsstrategie für Watches: Das 7-Tage-Ablaufproblem
Eine Gmail API Watch läuft nach 7 Tagen ohne Ankündigung ab. Es gibt keine automatische Verlängerung und keine Warnung. Wenn Ihr Cron-Job fehlschlägt, kommen zwar neue E-Mails an, aber Ihre Anwendung empfängt nichts – ohne Fehler auf beiden Seiten. Das macht die Verlängerung zum kritischsten operativen Teil jeder Gmail Push-Benachrichtigungs-Implementierung.
Täglich erneuern, nicht alle 7 Tage. Führen Sie Ihren Erneuerungs-Cron alle 24 Stunden aus (nicht alle 6 oder 7 Tage). Watch Renewal ist idempotent – Aufruf Benutzer ansehen setzt den 7-Tage-Timer einfach zurück. Ein täglicher Rhythmus verschafft Ihnen einen 6-tägigen Sicherheits
.
// 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 kümmert sich im Namen jedes authentifizierten Benutzers automatisch um die Verlängerung von Watches. Kein Cronjob erforderlich.
Fehlerbehebung bei Gmail API Push-Benachrichtigungen
Dies sind die vier Fehlerklassen, die für fast alle fehlerhaften Gmail-Push-Benachrichtigungen verantwortlich sind. Die meisten haben eine einzige Ursache, sobald man weiß, worauf man achten muss.
| Fehler / Symptom | Grundursache | Korrigieren | Schwere |
|---|---|---|---|
| 403 auf users.watch | Gmail-Dienstkonto gmail-api-push@system.gserviceaccount.com Pub/Sub Publisher-Rolle für das Thema wurde nicht gewährt. |
In der GCP Console: Pub/Sub > Themen > Ihr Thema > Berechtigungen. Fügen Sie das Dienstkonto mit der Rolle "Pub/Sub-Publisher" hinzu. | Blocker |
| Uhr funktioniert, aber keine Benachrichtigungen erhalten | Pub/Sub-Abonnement-Push-Endpunkt-URL ist nicht registriert, von Google abgelehnt (ungültiges TLS) oder der Push-Abonnementtyp ist "Pull" anstelle von "Push". | Überprüfen Sie, ob Ihr Abonnement vom Typ "Push" ist und Ihre Webhook-URL als Endpunkt verwendet wird. Stellen Sie sicher, dass das TLS-Zertifikat gültig ist (nicht selbstsigniert). Der Testendpunkt gibt 200 zurück. | Blocker |
| 404 bei history.list – historyId zu alt | Ihre gespeicherten letzteHistorieId ist älter als 7 Tage. Gmail behält den Verlauf nur 7 Tage bei. |
Zurückfallen auf Nachrichtenliste zum erneuten Synchronisieren. Dann rufen Sie Benutzer ansehen für eine frische historyId-Basislinie. |
Wiederherstellbar |
| Validierungstoken für Push-Endpunkt abgelehnt | Google sendet einen „X-Goog-Channel-Token“-Header. Wenn Ihr Endpunkt diesen überprüft und das Token nicht übereinstimmt, gibt er einen Statuscode ungleich 2xx zurück, und Pub/Sub versucht es unbegrenzt oft erneut. | Entweder die Token-Validierung während des anfänglichen Setups deaktivieren oder denselben Token-Wert sowohl in den GCP-Abonnement-Einstellungen als auch in Ihrer Anwendungskonfiguration konfigurieren. | Wiederherstellbar |
gmail-api-push@system.gserviceaccount.com Nicht gewährt Pub/Sub Publisher.Kontingente und Ratenbegrenzungen für Gmail API Push-Benachrichtigungen
Gmail API Push-Benachrichtigungen haben spezifische Kontingenteinschränkungen, die sich von den Standard-Kontingent-Buckets der Gmail API unterscheiden. Die wichtigste Einschränkung ist der Ereignisdurchsatz pro Benutzer.
Maximale Pub/Sub-Benachrichtigungsrate pro authentifiziertem Benutzer. Spitzenwerte können diese zeitweise überschreiten, werden aber im Laufe der Zeit gedrosselt. Wenn ein Postfach kontinuierlich mehr als 1 Änderung pro Sekunde empfängt, werden Benachrichtigungen gebündelt oder verzögert, nicht aber verworfen.
Maximale Ablaufzeit für Uhren. Alle Uhren müssen vor dieser Frist verlängert werden. Gmail behält Geschichte.Liste Daten für dasselbe 7-Tage-Fenster – eine historyId, die älter als 7 Tage ist, gibt eine 404 zurück.
Standard Gmail Benutzerverlauf Liste Anrufkosten betragen 5 Einheiten. Benutzer ansehen kostet 100 Einheiten pro Aufruf. Planen Sie Ihr Abgleichvolumen entsprechend.
Für eine detailliertere Aufschlüsselung der Kontingente pro Methode, der Beschränkungen pro Benutzer und der Verfahren für Anträge auf Erhöhung von Kontingenten siehe unsere dedizierte Gmail API Ratenbegrenzungen und Kontingente – Leitfaden.
Kompromisse: Pub/Sub vs. IMAP IDLE vs. Polling vs. Unified Webhook
Die Wahl der richtigen Strategie für Gmail Push-Benachrichtigungen hängt von Ihren Infrastrukturanforderungen, dem Bedarf an Anbieterabdeckung und Ihrer operativen Toleranz ab. Hier ist ein direkter Vergleich der vier Ansätze.
| Ansatz | Latenzzeit | Einrichtungsaufwand | Multi-Anbieter | Ops-Overhead |
|---|---|---|---|---|
| Gmail Pub/Sub überwachen | 1-10s | Hoch - GCP, IAM, Cron | Nur Gmail | 7-Tage-Erneuerungs-Cron |
| IMAP IDLE | 1-30sekunden | Medium - persistentes TCP | Gmail + IMAP-Server | Keep-Alive-Verwaltung |
| Abfrage | 30-300s Verzögerung | Niedrig | Jeder Anbieter | Hohe Quotenverbrennung |
| Vereinheitlichter Webhook (Unipile) | 1-10s | Niedrig - 1 Webhook-URL | Gmail + Outlook + IMAP | Nichts - verwaltet |
Die einheitliche Webhook-Alternative: Gmail + Outlook + IMAP mit einem Endpunkt
Wenn Sie Gmail API-Pushbenachrichtigungen plus Echtzeitereignisse von Outlook- und IMAP-Postfächern benötigen - mit einem einheitlichen Payload-Format und ohne GCP-Infrastruktur - Unipiles Gmail-API abstrahiert die gesamte Pub/Sub-Schicht. Als unabhängiges technisches Vermittlerunternehmen agiert Unipile im Namen jedes authentifizierten Nutzers, um E-Mail-Ereignisse über eine einzige Webhook-URL zu liefern, die Ihre Anwendung bereits kontrolliert.
Kein Pub/Sub-Topic zu erstellen, keine IAM-Berechtigung zu konfigurieren, kein GCP-Projekt zu verwalten. Registrierung und Verlängerung von Watchs erfolgen innerhalb der Unipile-Infrastruktur, nicht Ihrer.
Die 7-tägige Ablaufzeit der Uhr wird für jedes verknüpfte Konto gehandhabt. Sie benötigen niemals einen Cronjob für die Aktualisierung. Wenn ein Aktualisierungstoken widerrufen wird, gibt Unipile stattdessen einen Webhook zum Kontostatus aus, anstatt Ereignisse stillschweigend zu verwerfen.
Sie erhalten ein geparstes, normalisiertes E-Mail-Objekt – keine rohe historyId. Es ist nicht notwendig, Benutzerverlauf Liste oder pro Benutzer Cursor zu verwalten. Unipile löst die Delta auf und liefert strukturierte Nachrichtendaten.
derselbe Webhook-Endpunkt und dasselbe Ereignisschema decken Gmail, Outlook (einschließlich Microsoft 365 / Exchange Online) und IMAP ab. Keine protokollspezifische Integrationslogik, keine separaten Webhooks für Microsoft Graph-Abonnements im Vergleich zu Gmail Pub/Sub-Benachrichtigungen.
1. Gmail-Konto des Benutzers verknüpfen (OAuth im Namen des authentifizierten Benutzers)
// Siehe: https://developer.unipile.com/docs/getting-started
// 2. Konfigurieren Sie Ihren Webhook einmal
const Konfiguration = await fetch('https://api8.unipile.com:13815/api/v1/webhooks', {
method: 'POST',
Kopfzeilen: {
'X-API-KEY': 'DEIN_API_SCHLÜSSEL',
'Content-Type': 'application/json'
},
body: JSON.stringify({
URL 'https://app.you.com/webhooks/email',
Ereignisse: ['E-Mail.neu']
})
});
// 3. Einheitliche Payload verarbeiten: gleiche Struktur für Gmail, Outlook, IMAP
App.Beitrag('/webhooks/email', (req, res) => {
const { event, account_id, email } = req.body;
// event: "email.new"
// email.provider: "gmail" | "outlook" | "imap"
// email.betreff, .von, .an, .body_html...
Keine historyId. Kein Base64. Kein Cursor zu verwalten.
prozessiereEingehendeE-Mail(E-Mail);
res.Status(200).Ende();
});Unipile erstellt kein paralleles E-Mail-Archiv und speichert keine Nachrichteninhalte unabhängig davon. Der Zugriff ist auf die Sitzung jedes authentifizierten Benutzers beschränkt. Unipile ruft E-Mail-Daten im Namen jedes verknüpften Kontos ab und liefert sie in Echtzeit an Ihren Webhook-Endpunkt. Es werden keine Daten über das hinaus gespeichert, was zur Zustellung der Webhook-Nutzlast erforderlich ist.
Unipile ist ein unabhängiger technischer Vermittler. Er agiert im Namen jedes authentifizierten Nutzers, der Ihre Anwendung über OAuth autorisiert hat. Unipile ist nicht mit Google verbunden, wird von Google nicht unterstützt und von Google nicht gesponsert. Es nutzt dieselben Gmail-API-Endpunkte, die in dieser Anleitung beschrieben sind, pro Benutzer und unter der eigenen OAuth-Autorisierung jedes Nutzers. Anmeldedaten werden niemals zwischen Konten geteilt. Alle Vorgänge sind eine Entscheidung der Kundenseite, die an die Infrastruktur von Unipile delegiert wird.
Unipile gibt die Ratenbegrenzungen und Kontingentbeschränkungen der Gmail API über seine eigene Kontingentverwaltungs-Schicht an Ihre Anwendung weiter. Entscheidungen über das Ereignisvolumen, die Abfragehäufigkeit und die Nachrichtenverarbeitung bleiben eine Entscheidung auf Kundenseite. Unipile gibt Gmail API-Kontingentfehler als strukturierte Webhook-Ereignisse aus, damit Ihre Anwendung entsprechend reagieren kann.
Verbinden Sie Ihr erstes Gmail-Konto in wenigen Minuten. Kein GCP-Projekt. Keine Pub/Sub-Abrechnung. Kein Cron-Job zur Überwachung der Erneuerung. Sehen Sie sich unser an Leitfaden zur Integration der Gmail API und die Email-API-Anbieter Übersicht um alle unterstützten Anbieter zu erkunden.
Gmail API Push-Benachrichtigungen – FAQ
Antworten auf die häufigsten Fragen zu Gmail API Push-Benachrichtigungen, Pub/Sub-Einrichtung, historyId, Watch-Erneuerung und Echtzeit-E-Mail-Synchronisierungsalternativen.
Gmail API Push-Benachrichtigungen verwenden Google Cloud Pub/Sub um Echtzeit-Ereignisse bei Änderungen des Postfachs an deinen HTTPS-Webhook zu senden. Du registrierst einen Watch-Endpunkt über Benutzer ansehen, das eine Gmail-Mailbox mit einem von Ihnen besessenen Pub/Sub-Thema verknüpft. Wenn eine Änderung auftritt – neue Nachricht, Änderung des Labels – veröffentlicht Gmail eine Benachrichtigung an dieses Thema, das sie an Ihren Push-Webhook weiterleitet. Ihr Webhook ruft dann Benutzerverlauf Liste mit einem gespeicherten historyId Cursor, um die eigentliche Nachrichtenänderung abzurufen. Die Pub/Sub-Benachrichtigung selbst enthält nur die E-Mail-Adresse des Benutzers und eine neue historyId – nicht den Nachrichteninhalt.
Benutzer ansehen registriert ein Push-Benachrichtigungsabonnement für ein Gmail-Postfach und gibt eine historyId-Baseline zurück. Es ist der Einstiegspunkt, der Gmail mit Ihrem Pub/Sub-Thema verbindet. Benutzerverlauf Liste Der Abgleich-Endpunkt, den Sie aufrufen, nachdem Sie eine Gmail-Push-Benachrichtigung erhalten haben, um die tatsächlichen Änderungen (Nachrichtenhinzufügungen, -löschungen, Label-Änderungen) zu erhalten, die seit Ihrem gespeicherten historyId-Cursor aufgetreten sind. Watch teilt Gmail mit, wohin Benachrichtigungen gesendet werden sollen. History teilt Ihnen mit, was sich tatsächlich geändert hat.
Gmail API-Endpunkte, die E-Mails überwachen, laufen nach 7 Tage. Die beste Vorgehensweise ist, eine täglicher Cron-Job anstatt alle 6 oder 7 Tage, so dass Sie einen mehrtägigen Puffer gegen vorübergehende Fehler haben. Die Watch-Erneuerung ist idempotent: eine neue Benutzer ansehen Ein einfacher Aufruf setzt den Timer zurück und gibt eine frische historyId-Baseline zurück. Der Ablauf erfolgt stillschweigend – es gibt keine Warnmeldung, daher bedeutet ein fehlgeschlagener Cronjob verpasste Ereignisse ohne Fehler auf beiden Seiten.
Die häufigste Ursache ist eine Fehlende IAM-Berechtigung. Gmail verwendet das Dienstkonto gmail-api-push@system.gserviceaccount.com um auf Ihr Pub/Sub-Thema zu veröffentlichen. Ohne die Pub/Sub Publisher Rolle zu Ihrem Thema für dieses Konto, Benutzer ansehen funktioniert, aber es werden nie Benachrichtigungen zugestellt. Weitere Ursachen: Abonnementtyp ist "Pull" statt "Push", ungültiges TLS-Zertifikat an Ihrem Webhook-Endpunkt oder Ihr Endpunkt gibt Nicht-2xx-Antworten zurück, was dazu führt, dass Pub/Sub die Zustellung stoppt.
Die historyId ist eine monoton steigende Ganzzahl, die Gmail jedem Postfachänderungsereignis zuweist. Sie fungiert als inkrementeller Synchronisationscursor. Wenn Sie registrieren Benutzer ansehen, Gmail gibt eine historyId-Baseline zurück, die den aktuellen Zustand darstellt. Nachfolgende Gmail-Push-Benachrichtigungen enthalten eine neue historyId. Sie übergeben Ihre gespeicherte (vorherige) historyId als startVerlaufId zu Benutzerverlauf Liste um alle Änderungen zwischen den beiden Punkten zu erhalten. Sie müssen die neueste historyId pro authentifiziertem Benutzer in Ihrer Datenbank speichern. HistoryIds, die älter als 7 Tage sind, geben einen 404-Fehler zurück.
Nicht direkt über die Gmail API – Pub/Sub ist der erforderliche Übertragungskanal für Gmail Push-Benachrichtigungen. Sie können die GCP-Infrastruktur jedoch vollständig umgehen, indem Sie eine einheitliche E-Mail-API wie Unipile, das als unabhängiges technisches Vermittler fungiert und auf der Grundlage jedes authentifizierten Nutzers die Pub/Sub-Schicht abstrahiert und Gmail-Push-Benachrichtigungen mit einer normalisierten Nutzlast an Ihren Webhook liefert. Kein GCP-Projekt, keine IAM-Berechtigung, keine Watch-Erneuerungs-Cron erforderlich.
Ausführen täglicher Cron-Job das ruft Benutzer ansehen für alle aktiven authentifizierten Benutzer. Speichern Sie die zurückgegebene historyId als neue Basislinie und aktualisieren Sie den gespeicherten Ablaufzeitstempel. Behandeln Sie benutzerspezifische Fehler, ohne den Batch abzubrechen: eine 401 bedeutet, dass der OAuth-Aktualisierungstoken widerrufen wurde (Benutzer muss neu autorisieren), eine 404 bedeutet, dass die Überwachung bereits abgelaufen ist. Warten Sie niemals bis zum 7-tägigen Ablaufdatum, um zu erneuern – betrachten Sie den täglichen Lauf als Wartung, nicht als reaktive Korrektur.
Gmail API Push-Benachrichtigungen sind begrenzt auf ungefähr 1 Ereignis pro Sekunde pro authentifiziertem Benutzer. Bursts darüber werden gebündelt oder verzögert, nicht verworfen. Die Benutzerverlauf Liste Der Anruf kostet 5 Quota-Einheiten und Benutzer ansehen kostet 100 Einheiten pro Aufruf. Das standardmäßige tägliche Kontingent der Gmail API beträgt 1 Million Einheiten pro Projekt. Eine vollständige Aufschlüsselung der Limits pro Methode und der Verfahren zur Erhöhung des Kontingents finden Sie unter Gmail API-Ratenbegrenzungen-Leitfaden.
Brauchen Sie Hilfe bei der Einrichtung von Gmail API Push-Benachrichtigungen für Ihre App? Unser Team kann Sie dabei unterstützen.
DE 
EN 
FR 
ES 
IT 
BR 
NL 
PL 
TR