LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Outlook
Google Agenda
Word lid van de Slack-gemeenschapGmail API Pushmeldingen: Complete Gids voor Pub/Sub, Watch & Geschiedenis (2026)
Gmail API pushmeldingen end-to-end instellen: een Pub/Sub-onderwerp aanmaken, een watch-endpoint registreren, webhook-payloads decoderen, wijzigingen reconciliëren met gebruikers.geschiedenis.lijst, automatiseer het vernieuwen van horloges en sla de volledige GCP-configuratie over met een uniforme webhook-alternatief.
// 1. Registreer Gmail-watch via Unipile
const res = wacht op fetch('https://api8.unipile.com:13815/api/v1'
+ '/accounts/{id}/kijken', {
method: POST,
headers: {
'X-API-KEY': 'JOUW_API_SLEUTEL',
'Content-Type': "toepassing/json
},
body: JSON.rijgen({
webhook_url: 'https://app.you.com/webhooks/gmail'
})
});
// 2. Ontvang uniforme webhook-payload
app.post('/webhooks/gmail', (req, res) => {
const { event, account_id, e-mail } = req.body;
// gebeurtenis: "nieuwe_email" | geschiedenisId geabstraheerd
nieuweE-mailAfhandelen(e-mail);
});Wat zijn Gmail API pushmeldingen?
Voordat u Gmail API pushmeldingen in productie implementeert, is het nuttig om precies te begrijpen wat ze zijn, hoe ze verschillen van eenvoudige polling en welke infrastructuur ze vereisen.
Gmail API pushmeldingen zijn een realtime bezorgingsmechanisme dat Google Cloud Pub/Sub gebruikt om wijzigingsgebeurtenissen in de mailbox naar een door de ontwikkelaar gecontroleerd HTTPS-eindpunt te pushen. Wanneer een nieuw bericht arriveert of een bestaand bericht wordt gewijzigd, publiceert Gmail een melding met een gecodeerde geschiedenisId naar een Pub/Sub-onderwerp dat je beheert, dat vervolgens de gebeurtenis doorstuurt naar je webhook. Je server roept gebruikers.geschiedenis.lijst om de daadwerkelijke wijzigingen op te halen.
Gmail API pushmeldingen elimineren de noodzaak om herhaaldelijk aan te roepen Berichtenlijst op schema. Gebeurtenissen worden binnen enkele seconden na de wijziging van de mailbox geleverd, waardoor zowel de latentie als het gebruik van de API-quota wordt verminderd.
Het afleverkanaal is Google Cloud Pub/Sub, geen directe HTTP-callback van Gmail. Dit zorgt voor extra duurzaamheid: als uw eindpunt tijdelijk niet beschikbaar is, kan Pub/Sub de levering opnieuw proberen volgens de "ack deadline" van het abonnement.
Een Gmail API watch-eindpunt verloopt na 7 dagen. Uw toepassing moet dit proactief vernieuwen met een dagelijkse cron-taak, anders loopt u het risico om gebeurtenissen stilzwijgend te missen. Dit is een cruciaal operationeel detail dat wordt behandeld in de sectie Vernieuwing.
Gmail API pushmeldingen leveren gebeurtenissen binnen 1-10 seconden na de wijziging. Geen constante verversing betekent een lagere quotaverbruik van de Gmail API en een snellere reactietijd voor uw applicatie. Ideaal voor elk real-time gebruiksscenario op inboxniveau: CRM-synchronisatie, ticketsystemen, workflowautomatisering.
Polling Berichtenlijst Elke 60 seconden is eenvoudiger in te stellen, maar introduceert kunstmatige vertraging, verspilt quota voor lege reacties en schaalt slecht bij een groot aantal geauthenticeerde gebruikersaccounts. Alleen acceptabel voor prototypes met een laag volume.
Architectuur: watch + Pub/Sub + historyId in één flow
Gmail API pushmeldingen omvatten vier afzonderlijke lagen die na elkaar werken. Het begrijpen van elke laag voordat je code schrijft, voorkomt de meest voorkomende implementatiefouten.
Je POST naar https://gmail.googleapis.com/gmail/v1/users/me/watch met de naam van uw Pub/Sub-onderwerp en optioneel een labelfilter. Gmail retourneert een geschiedenisId en een vervaldatum Unix-tijdstempel. Opslaan beide. Dit horloge verloopt over 7 dagen.
Wanneer er een wijziging optreedt in de gevolgede mailbox (nieuw bericht, labelwijziging, lees/ongelezen statusomschakeling), publiceert Gmail een JSON-melding naar uw Cloud Pub/Sub-onderwerp. De payload is een base64-gecodeerd object dat het e-mailadres van de gebruiker en een nieuw geschiedenisId.
Uw Pub/Sub-abonnement stuurt het bericht door naar een geregistreerd HTTPS-push-eindpunt. Dit is uw webhook-URL, die binnen de ack deadline (standaard 10-600 seconden) moet reageren met HTTP 200-299. Een reactie die geen 2xx is, activeert automatische herhaalpogingen.
Decode de base64 Pub/Sub-berichtgegevens. Extraheer de nieuwe geschiedenisId. Vergelijk het met de laatsteGeschiedenisId opgeslagen in je database voor deze gebruiker.
Roepen gebruikers.geschiedenis.lijst met startGeschiedenisId instellen op uw opgeslagen waarde. Gmail retourneert alle wijzigingen (nieuwe berichten, labeltoevoegingen, verwijderingen) tussen de twee ID's. Update uw opgeslagen laatsteGeschiedenisId naar de nieuwe waarde. Gebruik nooit de historyId van de Pub/Sub-melding als startGeschiedenisId rechtstreeks.
Plan een dagelijkse cronjob om aan te roepen Gebruikers.watch opnieuw voor elk geauthenticeerd gebruikersaccount. Watch renewal is idempotent: een nieuwe aanroep vervangt de vorige vervaldatum. De teruggegeven geschiedenisId wordt je nieuwe basislijn.
Een monotoon stijgend geheel getal toegewezen door Gmail aan elke wijziging van een mailbox. Het is uw cursor voor incrementele synchronisatie. Sla altijd de laatste historyId per gebruiker op in uw database.
Het Gmail API-eindpunt dat een pushmeldingsabonnement voor een postvak registreert. Geeft een historyId-baseline en een Unix ms-verlooptijdstempel terug. Moet binnen 7 dagen worden vernieuwd.
Het reconciliatie-eindpunt. Gegeven een startHistoryId, retourneert het alle berichttoevoegingen, verwijderingen en labelwijzigingen die na dat punt hebben plaatsgevonden. Dit is waar je de daadwerkelijke berichtgegevens krijgt.
Vereisten: GCP-project, Pub/Sub-onderwerp, IAM-machtigingen
Gmail API-pushmeldingen vereisen drie bronnen aan de GCP-kant voordat u uw eerste Gebruikers.watch De meeste implementatiefouten zijn terug te voeren op een ontbrekende IAM-toekenning aan het Pub/Sub-onderwerp, de stap die ontwikkelaars het vaakst overslaan.
In de Google Cloud Console, maak een nieuw project aan of selecteer een bestaand project. Navigeer naar API's en Services > Bibliotheek en schakel de Gmail API. Hieronder heb je ook het Cloud Pub/Sub API ingeschakeld in hetzelfde project. Zorg ervoor dat uw OAuth 2.0-clientreferenties het volgende bevatten: https://www.googleapis.com/auth/gmail.readonly scope (of een bredere scope indien je schrijftoegang nodig hebt). Voor multi-user applicaties, zie onze gids over Gmail OAuth 2.0-integratie en de Google OAuth app-verificatie vereisten.
In de GCP Console, onder Pub/Sub > Onderwerpen, klik Onderwerp maken. Geef het een naam zoals gmail-meldingen. De volledige onderwerpsnaam is projects/YOUR_PROJECT_ID/topics/gmail-notifications. U zult deze exacte tekenreeks doorgeven aan Gebruikers.watch in de onderwerpNaam veld.
Dit is de stap die de meeste ontwikkelaars missen. Gmail gebruikt een door Google beheerde serviceaccount (gmail-api-push@system.gserviceaccount.com) om meldingen naar uw Pub/Sub-onderwerp te publiceren. Zonder dit account te verlenen Pub/Sub Publisher rol op je onderwerp, Gebruikers.watch zal slagen, maar er zullen nooit meldingen worden bezorgd. In de Console: Onderwerpen > selecteer uw onderwerp > Machtigingen > Hoofdpersoon toevoegen > voer gmail-api-push@system.gserviceaccount.com rol toewijzen Pub/Sub Publisher.
Onder uw Pub/Sub-onderwerp, maakt u een Pushabonnement. Stel het push-eindpunt in op uw HTTPS-webhook-URL (moet een geldig TLS-certificaat gebruiken, zelfondertekende certificaten worden geweigerd). Configureer optioneel een header voor tokenvalidatie zodat uw eindpunt verzoeken van Google kan verifiëren. Noteer de abonnementsnaam; deze hebt u mogelijk nodig om leveringsstatistieken in Cloud Monitoring te controleren.
100-gebruikerslimiet op niet-geverifieerde apps: Als je OAuth-verificatiescherm in de status "Testen" staat, kunnen slechts 100 Gmail-accounts je app autoriseren. Deze limiet is van toepassing op alles OAuth-bereiken, inclusief het watch-eindpunt. Voor productie-implementaties met meer dan 100 gebruikers moet u het verificatieproces van Google voltooien. Zie onze volledige gids op 100-gebruikerslimiet en verificatiepad.
Geen Pub/Sub onderwerp. Geen IAM-machtiging. Geen 7-daagse watch renewal cron. Bouw Gmail-pushmeldingen met één webhook-URL.
Stap-voor-stap: maak onderwerp, abonnement en user.watch aan
Met de vereiste GCP-instellingen, hier is de volledige code om een Gmail API watch-eindpunt te registreren in zowel Node.js als Python, met behulp van de Google API client-bibliotheek.
const { Google } = require('googleapis');
// Ga ervan uit dat de OAuth2-client al is geautoriseerd met een geldig toegangstoken
// Zie: https://www.unipile.com/gmail-oauth-20-integration-complete-guide/
async function registreerGmailWatch(auth, userId = "mij) {
const gmail = google.gmail({ versie: 'v1', auth });
const response = wacht op gmail.gebruikers.horloge({
gebruikersId,
requestBody: {
// Uw volledige Pub/Sub-onderwerptitel
onderwerpNaam: ''projecten/UW_PROJECT-ID/onderwerpen/gmail-meldingen'',
// Optioneel: alleen filteren op specifieke labels
labelIds: ['POSTVAK'],
labelFilterGedrag: 'INSLUITEN'
}
});
const { historyId, expiration } = response.data;
// Sla dit per gebruiker op in uw database
wacht op db.upsert({
gebruikersId,
laatsteGeschiedenisId: geschiedenisId,
// vervaldatum is Unix ms timestamp
watchVervaldatum: nieuw Datum(parseIntVervaldatum
});
console.log(`Watch geregistreerd. historyId: ${historyId}, verloopt: ${expiration}`);
return antwoord.gegevens;
}van googleapiclient.discovery importeer bouwen
van google.oauth2.credentials importeer Geloofsbrieven
def registreer_gmail_watch(aanmeldingsgegevens: Aanmeldingsgegevens, gebruiker_id: straal = "mij) -> dict:
"Gmail API pushmeldingen registreren watch voor een geauthenticeerde gebruiker."
service = bouwen('Gmail', 'v1', credentials=credentials)
lichaam = {
'onderwerpNaam': ''projecten/UW_PROJECT-ID/onderwerpen/gmail-meldingen'',
'labelIds': ['POSTVAK'],
'labelFilterGedrag': 'INSLUITEN'
}
resultaat = service.users().horloge(gebruikerId=user_id, body=body).uitvoeren()
# Sla per gebruiker op in je database
db_upsert(user_id=user_id,
laatste_geschiedenis_id=resultaat['geschiedenisId'],
watch_expiry=heel(result['vervaldatum']) // 1000)
return resultaatDe payload van de Gmail API push notificaties webhook verwerken
Wanneer Gmail een pushmelding verzendt, ontvangt uw HTTPS-eindpunt een Pub/Sub pushbericht. De werkelijke wijzigingsgegevens van Gmail zijn dubbel gecodeerd: de Pub/Sub-envelop bevat een base64-gecodeerde JSON-tekenreeks die op zijn beurt de e-mail en historyId van de gebruiker bevat.
app.post('/webhooks/gmail', async (req, res) => {
// Onmiddellijk bevestigen: Pub/Sub retries op niet-2xx
res.status(200).einde();
proberen {
const message = req.body.message;
als return;
// Decodeer het base64 Pub/Sub data-veld
const gedecodeerd =
Buffer.van(bericht.data, "base64).toString('utf-8');
const lading= JSON.parsen(ontcijferd);
// payload = { emailAdres: "user@gmail.com", geschiedenisId: "12345" }
const { emailAddress, historyId } = payload;
// Wachtrij reconciliation (blokkeer de ack niet)
wacht op wachtrij.in de wachtrij zetten({ eMailadres, geschiedenisId });
} vangen (err) {
// Log maar gooi niet opnieuw: ack is al verzonden
console.fout('Webhook parsefout', err);
}
});importeer base64, json
van kolf importeer Flask, verzoek, jsonify
app = Fles(__name__)
@app.route('/webhooks/gmail', methoden=[POST])
def gmail_webhook():
# Onmiddellijk bevestigen
data = verzoek.haal_json(stil=True) of {}
bericht = data.krijgen('bericht', {})
als 'gegevens' in bericht:
# Base64 decoderen en JSON parseren
ruw = base64.b64decode(bericht['gegevens'] + '==')
lading= json.ladingenruw
# { "emailAddress": "user@gmail.com", "historyId": "12345" }
e-mail = payload.krijgen('e-mailadres')
history_id = payload.krijgen('geschiedenisId')
# Asynchrone afstemming in de wachtrij plaatsen
enqueuereconcile(e-mail, geschiedenis_id)
return jsonificeren({}), 200Wijzigingen verzoenen met gebruikers.history.list
De Pub/Sub-melding vertelt u alleen er is iets veranderd. Het vertelt je niet wat. Je moet bellen gebruikers.geschiedenis.lijst met uw opgeslagen laatsteGeschiedenisId als de cursor om de werkelijke delta te krijgen.
async function geschiedenis_verzoenen(auth, e-mailadres, nieuweGeschiedenisId) {
const gmail = google.gmail({ versie: 'v1', auth });
// Haal onze opgeslagen laatsteHistoryId op voor deze gebruiker
const gebruiker = wacht op db.vindOpEmail(e-mailadres);
const startGeschiedenisId = user.laatsteGeschiedenisId;
proberen {
const response = wacht op gmail.users.geschiedenis.list({
userId: "mij,
// Gebruik de OPGESLAGEN ID als cursor: NIET de nieuwe notification historyId
startGeschiedenisId,
// Filteren op alleen berichttoevoegingen (optioneel)
historyTypes: ['berichtToegevoegd']
});
const histories = response.data.history || [];
voor (const register van de geschiedenissen) {
voor (const added of (record.messagesAdded || [])) {
// toegevoegd.bericht = { id, threadId, labelIds }
wacht op verwerkNieuwBericht(authenticatie, toegevoegd.bericht.id);
}
}
// Cursor bijwerken naar de nieuwe historyId uit de melding
wacht op db.updateLaatsteGeschiedenisId(e-mailadres, nieuweGeschiedenisId);
} vangen (err) {
als (fout.code === 404) {
// historyId is te oud (> 7 dagen). Herinitialiseer vanuit messages.list
wacht op herinitialiserenVanBerichten(auth, e-mailadres);
} anders {
gooien fout;
}
}
}historyId in de Pub/Sub-melding is de huidige staat. Jouw startGeschiedenisId moet de vorige dat je hebt opgeslagen. Door de notification historyId direct te gebruiken als startHistoryId, mis je alle wijzigingen tussen je laatste verwerkte punt en nu.
Pub/Sub kan dezelfde melding meerdere keren afleveren. Uw reconciliatielogica moet idempotent zijn: het tweemaal verwerken van dezelfde bericht-ID mag geen effect hebben. Gebruik een unieke beperking op bericht-ID's in uw database, of controleer op bestaan alvorens in te voegen.
Als je een startHistoryId opgeeft die ouder is dan 7 dagen, geeft de API een 404 terug. Val in dat geval terug naar Berichtenlijst om opnieuw te synchroniseren vanaf nul, vervolgens bellen Gebruikers.watch opnieuw om een frisse historyId-basislijn te krijgen.
Als er veel wijzigingen hebben plaatsgevonden tussen uw laatste historyId en nu, kan het geschiedenis.lijst antwoord gepagineerd zijn. Volg altijd volgendePaginatoken totdat uitgeput bent voordat u uw opgeslagen cursor bijwerkt.
Strategie voor het vernieuwen van abonnementen: het probleem van de 7-daagse vervaldatum
Een Gmail API-watch verloopt stilzwijgend na 7 dagen. Er is geen automatische verlenging en geen waarschuwingsmelding. Als uw cron mislukt, komen er wel nieuwe e-mails binnen, maar ontvangt uw applicatie niets - zonder fouten aan beide kanten. Dit maakt verlenging het meest operationeel kritieke onderdeel van elke implementatie van Gmail pushmeldingen.
Vernieuw dagelijks, niet elke 7 dagen. Voer uw vernieuwings-cron elke 24 uur uit (niet om de 6 of 7 dagen). Controle op vernieuwing is idempotent - aanroepen Gebruikers.watch Opnieuw reset de timer van 7 dagen. Een dagelijkse cadans geeft je een veiligheidsmarge van 6 dagen tegen tijdelijke storingen.
// 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 handelt het vernieuwen van horloges automatisch af namens elke geauthenticeerde gebruiker. Geen cronjob nodig.
Gmail API pushmeldingen oplossen
Dit zijn de vier foutklassen die bijna alle mislukkingen van Gmail pushmeldingen verklaren. De meeste hebben één hoofdoorzaak zodra je weet waar je naar moet zoeken.
| Fout / Symptoom | Oorzaak | Repareer | Ernst |
|---|---|---|---|
| 403 op users.watch | Gmail serviceaccount gmail-api-push@system.gserviceaccount.com kreeg de rol van Pub/Sub Publisher op het onderwerp niet toegekend. |
In de GCP Console: Pub/Sub > Onderwerpen > uw onderwerp > Machtigingen. Voeg het serviceaccount toe met de rol Pub/Sub-uitgever. | Blokkeerder |
| horloge slaagt maar ontvangt geen meldingen | De push-eindpunt-URL van de Pub/Sub-abonnement is niet geregistreerd, geweigerd door Google (ongeldige TLS), of het type push-abonnement is "Pull" in plaats van "Push". | Verifieer dat uw abonnement van het type "Push" is met uw webhook-URL als eindpunt. Zorg ervoor dat het TLS-certificaat geldig is (niet zelfondertekend). Test-eindpunt retourneert 200. | Blokkeerder |
| 404 op geschiedenis.lijst - historyId te oud | Uw opgeslagen laatsteGeschiedenisId is ouder dan 7 dagen. Gmail bewaart alleen geschiedenis gedurende 7 dagen. |
Terugvallen naar Berichtenlijst opnieuw synchroniseren. Daarna bellen Gebruikers.watch voor een nieuwe geschiedenisId-basislijn. |
Herstelbaar |
| Validatietoken van push-eindpunt afgewezen | Google stuurt een X-Goog-Channel-Token header. Als uw endpoint deze valideert en de token niet overeenkomt, retourneert het een non-2xx en Pub/Sub probeert het onbeperkt opnieuw. | Schakel de tokenvalidatie uit tijdens de eerste installatie, of configureer dezelfde tokenwaarde in de GCP-abonnementinstellingen en uw applicatieconfiguratie. | Herstelbaar |
gmail-api-push@system.gserviceaccount.com niet toegekend Pub/Sub Publisher.Quota's en limieten voor Gmail API pushmeldingen
Gmail API pushmeldingen hebben specifieke quota beperkingen die verschillen van standaard Gmail API quota. De belangrijkste beperking is de doorvoercapaciteit per gebruikersevenement.
Maximale Pub/Sub-notificatiesnelheid per geauthenticeerde gebruiker. Piekbelastingen kunnen dit tijdelijk overschrijden, maar worden na verloop van tijd gereguleerd. Als een mailbox continu meer dan 1 wijziging per seconde ontvangt, worden meldingen gebundeld of vertraagd, niet gedropt.
Maximale vervaldatum van watches. Alle watches moeten vóór deze deadline worden vernieuwd. Gmail bewaart geschiedenis.lijst data voor hetzelfde 7-daagse venster - een historyId ouder dan 7 dagen retourneert een 404.
Standaard dagelijkse quotum van de Gmail API per project. Elk gebruikers.geschiedenis.lijst Bellen kost 5 eenheden. Gebruikers.watch kost 100 eenheden per oproep. Plan uw reconciliatievolume dienovereenkomstig.
Voor een diepere uitsplitsing van quota per methode, limieten per gebruiker en procedures voor het aanvragen van quotaverhogingen, raadpleeg onze speciale Begeleiding over Gmail API-limieten en -quota.
Afwegingen: Pub/Sub versus IMAP IDLE versus polling versus uniforme webhook
Het kiezen van de juiste Gmail pushmeldingenstrategie hangt af van uw infrastructuurbeperkingen, de behoeften aan providerdekking en de operationele tolerantie. Hier is een directe vergelijking van de vier benaderingen.
| Aanpak | Latency | Installatiecomplexiteit | Multi-provider | Ops overhead |
|---|---|---|---|---|
| Gmail Pub/Sub-abonnement | 1-10s | Hoog - GCP, IAM, cron | Alleen Gmail | 7-daagse vernieuwings-cron |
| IMAP IDLE | 1-30s | Medium - persistente TCP | Gmail + IMAP servers | keep-alive beheer |
| Polling | 30-300s vertraging | Laag | Elke aanbieder | Hoge quota verbranding |
| Verenigde webhook (Unipile) | 1-10s | Laag - 1 webhook-URL | Gmail + Outlook + IMAP | Niet van toepassing - beheerd |
De Alternatieve Unified Webhook: Gmail + Outlook + IMAP met één eindpunt
Als je Gmail API pushmeldingen nodig hebt plus realtime gebeurtenissen van Outlook en IMAP-mailboxen - met een uniform payloadformaat en zonder GCP-infrastructuur - Unipile's Gmail API abstracteert de hele Pub/Sub-laag. Als onafhankelijke technische tussenpersoon treedt Unipile op namens elke geauthenticeerde gebruiker om e-mailgebeurtenissen te leveren via een enkele webhook-URL die uw applicatie al beheert.
Geen Pub/Sub-onderwerp om te maken, geen IAM-toekenning om te configureren, geen GCP-project om te onderhouden. Registratie en verlenging van de watch gebeuren binnen de infrastructuur van Unipile, niet de jouwe.
De 7-daagse watch-vervaldatum wordt afgehandeld namens elke gekoppelde account. U heeft nooit een verlengings cronjob nodig. Als een vernieuwingstoken wordt ingetrokken, toont Unipile een webhook voor de accountstatus in plaats van gebeurtenissen stilzwijgend weg te laten.
U ontvangt een geparseerd, genormaliseerd e-mailobject - geen ruwe historyId. Het is niet nodig om te bellen gebruikers.geschiedenis.lijst of beheert per gebruiker cursors. Unipile lost de delta op en levert gestructureerde berichtgegevens.
Hetzelfde webhook-eindpunt en hetzelfde eventschema dekken Gmail, Outlook (inclusief Microsoft 365 / Exchange Online) en IMAP. Geen integratielogica per provider, geen aparte webhooks voor Microsoft Graph-abonnementen versus Gmail pub/sub-notificaties.
// 1. Koppel Gmail-account van gebruiker (OAuth namens geauthenticeerde gebruiker)
// Zie: https://developer.unipile.com/docs/getting-started
// 2. Configureer uw webhook eenmalig
const config = wacht op fetch('https://api8.unipile.com:13815/api/v1/webhooks', {
method: POST,
headers: {
'X-API-KEY': 'JOUW_API_SLEUTEL',
'Content-Type': "toepassing/json
},
body: JSON.rijgen({
url: 'https://app.you.com/webhooks/email',
evenementen: ['e-mail.nieuw']
})
});
// 3. Uniforme payload afhandelen: dezelfde structuur voor Gmail, Outlook, IMAP
app.post('/webhooks/email', (req, res) => {
const { event, account_id, email } = req.body;
// gebeurtenis: "email.nieuw"
// email.provider: "gmail" | "outlook" | "imap"
// e-mail.onderwerp, .van, .aan, .body_html...
// Geen historyId. Geen base64. Geen cursor om te beheren.
verwerkInkomendeEメール(e-mail);
res.status(200).einde();
});Unipile bouwt geen parallel archief op en slaat de inhoud van berichten niet onafhankelijk op. Toegang is beperkt tot de sessie van elke geauthenticeerde gebruiker. Unipile haalt e-mailgegevens op namens elke gekoppelde account en levert deze in realtime aan uw webhook-eindpunt. Geen gegevens worden langer bewaard dan nodig is om de webhook-payload te leveren.
Unipile is een onafhankelijke technische tussenpersoon. Het treedt op namens elke geauthenticeerde gebruiker die uw toepassing via OAuth heeft geautoriseerd. Unipile is niet gelieerd aan, goedgekeurd door of gesponsord door Google. Het gebruikt dezelfde Gmail API-endpoints zoals beschreven in deze handleiding, op basis van per gebruiker, onder de eigen OAuth-autorisatie van elke gebruiker. Inloggegevens worden nooit gedeeld tussen accounts. Alle bewerkingen zijn een beslissing aan de kant van de klant die is gedelegeerd aan de infrastructuur van Unipile.
Unipile brengt de Gmail API rate limits en quota beperkingen over naar uw applicatie via zijn eigen quota beheerlaag. Beslissingen over het aantal gebeurtenissen, de pollingfrequentie en de berichtafhandeling blijven een beslissing van de klant. Unipile toont Gmail API quotafouten als gestructureerde webhookgebeurtenissen, zodat uw applicatie hier adequaat op kan reageren.
Koppel uw eerste Gmail-account in enkele minuten. Geen GCP-project. Geen Pub/Sub-facturering. Geen watch renewal cron. Zie onze Gids voor Gmail API-integratie en de Overzicht e-mail API-providers om alle ondersteunde providers te verkennen.
Gmail API Pushmeldingen - Veelgestelde vragen
Antwoorden op de meest voorkomende vragen over Gmail API pushmeldingen, Pub/Sub-configuratie, historyId, vernieuwing van watch en alternatieven voor realtime e-mailsynchronisatie.
Gmail API pushmeldingen gebruiken Google Cloud Pub/Sub om realtime mailboxwijzigingsevenementen naar uw HTTPS-webhook te sturen. U registreert een watch endpoint via Gebruikers.watch, die een Gmail-mailbox koppelt aan een Pub/Sub-onderwerp dat je bezit. Wanneer er een wijziging optreedt - een nieuw bericht, een labelwijziging - publiceert Gmail een melding naar dat onderwerp, dat deze doorstuurt naar je push webhook. Je webhook roept vervolgens gebruikers.geschiedenis.lijst met een opgeslagen geschiedenisId cursor om het werkelijke berichtdelta op te halen. De Pub/Sub-melding zelf bevat alleen het e-mailadres gebruiker en een nieuwe historyId - niet de berichtinhoud.
Gebruikers.watch registreert een pushmeldingabonnement voor een Gmail-mailbox en retourneert een historyId-baseline. Het is het toegangspunt dat Gmail verbindt met uw Pub/Sub-onderwerp. gebruikers.geschiedenis.lijst het herstel-eindpunt dat u aanroept na ontvangst van een Gmail pushmelding om de werkelijke wijzigingen (berichttoevoegingen, verwijderingen, labelwijzigingen) te verkrijgen die hebben plaatsgevonden sinds uw opgeslagen geschiedenis-ID-cursor. Watch vertelt Gmail waar waarschuwingen naartoe moeten worden verzonden. History vertelt u wat er daadwerkelijk is gewijzigd.
Gmail API watch endpoints verlopen na 7 dagen. Beste praktijk is om een dagelijkse cron taak in plaats van elke 6 of 7 dagen, zodat je een buffer van meerdere dagen hebt tegen tijdelijke storingen. Het vernieuwen van de wachtwoord is idempotent: een nieuwe Gebruikers.watch Aanroepen reset simpelweg de timer en retourneert een nieuwe geschiedenis-id baseline. Verloop gebeurt stilzwijgend - er is geen waarschuwing, dus een mislukte cron betekent gemiste gebeurtenissen zonder fouten aan beide kanten.
De meest voorkomende oorzaak is een ontbrekende IAM-toekenning. Gmail gebruikt de serviceaccount gmail-api-push@system.gserviceaccount.com om te publiceren naar uw Pub/Sub-onderwerp. Zonder de Pub/Sub Publisher rol op je onderwerp voor dit account, Gebruikers.watch werkt, maar er worden nooit meldingen bezorgd. Andere oorzaken: het abonnementstype is "Pull" in plaats van "Push", een ongeldig TLS-certificaat op uw webhook-eindpunt, of uw eindpunt retourneert niet-2xx-antwoorden waardoor Pub/Sub stopt met bezorgen.
De geschiedenisId is een monotoon stijgend geheel getal dat Gmail toewijst aan elke gebeurtenis van een postvakwijziging. Het fungeert als een incrementele synchronisatiecursor. Wanneer u zich registreert Gebruikers.watch, Gmail geeft een historyId terug die de huidige status vertegenwoordigt. Latere Gmail pushmeldingen bevatten een nieuw historyId. Je geeft je opgeslagen (vorige) historyId door als startGeschiedenisId naar gebruikers.geschiedenis.lijst om alle wijzigingen tussen de twee punten te verkrijgen. Je moet de laatste historyId per geauthenticeerde gebruiker in je database opslaan. HistoryIds ouder dan 7 dagen retourneren een 404-fout.
Niet direct via de Gmail API - Pub/Sub is het vereiste leveringskanaal voor pushmeldingen van Gmail. Je kunt de GCP-infrastructuur echter volledig overslaan door een uniforme e-mail-API te gebruiken zoals Eenpaal, die fungeert als een onafhankelijke technische intermediair namens elke geauthenticeerde gebruiker, abstraheert de Pub/Sub-laag en levert Gmail pushmeldingen aan uw webhook met een genormaliseerde payload. Geen GCP-project, geen IAM-toekenning, geen cron voor het vernieuwen van waarschuwingen vereist.
Uitvoeren dagelijkse cron taak dat vraagt Gebruikers.watch voor alle actieve geauthenticeerde gebruikers. Sla de geretourneerde historyId op als de nieuwe baseline en update de opgeslagen vervaldatum. Verwerk fouten per gebruiker zonder de batch af te breken: een 401 betekent dat de OAuth-vernieuwingstoken is ingetrokken (gebruiker moet opnieuw autoriseren), een 404 betekent dat de watch al verlopen is. Wacht nooit tot de 7-daagse vervaldatum om te vernieuwen - behandel de dagelijkse uitvoering als onderhoud, niet als een reactieve oplossing.
Gmail API pushmeldingen zijn beperkt tot ongeveer 1 gebeurtenis per seconde per geauthenticeerde gebruiker. Uitbarstingen hierboven worden gebundeld of uitgesteld, niet weggegooid. De gebruikers.geschiedenis.lijst kost bellen 5 quotum eenheden en Gebruikers.watch kost 100 eenheden per aanroep. Het standaard dagelijkse quotum voor de Gmail API is 1 miljoen eenheden per project. Voor een volledige uitsplitsing van limieten per methode en procedures voor quotumverhoging, zie onze Gmail API limieten gids.
Hulp nodig bij het instellen van Gmail API pushmeldingen voor uw app? Ons team kan u erdoorheen helpen.
NL 
EN 
FR 
ES 
DE 
IT 
BR 
PL 
TR