LinkedIn
Instagram
WhatsApp
Telegramma
Gmail
Prospettiva
Calendario di Google
Partecipare alla comunità SlackAPI Gmail Notifiche pushGuida completa a Pub/Sub, Watch e History (2026)
Configurazione delle notifiche push dell'API Gmail end-to-end: crea un argomento Pub/Sub, registra un endpoint di watch, decodifica i payload dei webhook, riconcilia le modifiche con Elenco cronologia utenti, automatizzare il rinnovo degli orologi, ed evitare l'intera configurazione di GCP con un'alternativa webhook unificata.
// 1. Registra l'aggiornamento di Gmail tramite Unipile
const res = await fetch('https://api8.unipile.com:13815/api/v1'
+ '/accounti/{id}/guarda', {
method: 'POST',
headers: {
'X-API-KEY': 'CHIAVE_API_TUA',
'Content-Type': 'application/json'
},
body: JSON.stringere({
webhook_url: 'https://app.you.com/webhooks/gmail'
})
});
// 2. Ricevi payload webhook unificato
app.posta('/webhooks/gmail', (req, res) => {
const { evento, account_id, email } = req.body;
evento: "nuova_email" | historyId astratto
gestisciNuovaEmail(e-mail);
});Le notifiche push dell'API Gmail sono un meccanismo che consente alle applicazioni di ricevere informazioni in tempo reale sulle modifiche apportate alle caselle di posta degli utenti.
Prima di implementare le notifiche push dell'API Gmail in produzione, è utile capire esattamente cosa sono, in cosa differiscono dal semplice polling e quali infrastrutture richiedono.
Le notifiche push dell'API Gmail sono un meccanismo di recapito in tempo reale che utilizza Google Cloud Pub/Sub per inviare eventi di modifica della casella di posta a un endpoint HTTPS controllato dallo sviluppatore. Quando arriva un nuovo messaggio o viene modificato un messaggio esistente, Gmail pubblica una notifica contenente un codificato idStoria a un topic Pub/Sub di tua proprietà, che a sua volta inoltra quell'evento al tuo webhook. Il tuo server chiama Elenco cronologia utenti per recuperare le modifiche effettive.
Le notifiche push dell'API Gmail eliminano la necessità di chiamare ripetutamente messaggi.elenco su una pianificazione. Gli eventi vengono consegnati entro pochi secondi dalla modifica della casella di posta, riducendo sia la latenza che l'utilizzo della quota API.
Il canale di recapito è Google Cloud Pub/Sub, non un callback HTTP diretto da Gmail. Questo aggiunge durabilità: se il tuo endpoint non è temporaneamente disponibile, Pub/Sub può ritentare la consegna in base alla scadenza di conferma della sottoscrizione.
Un endpoint di watch dell'API di Gmail scade dopo 7 giorni. La tua applicazione deve rinnovarlo proattivamente con un cron job giornaliero o rischiare di perdere eventi silenziosamente. Questo è un dettaglio operativo critico trattato nella sezione Rinnovo.
Le notifiche push dell'API Gmail inviano eventi entro 1-10 secondi dalla modifica. Nessun polling costante significa un minor consumo di quote sull'API Gmail e tempi di reazione più rapidi per la tua applicazione. Ideale per qualsiasi caso d'uso in tempo reale a livello di casella di posta: sincronizzazione CRM, sistemi di ticketing, automazione dei flussi di lavoro.
Sondaggio messaggi.elenco ogni 60 secondi è più semplice da configurare ma introduce un ritardo artificiale, spreca quote su risposte vuote e scala male su un gran numero di account utente autenticati. Accettabile solo per prototipi a basso volume.
Architettura: watch + Pub/Sub + historyId in un unico flusso
Le notifiche push dell'API Gmail coinvolgono quattro layer distinti che lavorano in sequenza. Comprendere ciascun layer prima di scrivere codice previene gli errori di implementazione più comuni.
Invii un POST a https://gmail.googleapis.com/gmail/v1/users/me/watch con il nome del tuo argomento Pub/Sub e, facoltativamente, un filtro di etichette. Gmail restituisce un idStoria e un scadenza Timestamp Unix. Memorizza entrambi. Questo orologio scade tra 7 giorni.
Quando si verifica una qualsiasi modifica nella casella di posta monitorata (nuovo messaggio, modifica etichetta, attivazione/disattivazione lettura/non lettura), Gmail pubblica una notifica JSON sul tuo argomento Cloud Pub/Sub. Il payload è un oggetto codificato in base64 contenente l'indirizzo email dell'utente e un nuovo idStoria.
La tua sottoscrizione Pub/Sub inoltra il messaggio a un endpoint push HTTPS registrato. Questo è il tuo URL webhook, che deve rispondere con HTTP 200-299 entro il _ack deadline_ (predefinito 10-600 secondi). Una risposta non 2xx attiva i tentativi automatici.
Decodifica i dati del messaggio Pub/Sub in base64. Estrai il nuovo idStoria. Confrontalo con il ultimoIdCronologia memorizzati nel tuo database per questo utente.
Chiama Elenco cronologia utenti con startHistoryId imposta al tuo valore memorizzato. Gmail restituisce tutte le modifiche (nuovi messaggi, aggiunte di etichette, eliminazioni) tra i due ID. Aggiorna il tuo memorizzato ultimoIdCronologia al nuovo valore. Non utilizzare mai historyId dalla notifica Pub/Sub come startHistoryId direttamente.
Pianifica un cron job giornaliero per chiamare utenti.guarda di nuovo per ogni account utente autenticato. Il rinnovo della vigilanza è idempotente: una nuova chiamata sostituisce la scadenza precedente. Il valore restituito idStoria diventa la tua nuova linea di base.
Un intero monotonicamente crescente assegnato da Gmail a ogni modifica della casella di posta. È il tuo cursore per la sincronizzazione incrementale. Archivia sempre l'ultimo historyId per utente nel tuo database.
L'endpoint dell'API di Gmail che registra una sottoscrizione di notifica push per una casella di posta. Restituisce una baseline historyId e un timestamp Unix in millisecondi di scadenza. Deve essere rinnovato entro 7 giorni.
L'endpoint di riconciliazione. Dato uno startHistoryId, restituisce tutte le aggiunte, cancellazioni e modifiche alle etichette dei messaggi avvenute dopo quel punto. È qui che ottieni i dati effettivi dei messaggi.
Prerequisiti: progetto GCP, argomento Pub/Sub, concessione IAM
Le notifiche push dell'API Gmail richiedono tre risorse lato GCP prima del tuo primo utenti.guarda chiamata. La maggior parte dei fallimenti di implementazione sono riconducibili a una mancata autorizzazione IAM sull'argomento Pub/Sub, il passaggio che gli sviluppatori saltano più frequentemente.
Nella Google Cloud Console, crea o seleziona un progetto esistente. Naviga su API e Servizi > Libreria e abilita il API Gmail. Hai anche bisogno del Cloud Pub/Sub API abilitati nello stesso progetto. Assicurati che le tue credenziali client OAuth 2.0 includano https://www.googleapis.com/auth/gmail.readonly ambito (o un ambito più ampio se hai bisogno di usare la scrittura). Per le applicazioni multi-utente, consulta la nostra guida su Integrazione Gmail OAuth 2.0 e il Verifica dell'app Google OAuth requisiti.
Nella console GCP sotto Pub/Sub > Argomenti, fare clic Crea argomento. Dai un nome come notifiche-gmail. Il nome completo dell'argomento sarà projects/IL_TUO_PROJECT_ID/topics/notifiche-gmail. Lo passerai questa esatta stringa a utenti.guarda nel nomeArgomento campo.
Questo è il passaggio che la maggior parte degli sviluppatori perde. Gmail utilizza un account di servizio gestito da Google (gmail-api-push@system.gserviceaccount.com) per pubblicare notifiche sul tuo argomento Pub/Sub. Senza concedere a questo account il Pub/Sub Publisher ruolo sul tuo argomento, utenti.guarda avrà successo ma nessuna notifica verrà mai recapitata. Nella Console: Topics > seleziona il tuo argomento > Permissions > Add principal > inserisci gmail-api-push@system.gserviceaccount.com assegna ruolo Pub/Sub Publisher.
Sotto il tuo argomento Pub/Sub, crea un Sottoscrizione push. Imposta l'endpoint push sull'URL del tuo webhook HTTPS (deve utilizzare un certificato TLS valido, i certificati autofirmati vengono rifiutati). Opzionalmente, configura un header di validazione del token in modo che il tuo endpoint possa verificare che le richieste provengano da Google. Prendi nota del nome della sottoscrizione, potrebbe essere necessario per monitorare le metriche di consegna in Cloud Monitoring.
Limite di 100 utenti per le app non verificate: Se la schermata di consenso OAuth è in stato "Test", solo 100 account Gmail possono autorizzare la tua app. Questo limite si applica a tutto Ambiti OAuth, incluso l'endpoint di monitoraggio. Per distribuzioni in produzione con più di 100 utenti, è necessario completare il processo di verifica di Google. Vedi la nostra guida completa su limite di 100 utenti e percorso di verifica.
Nessun argomento Pub/Sub. Nessuna concessione IAM. Nessuna pianificazione cron per il rinnovo della sorveglianza di 7 giorni. Crea notifiche push di Gmail con un URL webhook.
Passo dopo passo: crea argomento, sottoscrizione e utenti.watch
Con i prerequisiti di GCP in atto, ecco il codice completo per registrare un endpoint di watch per la Gmail API sia in Node.js che in Python, utilizzando la libreria client di Google API.
const { google } = require('googleapis');
// Presume che il client OAuth2 sia già autorizzato con un token di accesso valido
// Vedi: https://www.unipile.com/gmail-oauth-20-integration-complete-guide/
async function registraGmailWatch(auth, userId = 'me') {
const gmail = Google.gmail({ versione: 'v1', auth });
const response = await gmail.utenti.orologio({
ID utente,
requestBody: {
// Il tuo nome completo di argomento Pub/Sub
nomeArgomento: 'projects/IL_TUO_PROJECT_ID/topics/notifiche-gmail',
// Opzionale: filtra per etichette specifiche
idsEtichetta: ['POSTA IN ARRIVO'],
ComportamentoFiltroEtichetta: 'INCLUDI'
}
});
const { historyId, expiration } = response.data;
// Memorizza questi per utente nel tuo database
await database.upsert({
ID utente,
lastHistoryId: historyId,
// la scadenza è un timestamp in millisecondi Unix
scadenzaGuarda: new Data(parseIntscadenza
});
console.log(`Watch registrato. historyId: ${historyId}, scade: ${expiration}`);
return response.data;
}from googleapiclient.discovery import costruire
from google.oauth2.credenziali import Credenziali
def registra_gmail_watchcredenziali: Credenziali, user_id: strada = 'me') -> dict:
""""Registrare un listener per le notifiche push dell'API di Gmail per un utente autenticato.""""
servizio = costruire('gmail', 'v1', credenziali=credenziali)
corpo = {
'nomeArgomento': 'projects/IL_TUO_PROJECT_ID/topics/notifiche-gmail',
'labelIds': ['POSTA IN ARRIVO'],
'labelFilterBehavior': 'INCLUDI'
}
risultato = servizio.utenti().orologio(userId=user_id, body=body).eseguire()
# Memorizza i dati per utente nel database
db_upsert(id_utente=user_id,
ultimo_id_cronologia=risultato['cronologiaId'],
watch_expiry=int(risultato['scadenza']) // 1000)
return risultatoGestione del payload del webhook per le notifiche push dell'API Gmail
Quando Gmail invia una notifica push, il tuo endpoint HTTPS riceve un messaggio push di Pub/Sub. I dati effettivi della modifica di Gmail sono codificati in doppio: l'envelope di Pub/Sub contiene una stringa JSON codificata in base64 che a sua volta contiene l'email dell'utente e historyId.
app.posta('/webhooks/gmail', async (req, res) => {
// Riconoscimento immediato: Pub/Sub ritenta in caso di risposte non 2xx
res.stato(200).fine();
tentare {
const messaggio = req.body.messaggio;
se (!message?.data) restituisci;
// Decodifica il campo dati di Pub/Sub in base64
const decodificato =
Buffer.from(dati.messaggio, 'base64').toStringa('utf-8');
const carico utile = JSON.analizzare(decodificato);
// payload = { emailAddress: "user@gmail.com", historyId: "12345" }
const { emailAddress, historyId } = payload;
// Riconciliazione della coda (non bloccare l'ack)
await coda.accodare({ emailAddress, historyId });
} catch (err) {
// Registra ma non ri-lancia: ack era già stato inviato
console.errore('Errore di analisi webhook', errore);
}
});import base64, json
from fiaschetta import Flask, richiesta, jsonify
app = Fiasco(__name__)
@app.itinerario('/webhooks/gmail', methods=['POST'])
def gmail_webhook():
# Confermare immediatamente
dati = richiesta.ottieni_json(silenzioso=Vero) o {}
messaggio = dati.ottenere('messaggio', {})
se 'dati' in messaggio:
# Decodifica Base64 e analisi sintattica JSON
grezzo = base64.b64decode(messaggio['dati'] + '==')
carico utile = json.carichi(grezzo)
# { "emailAddress": "user@gmail.com", "historyId": "12345" }
email = payload.ottenere('indirizzoEmail')
history_id = payload.ottenere('cronologiaId')
#: Accodamento della riconciliazione asincrona
accodare_riconciliare(email, id_storia)
return jsonify({}), 200Riconciliare modifiche con utenti.history.list
La notifica Pub/Sub ti dice solo qualcosa è cambiato. Non dice cosa. Devi chiamare Elenco cronologia utenti con il tuo memorizzato ultimoIdCronologia come cursore per ottenere il delta effettivo.
async function riconciliaStorico(auth, indirizzoEmail, nuovoIdCronologia) {
const gmail = Google.gmail({ versione: 'v1', auth });
// Recupera il nostro lastHistoryId memorizzato per questo utente
const utente = await database.trova per email(indirizzoEmail);
const startHistoryId = user.lastHistoryId;
tentare {
const response = await gmail.users.history.list({
userId: 'me',
// Usa l'ID MEMORIZZATO come cursore: NON la nuova historyId della notifica
startHistoryId,
// Filtra solo per aggiunte di messaggi (opzionale)
tipiDiCronologia: ['messaggioAggiunto']
});
const storici = risposta.dati.storia || [];
per (const registra delle storie) {
per (const added of (record.messagesAdded || [])) {
// aggiunto.messaggio = { id, threadId, labelIds }
await elaboraNuovoMessaggio(auth, added.message.id);
}
}
// Aggiorna il cursore al nuovo historyId dalla notifica
await database.aggiornaUltimoIdCronologia(emailAddress, newHistoryId);
} catch (err) {
se (err.code === 404) {
// ID cronologia troppo vecchio (> 7 giorni). Reinizializza da messaggi.elenco
await ripristinaDaMessaggi(autenticazione, indirizzoEmail);
} altrimenti {
lanciare errore;
}
}
}historyId nella notifica Pub/Sub è il corrente stato. La startHistoryId deve essere il precedente valore che hai memorizzato. Utilizzare historyId della notifica direttamente come startHistoryId significa che perderai tutte le modifiche tra il tuo ultimo punto elaborato e ora.
Pub/Sub potrebbe recapitare la stessa notifica più volte. La tua logica di riconciliazione deve essere idempotente: l'elaborazione dello stesso ID messaggio due volte dovrebbe essere un'operazione nulla. Utilizza un vincolo univoco sugli ID messaggio nel tuo database o verifica l'esistenza prima di inserire.
Se passi uno startHistoryId più vecchio di 7 giorni, l'API restituisce un 404. In questo caso, esegui il fallback a messaggi.elenco per risincronizzare da zero, quindi chiama utenti.guarda ancora per ottenere una nuova base di historyId.
Se sono avvenute molte modifiche tra il tuo ultimo historyId e adesso, la risposta di history.list potrebbe essere paginata. Segui sempre tokenPaginaSuccessiva fino all'esaurimento prima di aggiornare il cursore memorizzato.
Strategia di rinnovo dell'orologio: il problema della scadenza di 7 giorni
Un watch della Gmail API scade silenziosamente dopo 7 giorni. Non c'è alcun rinnovo automatico né notifica di avviso. Se il tuo cron fallisce, arrivano nuove email ma la tua applicazione non riceve nulla - senza errori da nessuna delle due parti. Ciò rende il rinnovo la parte operativamente più critica di qualsiasi implementazione di notifiche push di Gmail.
Rinnovare giornalmente, non ogni 7 giorni. Esegui il tuo cron di rinnovo ogni 24 ore (non ogni 6 o 7 giorni). Watch renewal è idempotente - chiamando utenti.guarda riporta semplicemente il timer di 7 giorni a zero. Una cadenza giornaliera ti offre un margine di sicurezza di 6 giorni contro guasti transitori.
// 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 gestisce il rinnovo degli orologi automaticamente per conto di ciascun utente autenticato. Non è necessario alcun cron job.
Risoluzione dei problemi delle notifiche push dell'API di Gmail
Queste sono le quattro classi di errori che rappresentano quasi tutti i fallimenti delle notifiche push di Gmail. La maggior parte ha una singola causa principale una volta che sai cosa cercare.
| Errore / Sintomo | Causa principale | Risolvi | Gravità |
|---|---|---|---|
| 403 su users.watch | Account di servizio Gmail gmail-api-push@system.gserviceaccount.com non è stato concesso il ruolo di Publisher di Pub/Sub sull'argomento. |
Nella Console GCP: Pub/Sub > Argomenti > il tuo argomento > Permessi. Aggiungi l'account di servizio con il ruolo di Publisher Pub/Sub. | Bloccante |
| l'orologio funziona ma non riceve notifiche | L'URL dell'endpoint di push della sottoscrizione Pub/Sub non è registrato, è stato rifiutato da Google (TLS non valido) o il tipo di sottoscrizione di push è "Pull" anziché "Push". | Verifica che la tua sottoscrizione sia di tipo "Push" con il tuo URL webhook come endpoint. Assicurati che il certificato TLS sia valido (non autofirmato). Verifica che l'endpoint di test restituisca 200. | Bloccante |
| 404 su history.list - historyId troppo vecchio | Il tuo memorizzato ultimoIdCronologia è più vecchio di 7 giorni. Gmail conserva la cronologia solo per 7 giorni. |
Rinunciare a messaggi.elenco per risincronizzare. Poi chiama utenti.guarda per una nuova baseline historyId. |
Recuperabile |
| Token di validazione endpoint push rifiutato | Google invia un'intestazione X-Goog-Channel-Token. Se il tuo endpoint la verifica e il token non corrisponde, restituisce un codice di stato diverso da 2xx e Pub/Sub riprova all'infinito. | Disabilita la convalida dei token durante l'impostazione iniziale oppure configura lo stesso valore di token sia nelle impostazioni della sottoscrizione GCP che nella configurazione della tua applicazione. | Recuperabile |
gmail-api-push@system.gserviceaccount.com non concesso Publisher Pub/Sub.Quote e limiti di frequenza per le notifiche push dell'API di Gmail
Le notifiche push dell'API Gmail hanno vincoli di quota specifici che differiscono dai bucket di quota standard dell'API Gmail. Il vincolo principale è la velocità effettiva degli eventi per utente.
Massima frequenza di notifica Pub/Sub per utente autenticato. I picchi possono superarla temporaneamente, ma vengono limitati nel tempo. Se una casella di posta riceve più di 1 modifica al secondo in modo continuo, le notifiche verranno raggruppate o ritardate, non scartate.
Scadenza massima dell'abbonamento. Tutti gli abbonamenti devono essere rinnovati prima di tale data. Gmail conserva storia.elenco dati per la stessa finestra di 7 giorni - un historyId più vecchio di 7 giorni restituisce un 404.
Quota giornaliera predefinita della Gmail API per progetto. Ogni Elenco cronologia utenti La chiamata costa 5 unità. utenti.guarda costa 100 unità per chiamata. Pianifica il tuo volume di riconciliazione di conseguenza.
Per una disamina più approfondita delle quote per metodo, dei limiti per utente e delle procedure di richiesta di aumento delle quote, consulta la nostra guida dedicata Gmail API limiti di frequenza e quote guida.
Compromessi: Pub/Sub vs IMAP IDLE vs polling vs webhook unificato
La scelta della giusta strategia di notifiche push di Gmail dipende dai vincoli della tua infrastruttura, dalle esigenze di copertura del provider e dalla tolleranza operativa. Ecco un confronto diretto dei quattro approcci.
| Approccio | Latenza | Complessità di configurazione | Multi-provider | Costi operativi generali |
|---|---|---|---|---|
| Gmail Pub/Sub guardato | 1-10s | Avanzato - GCP, IAM, cron | Solo Gmail | rinnovo cron di 7 giorni |
| IMAP IDLE | 1-30 secondi | Medio - TCP persistente | Gmail + server IMAP | Gestione della connessione persistente |
| Sondaggio | Ritardo 30-300s | Basso | Qualsiasi fornitore | Bruciare in alta quota |
| Webhook unificato (Unipile) | 1-10s | Basso - 1 URL webhook | Gmail + Outlook + IMAP | Nessuno - gestito |
L'alternativa unificata ai webhook: Gmail + Outlook + IMAP con un unico endpoint
Se hai bisogno di notifiche push dell'API di Gmail più eventi in tempo reale da caselle di posta Outlook e IMAP – con un formato di payload unificato e senza infrastruttura GCP – Unipile API Gmail riassume l'intera interfaccia Pub/Sub. In qualità di intermediario tecnico indipendente, Unipile agisce per conto di ciascun utente autenticato per recapitare eventi email tramite un singolo URL webhook già controllato dalla tua applicazione.
Non occorre creare alcun argomento Pub/Sub, né configurare alcuna autorizzazione IAM, né gestire alcun progetto GCP. La registrazione e il rinnovo avvengono all'interno dell'infrastruttura di Unipile, non della tua.
La scadenza di 7 giorni dell'orologio è gestita per conto di ogni account collegato. Non è mai necessario un processo di rinnovo pianificato. Se un token di aggiornamento viene revocato, Unipile visualizza un webhook di stato dell'account invece di ignorare silenziosamente gli eventi.
Ricevi un oggetto email analizzato e normalizzato, non un historyId grezzo. Non è necessario chiamare Elenco cronologia utenti o gestire i cursori per singolo utente. Unipile risolve il delta e fornisce dati strutturati.
Lo stesso endpoint webhook e lo stesso schema di eventi coprono Gmail, Outlook (inclusi Microsoft 365 / Exchange Online) e IMAP. Nessuna logica di integrazione per provider, nessun webhook separato per le sottoscrizioni a Microsoft Graph rispetto alle notifiche pub/sub di Gmail.
// 1. Collega l'account Gmail dell'utente (OAuth per conto dell'utente autenticato)
// Vedi: https://developer.unipile.com/docs/getting-started
// 2. Configura il tuo webhook una volta
const configurazione = await fetch('https://api8.unipile.com:13815/api/v1/webhooks', {
method: 'POST',
intestazioni: {
'X-API-KEY': 'CHIAVE_API_TUA',
'Content-Type': 'application/json'
},
body: JSON.stringere({
url: 'https://app.you.com/webhooks/email',
eventi: ['email.nuova']
})
});
Gestisci payload unificati: stessa forma per Gmail, Outlook, IMAP
app.posta('/webhooks/email', (req, res) => {
const { event, account_id, email } = req.body;
// evento: "email.nuova"
// fornitore.email: "gmail" | "outlook" | "imap"
// oggetto.email, .da, .a, .corpo_html...
// Nessun historyId. Nessun base64. Nessun cursore da gestire.
elaboraEmailInEntrata(e-mail);
res.stato(200).fine();
});Unipile non crea un archivio email parallelo né memorizza il contenuto dei messaggi in modo indipendente. L'accesso è limitato alla sessione di ciascun utente autenticato. Unipile recupera i dati delle email per conto di ciascun account collegato e li consegna al tuo endpoint webhook in tempo reale. Nessun dato viene conservato oltre quanto necessario per fornire il payload del webhook.
Unipile è un intermediario tecnico indipendente. Agisce per conto di ciascun utente autenticato che ha autorizzato l'applicazione tramite OAuth. Unipile non è affiliata, approvata o sponsorizzata da Google. Utilizza gli stessi endpoint dell'API Gmail descritti in questa guida, su base per utente, sotto la propria autorizzazione OAuth di ciascun utente. Le credenziali non vengono mai condivise tra gli account. Tutte le operazioni sono una decisione lato cliente delegata all'infrastruttura di Unipile.
Unipile riporta i limiti di frequenza e i vincoli di quota dell'API Gmail alla tua applicazione attraverso il proprio livello di gestione delle quote. Le decisioni sul volume degli eventi, sulla frequenza di polling e sulla gestione dei messaggi rimangono una decisione lato cliente. Unipile presenta gli errori di quota dell'API Gmail come eventi webhook strutturati in modo che la tua applicazione possa rispondere in modo appropriato.
Collega il tuo primo account Gmail in pochi minuti. Nessun progetto GCP. Nessun addebito per Pub/Sub. Nessun rinnovo cron. Vedi la nostra Guida all'integrazione dell'API di Gmail e il Panoramica provider API email per esplorare tutti i provider supportati.
Gmail API Push Notifications - Domande frequenti
Risposte alle domande più comuni sull'API Gmail, notifiche push, configurazione Pub/Sub, historyId, rinnovo di watch e alternative di sincronizzazione email in tempo reale.
Notifiche push API di Gmail Google Cloud Pub/Sub per fornire eventi di modifica della casella di posta in tempo reale al tuo webhook HTTPS. Registri un endpoint di monitoraggio tramite utenti.guarda, che collega una casella di posta Gmail a un argomento Pub/Sub di tua proprietà. Quando si verifica una modifica - nuovo messaggio, modifica etichetta - Gmail pubblica una notifica a quell'argomento, che la inoltra al tuo webhook push. Il tuo webhook quindi chiama Elenco cronologia utenti con uno memorizzato idStoria cursore per recuperare il delta effettivo del messaggio. La notifica Pub/Sub contiene solo l'email dell'utente e un nuovo historyId, non il contenuto del messaggio.
utenti.guarda registra un abbonamento di notifica push per una casella di posta Gmail e restituisce un historyId di base. È il punto di ingresso che collega Gmail al tuo argomento Pub/Sub. Elenco cronologia utenti è l'endpoint di riconciliazione che chiami dopo aver ricevuto una notifica push di Gmail per ottenere le modifiche effettive (aggiunte, eliminazioni di messaggi, modifiche alle etichette) che si sono verificate dopo il tuo cursore historyId memorizzato. Watch dice a Gmail dove inviare gli avvisi. History ti dice cosa è cambiato effettivamente.
Gli endpoint di monitoraggio dell'API di Gmail scadono dopo 7 giorni. Le migliori pratiche prevedono l'esecuzione di un lavoro cron giornaliero anziché ogni 6 o 7 giorni, quindi si dispone di un buffer di più giorni contro i guasti transitori. Il rinnovo del certificato è idempotente: un nuovo utenti.guarda chiama semplicemente reimposta il timer e restituisce una nuova historyId baseline. La scadenza avviene in silenzio - non c'è alcuna notifica di avviso, quindi un cron fallito significa eventi persi senza errori da nessuna delle due parti.
La causa più comune è un concessione IAM mancante. Gmail utilizza l'account di servizio gmail-api-push@system.gserviceaccount.com per pubblicare sul tuo argomento Pub/Sub. Senza il Pub/Sub Publisher ruolo sul tuo argomento per questo account, utenti.guarda riesce ma non vengono mai consegnate notifiche. Altre cause: il tipo di sottoscrizione è "Pull" invece di "Push", certificato TLS non valido sul tuo endpoint webhook, o il tuo endpoint restituisce risposte non 2xx causando l'interruzione della consegna da parte di Pub/Sub.
Il idStoria è un numero intero monotonicamente crescente che Gmail assegna a ogni evento di modifica della casella di posta. Funziona come un cursore di sincronizzazione incrementale. Quando ti registri a utenti.guarda, Gmail restituisce un historyId di base che rappresenta lo stato corrente. Le successive notifiche push di Gmail includono un nuovo historyId. Passi il tuo historyId memorizzato (precedente) come startHistoryId a Elenco cronologia utenti per ottenere tutte le modifiche tra i due punti. Devi memorizzare l'ultimo historyId per utente autenticato nel tuo database. Gli historyId più vecchi di 7 giorni restituiscono un errore 404.
Non direttamente tramite l'API di Gmail: Pub/Sub è il canale di distribuzione richiesto per le notifiche push di Gmail. Tuttavia, è possibile saltare completamente l'infrastruttura GCP utilizzando un'API email unificata come Unipile, che funge da intermediario tecnico indipendente per conto di ciascun utente autenticato, astrae il livello Pub/Sub e fornisce notifiche push di Gmail al tuo webhook con un payload normalizzato. Nessun progetto GCP, nessuna concessione IAM, nessun cron di rinnovo watch richiesto.
Esegui lavoro cron giornaliero che chiama utenti.guarda per tutti gli utenti attivi e autenticati. Memorizzare l'historyId restituito come nuova base e aggiornare il timestamp di scadenza memorizzato. Gestire gli errori per utente senza interrompere il batch: un 401 significa che il token di aggiornamento OAuth è stato revocato (l'utente deve riautorizzare), un 404 significa che l'attività è già scaduta. Non aspettare mai la scadenza di 7 giorni per il rinnovo - tratta l'esecuzione giornaliera come manutenzione, non come una correzione reattiva.
Le notifiche push dell'API Gmail sono limitate a circa 1 evento al secondo per utente autenticato. Gli aumenti sopra questo vengono accumulati o ritardati, non scartati. Il Elenco cronologia utenti la chiamata costa 5 unità di quota e utenti.guarda costa 100 unità per chiamata. La quota giornaliera predefinita dell'API Gmail è di 1 milione di unità per progetto. Per una ripartizione completa dei limiti per metodo e delle procedure per aumentare le quote, consulta la nostra Limiti di frequenza API Gmail guida.
Hai bisogno di aiuto per configurare le notifiche push dell'API Gmail per la tua app? Il nostro team può guidarti.
IT 
EN 
FR 
ES 
DE 
BR 
NL 
PL 
TR