LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Perspectivas
Google Agenda
Participe da comunidade do SlackAPI do Gmail Notificações Push: Guia Completo de Pub/Sub, Watch e History (2026)
Configurar notificações push da API do Gmail de ponta a ponta: criar um tópico do Pub/Sub, registrar um endpoint de observação, decodificar cargas úteis de webhook, reconciliar alterações com usuários.histórico.lista, automatize a renovação de watch e pule toda a configuração do GCP com uma alternativa unificada de webhook.
// 1. Registrar observação do Gmail via Unipile
const res = await fetch('https://api8.unipile.com:13815/api/v1'
+ ''/contas/{id}/seguir'', {
method: 'POST',
headers: {
'X-API-KEY': 'SUA_CHAVE_DE_API',
'Content-Type': 'application/json'
},
body: JSON.stringify({
webhook_url: 'https://app.you.com/webhooks/gmail'
})
});
// 2. Receber payload unificado do webhook
aplicativo.postagem('/webhooks/gmail', (req, res) => {
const { evento, id_conta, email } = req.body;
// evento: "novo_email" | históricoId abstraído
lidarNovoEmail(e-mail);
});As notificações push da API do Gmail são um recurso que permite que seu aplicativo receba atualizações em tempo real sobre novas mensagens e outras alterações na caixa de entrada do usuário. Em vez de seu aplicativo precisar fazer polling periodicamente para verificar alterações, o Gmail envia uma notificação para um endpoint que você especifica sempre que algo novo acontece.
Antes de implementar as notificações push da API do Gmail em produção, é útil entender exatamente o que são, como diferem da simples consulta e qual infraestrutura exigem.
As notificações push da API do Gmail são um mecanismo de entrega em tempo real que usa o Google Cloud Pub/Sub para enviar eventos de alteração da caixa de correio para um endpoint HTTPS controlado pelo desenvolvedor. Quando uma nova mensagem chega ou uma mensagem existente é modificada, o Gmail publica uma notificação contendo um codificado idHistórico para um tópico do Pub/Sub que você possui, que então encaminha esse evento para o seu webhook. Seu servidor chama usuários.histórico.lista para recuperar as alterações reais.
Notificações push da API do Gmail eliminam a necessidade de chamar repetidamente mensagens.listar em um cronograma. Os eventos são entregues em segundos após a alteração da caixa de correio, reduzindo a latência e o uso de cotas de API.
O canal de entrega é o Google Cloud Pub/Sub, e não um callback HTTP direto do Gmail. Isso adiciona durabilidade: se o seu endpoint estiver temporariamente indisponível, o Pub/Sub pode tentar novamente a entrega de acordo com o prazo de confirmação (ack deadline) da sua assinatura.
Um endpoint de watch da API do Gmail expira após 7 dias. Sua aplicação deve renová-lo proativamente com um cron job diário ou correr o risco de perder eventos silenciosamente. Este é um detalhe operacional crítico coberto na seção de Renovação.
As notificações push da API do Gmail entregam eventos em 1 a 10 segundos após a alteração. Nenhuma consulta constante significa menor consumo de cota na API do Gmail e menor tempo de reação para seu aplicativo. Ideal para qualquer caso de uso em tempo real no nível da caixa de entrada: sincronização de CRM, sistemas de tickets, automação de fluxo de trabalho.
Pesquisa de opinião mensagens.listar a cada 60 segundos é mais simples de configurar, mas introduz atrasos artificiais, desperdiça cota em respostas vazias e tem baixo escalonamento em um grande número de contas de usuários autenticados. Aceitável apenas para protótipos de baixo volume.
Arquitetura: watch + Pub/Sub + historyId em um único fluxo
As notificações push da API do Gmail envolvem quatro camadas distintas trabalhando em sequência. Compreender cada camada antes de escrever o código evita os erros de implementação mais comuns.
Você POSTA em https://gmail.googleapis.com/gmail/v1/users/me/watch com o nome do seu tópico do Pub/Sub e, opcionalmente, um filtro de rótulo. O Gmail retorna um idHistórico e um expiração Timestamp Unix. Armazene ambos. Este relógio expira em 7 dias.
Quando ocorre qualquer alteração na caixa de entrada monitorada (nova mensagem, alteração de rótulo, alternância de leitura/não leitura), o Gmail publica uma notificação JSON no seu tópico do Cloud Pub/Sub. A carga útil é um objeto codificado em base64 contendo o endereço de e-mail do usuário e um novo idHistórico.
Sua assinatura Pub/Sub encaminha a mensagem para um endpoint de push HTTPS registrado. Esta é a sua URL de webhook, que deve responder com HTTP 200-299 dentro do prazo de confirmação (padrão de 10 a 600 segundos). Uma resposta não 2xx aciona novas tentativas automáticas.
Decodificar os dados da mensagem Pub/Sub em base64. Extrair o novo idHistórico. Compare-o com o últimoIdHistórico armazenados em seu banco de dados para este usuário.
Chamar usuários.histórico.lista com idDoInícioDoHistórico configure para o seu valor armazenado. O Gmail retorna todas as alterações (novas mensagens, adições de marcadores, exclusões) entre os dois IDs. Atualize seu armazenado últimoIdHistórico para o novo valor. Nunca use o historyId da notificação do Pub/Sub como idDoInícioDoHistórico diretamente.
Agendar um trabalho cron diário para chamar usuários.assistir novamente para cada conta de usuário autenticada. A renovação de watch é idempotente: uma nova chamada substitui o tempo de expiração anterior. O retornado idHistórico torna-se sua nova linha de base.
Um inteiro monotonicamente crescente atribuído pelo Gmail a cada alteração de caixa de correio. É o seu cursor para sincronização incremental. Sempre armazene o último historyId por usuário em seu banco de dados.
O endpoint da API do Gmail que registra uma assinatura de notificação push para uma caixa de correio. Retorna uma linha de base de historyId e um timestamp de expiração Unix em milissegundos. Deve ser renovado em até 7 dias.
O endpoint de reconciliação. Dado um startHistoryId, ele retorna todas as adições, exclusões e alterações de rótulos de mensagens que ocorreram após esse ponto. É aqui que você obtém os dados reais das mensagens.
Pré-requisitos: projeto GCP, tópico Pub/Sub, concessão IAM
As notificações push da API do Gmail exigem três recursos no lado do GCP antes da sua primeira usuários.assistir chamar. A maioria das falhas de implementação remonta a uma permissão IAM ausente no tópico do Pub/Sub, a etapa que os desenvolvedores mais frequentemente pulam.
No Google Cloud Console, crie ou selecione um projeto existente. Navegue até APIs e Serviços > Biblioteca e habilitar o API do Gmail. Você também precisa do API do Cloud Pub/Sub habilitado no mesmo projeto. Certifique-se de que suas credenciais de cliente OAuth 2.0 incluam a https://www.googleapis.com/auth/gmail.readonly escopo (ou um escopo mais amplo se você precisar de acesso de escrita). Para aplicações multiusuário, veja nosso guia sobre Integração do Gmail com OAuth 2.0 e o Verificação do aplicativo OAuth do Google requisitos.
No Console do GCP, em Pub/Sub > Tópicos, clique Criar Tópico. Dê um nome como notificações do gmail. O nome completo do tópico será projects/SEU_PROJECT_ID/topics/gmail-notifications. Você passará essa string exata para usuários.assistir no NomeTópico campo.
Este é o passo que a maioria dos desenvolvedores ignora. O Gmail usa uma conta de serviço gerenciada pelo Google (gmail-api-push@system.gserviceaccount.com) para publicar notificações no seu tópico Pub/Sub. Sem conceder a esta conta o Publicador Pub/Sub papel no seu tópico, usuários.assistir vai funcionar, mas nenhuma notificação será entregue. No Console: Tópicos > selecione seu tópico > Permissões > Adicionar principal > insira gmail-api-push@system.gserviceaccount.com atribuir função Publicador Pub/Sub.
Sob seu tópico Pub/Sub, crie um Assinar push. Configure o endpoint de push para a URL do seu webhook HTTPS (deve usar um certificado TLS válido, certificados autoassinados são rejeitados). Opcionalmente, configure um cabeçalho de validação de token para que seu endpoint possa verificar se as solicitações vêm do Google. Anote o nome da assinatura, você pode precisar dele para monitorar métricas de entrega no Cloud Monitoring.
Limite de 100 usuários para aplicativos não verificados: Se a sua tela de consentimento OAuth estiver em status de "Teste", apenas 100 contas do Gmail poderão autorizar seu aplicativo. Este limite se aplica a tudo Escopos OAuth, incluindo o endpoint de observação. Para implantações em produção com mais de 100 usuários, você deve concluir o processo de verificação do Google. Consulte nosso guia completo sobre o Limite de 100 usuários e caminho de verificação.
Sem tópico no Pub/Sub. Sem concessão de IAM. Sem cron de renovação de watch de 7 dias. Crie notificações push do Gmail com uma URL de webhook.
Passo a passo: crie tópico, inscrição e usuários.watch
Com os pré-requisitos do GCP implementados, aqui está o código completo para registrar um endpoint de watch da API Gmail em Node.js e Python, usando a biblioteca cliente da API do Google.
const { google } = require('googleapis');
// Assume que o cliente OAuth2 já está autorizado com um token de acesso válido
// Veja: https://www.unipile.com/gmail-oauth-20-integration-complete-guide/
async function registrarGmailWatch(auth, userId = "eu) {
const gmail = Google.gmail({ versão: 'v1', auth });
const response = await gmail.users.relógio({
idDoUsuario,
corpo da requisição: {
// O nome completo do seu tópico Pub/Sub
nomeDoTópico: 'projects/YOUR_PROJECT_ID/topics/gmail-notifications',
// Opcional: filtrar apenas para rótulos específicos
labelIds: ['Caixa de entrada'],
labelFiltroComportamento: 'INCLUIR'
}
});
const { historyId, expiration } = response.data;
// Armazene isso por usuário em seu banco de dados
await banco de dados.inserir ou atualizar({
idDoUsuario,
lastHistoryId: historyId,
// expiração é um timestamp Unix em milissegundos
expiracaoDoWatch: new Data(parseInt(expiração))
});
console.log(`Observação registrada. historyId: ${historyId}, expira em: ${expiration}`);
return response.data;
}from googleapiclient.discovery import construir
from google.oauth2.credentials import Credenciais
def registrar_gmail_watch(credenciais: Credenciais, user_id: str = "eu) -> dict:
"Registrar notificações push da API do Gmail para um usuário autenticado."
serviço = construir('gmail', 'v1', credenciais=credenciais)
corpo = {
'nomeDoTópico': 'projects/YOUR_PROJECT_ID/topics/gmail-notifications',
'IDs dos rótulos': ['Caixa de entrada'],
'comportamentoDoFiltroDeEtiqueta': 'INCLUIR'
}
resultado = service.users().relógio(userId=user_id, body=corpo).executar()
#: Armazene por usuário no seu banco de dados
db_inserir_ou_atualizar(user_id=user_id,
last_history_id=resultado['idHistorico'],
expiracao_visualizacao=inteiro(resultado['expiração']) // 1000)
return resultadoTratando a carga útil do webhook de notificações push da API do Gmail
Quando o Gmail envia uma notificação push, seu endpoint HTTPS recebe uma mensagem push do Pub/Sub. Os dados reais da alteração do Gmail são codificados duas vezes: o envelope do Pub/Sub contém uma string JSON codificada em base64 que, por sua vez, contém o e-mail do usuário e o historyId.
aplicativo.postagem('/webhooks/gmail', async (req, res) => {
// Reconhecer imediatamente: Pub/Sub retenta em não 2xx
res.status(200).fim();
tentar {
const mensagem = req.body.mensagem;
se (!message?.data) retorne;
// Decodificar o campo Pub/Sub de base64
const decodificado =
Buffer.from(message.dados, 'base64').toString('utf-8');
const carga útil = JSON.analisar(decodificado);
// carga útil = { endereço de e-mail: "user@gmail.com", id de histórico: "12345" }
const { emailAddress, historyId } = payload;
// Reconciliação de fila (não bloquear o ack)
await fila.enfileirar({ emailAddress, historyId });
} catch (err) {
// Registrar, mas não relançar: ack já foi enviado
console.erro('Erro ao analisar webhook', erro);
}
});import base64, json
from garrafa import Flask, request, jsonify
aplicativo = Frasco(__name__)
@app.rota('/webhooks/gmail', métodos=['POST'])
def gmail_webhook():
# Confirme imediatamente
dados = request.obter_json(silencioso=Verdadeiro) ou {}
mensagem = dados.obter('mensagem', {})
se 'dados' em mensagem:
# Decodificar base64 e analisar JSON
cru = base64.b64decode(mensagem['dados'] + '==')
carga útil = json.cargascru
# { "emailAddress": "user@gmail.com", "historyId": "12345" }
email = carga Útil.obter('endereço de e-mail')
history_id = payload.obter('idHistorico')
#: Colocar na fila a reconciliação assíncrona
enqueue_reconcile(email, id_do_histórico)
return jsonify({}), 200Reconciliando alterações com users.history.list
A notificação do Pub/Sub apenas informa a você algo mudou. Não diz o quê. Você deve ligar usuários.histórico.lista com o seu armazenado últimoIdHistórico como o cursor para obter o delta real.
async function reconciliarHistórico(auth, endereçoDeEmail, novoIdDeHistórico) {
const gmail = Google.gmail({ versão: 'v1', auth });
// Recupera nosso lastHistoryId armazenado para este usuário
const usuário = await banco de dados.encontrarPorEmail(endereço de e-mail);
const startHistoryId = user.ultimoIdHistorico;
tentar {
const response = await gmail.users.history.list({
userId: "eu,
// Use o ID ARMAZENADO como cursor: NÃO o novo historyId da notificação
idDoInícioDoHistórico,
// Filtra apenas para adições de mensagens (opcional)
tiposDeHistórico: ['mensagemAdicionada']
});
const histories = response.data.history || [];
para (const registro de histórias) {
para (const added of (record.messagesAdded || [])) {
// added.message = { id, threadId, labelIds }
await processarNovaMensagem(auth, id.da.mensagem);
}
}
// Atualiza o cursor para o novo historyId da notificação
await banco de dados.atualizarUltimoIdDoHistorico(endereçoDeE-mail, novoIDDoHistórico);
} catch (err) {
se (err.code === 404) {
// O historyId está muito antigo (> 7 dias). Reinicialize a partir de messages.list
await reestabelecerDasMensagens(autenticação, endereço de e-mail);
} senão {
arremessar erro;
}
}
}O historyId na notificação do Pub/Sub é o atual estado. Seu idDoInícioDoHistórico tem que ser o anterior valor que você armazenou. Usar o notificationHistoryId diretamente como startHistoryId significa que você perderá todas as alterações entre o seu último ponto processado e o momento atual.
O Pub/Sub pode entregar a mesma notificação mais de uma vez. Sua lógica de reconciliação deve ser idempotente: processar o mesmo ID de mensagem duas vezes deve ser uma operação nula. Use uma restrição de unicidade em IDs de mensagem em seu banco de dados, ou verifique a existência antes de inserir.
Se você passar um startHistoryId com mais de 7 dias, a API retornará um 404. Nesse caso, volte para mensagens.listar para ressincronizar do zero, então chame usuários.assistir novamente para obter uma nova linha de base de historyId.
Se muitas alterações ocorreram entre seu último historyId e agora, a resposta de history.list pode ser paginada. Siga sempre próximoTokenPágina até esgotar antes de atualizar seu cursor armazenado.
Estratégia de renovação de watch: o problema da expiração de 7 dias
A API do Gmail watch expira silenciosamente após 7 dias. Não há renovação automática nem notificação de aviso. Se o seu cron falhar, novos e-mails chegarão, mas sua aplicação não receberá nada – sem erros em nenhum lado. Isso torna a renovação a parte operacionalmente mais crítica de qualquer implementação de notificações push do Gmail.
Renove diariamente, não a cada 7 dias. Execute o seu cron de renovação a cada 24 horas (não a cada 6 ou 7 dias). Assista à renovação é idempotente - chamando usuários.assistir reinicia simplesmente o cronômetro de 7 dias. Uma cadência diária lhe dá uma margem de segurança de 6 dias contra falhas transitórias.
// 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);
}
}
}
}A Unipile cuida da renovação de watch automaticamente em nome de cada usuário autenticado. Nenhum cron job é necessário.
Solução de problemas de notificações push da API do Gmail
Estas são as quatro classes de erros que respondem por quase todas as falhas nas notificações push do Gmail. A maioria tem uma única causa raiz, uma vez que você saiba o que procurar.
| Erro / Sintoma | Causa Raiz | Consertar | Gravidade |
|---|---|---|---|
| 403 em users.watch | Conta de serviço do Gmail gmail-api-push@system.gserviceaccount.com não foi concedida a função de Publicador do Pub/Sub no tópico. |
No Console do GCP: Pub/Sub > Tópicos > seu tópico > Permissões. Adicione a conta de serviço com a função de Publicador do Pub/Sub. | Bloqueador |
| O relógio funciona, mas nenhuma notificação é recebida | URL do endpoint de push da assinatura Pub/Sub não registrada, rejeitada pelo Google (TLS inválido) ou tipo de assinatura de push é "Pull" em vez de "Push". | Verifique se sua assinatura é do tipo "Push" com sua URL de webhook como endpoint. Certifique-se de que o certificado TLS seja válido (não autoassinado). O endpoint de teste retorna 200. | Bloqueador |
| 404 em history.list - historyId muito antigo | Seu armazenado últimoIdHistórico é mais antigo que 7 dias. O Gmail só retém o histórico por 7 dias. |
Recuar para mensagens.listar para resincronizar. Em seguida, chame usuários.assistir para uma nova linha de base de historyId. |
Recuperável |
| Token de validação do endpoint push rejeitado | O Google envia um cabeçalho X-Goog-Channel-Token. Se seu endpoint o validar e o token não corresponder, ele retornará um código não 2xx e o Pub/Sub tentará novamente indefinidamente. | Ou desabilite a validação de token durante a configuração inicial, ou configure o mesmo valor de token nas configurações de assinatura do GCP e na configuração do seu aplicativo. | Recuperável |
gmail-api-push@system.gserviceaccount.com não concedido Publisher do Pub/Sub.Cotas e limites de taxa para notificações push da API do Gmail
As notificações push da API do Gmail têm restrições de cota específicas que diferem dos buckets de cota padrão da API do Gmail. A restrição principal é a taxa de transferência de eventos por usuário.
Taxa máxima de notificações Pub/Sub por usuário autenticado. Rajadas podem exceder temporariamente esta taxa, mas são limitadas ao longo do tempo. Se uma caixa de correio receber mais de 1 alteração por segundo continuamente, as notificações serão agrupadas ou atrasadas, não descartadas.
Expiração máxima do relógio. Todos os relógios devem ser renovados antes deste prazo. O Gmail retém histórico.listar dados para a mesma janela de 7 dias - um historyId mais antigo que 7 dias retorna um 404.
Cota diária padrão da API do Gmail por projeto. Cada usuários.histórico.lista A chamada custa 5 unidades. usuários.assistir custa 100 unidades por chamada. Planeje seu volume de conciliação de acordo.
Para uma análise mais detalhada das cotas por método, limites por usuário e procedimentos de solicitação de aumento de cota, consulte nosso Guia de limites e cotas da API do Gmail.
Trade-offs: Pub/Sub vs IMAP IDLE vs polling vs webhook unificado
Escolher a estratégia certa de notificações push do Gmail depende das restrições da sua infraestrutura, das necessidades de cobertura do provedor e da sua tolerância operacional. Aqui está uma comparação direta das quatro abordagens.
| Abordagem | Latência | Complexidade da configuração | Multifornecedor | Sobrecarga operacional |
|---|---|---|---|---|
| Gmail Pub/Sub watch | 1-10s | Alto - GCP, IAM, cron | Apenas Gmail | renovação de 7 dias cron |
| IMAP IDLE | 1-30s | Médio - TCP persistente | Gmail + Servidores IMAP | Gerenciamento de keep-alive |
| Pesquisa de opinião | 30-300s de lag | Baixa | Qualquer provedor | Queima de cota alta |
| Webhook unificado (Unipile) | 1-10s | Baixo - 1 URL de webhook | Gmail + Outlook + IMAP | Nenhum - gerenciado |
A Alternativa Unificada de Webhook: Gmail + Outlook + IMAP com um único endpoint
Se você precisa de notificações push da API do Gmail, mais eventos em tempo real de caixas de correio Outlook e IMAP – com um formato de carga unificado e sem infraestrutura GCP – o Unipile's API do Gmail resume toda a camada Pub/Sub. Como um intermediário técnico independente, a Unipile atua em nome de cada usuário autenticado para entregar eventos de e-mail através de um único URL de webhook que sua aplicação já controla.
Sem tópicos do Pub/Sub para criar, sem concessões do IAM para configurar, sem projetos do GCP para manter. O registro e a renovação do Watch acontecem dentro da infraestrutura da Unipile, não da sua.
A expiração de 7 dias do watch é tratada em nome de cada conta vinculada. Você nunca precisa de um cron job de renovação. Se um token de atualização for revogado, o Unipile exibe um webhook de status da conta em vez de descartar eventos silenciosamente.
Você recebe um objeto de e-mail analisado e normalizado - não um historyId bruto. Não há necessidade de chamar usuários.histórico.lista ou gerenciar cursores por usuário. Unipile resolve o delta e entrega dados de mensagens estruturados.
O mesmo endpoint de webhook e o mesmo esquema de evento cobrem Gmail, Outlook (incluindo Microsoft 365 / Exchange Online) e IMAP. Nenhuma lógica de integração por provedor, nenhum webhook separado para assinaturas do Microsoft Graph em comparação com notificações de pub/sub do Gmail.
// 1. Vincular conta Gmail do usuário (OAuth em nome do usuário autenticado)
// Veja: https://developer.unipile.com/docs/getting-started
// 2. Configure seu webhook uma vez
const config = await fetch('https://api8.unipile.com:13815/api/v1/webhooks', {
method: 'POST',
cabeçalhos: {
'X-API-KEY': 'SUA_CHAVE_DE_API',
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: 'https://app.you.com/webhooks/email',
eventos: ['email.novo']
})
});
// 3. Lidar com carga útil unificada: mesma estrutura para Gmail, Outlook, IMAP
aplicativo.postagem('/webhooks/email', (req, res) => {
const { evento, conta_id, email } = req.body;
// evento: "email.novo"
// provedor.email: "gmail" | "outlook" | "imap"
// email.assunto, .de, .para, .corpo_html...
// Sem historyId. Sem base64. Sem cursor para gerenciar.
processarEmailEntrada(e-mail);
res.status(200).fim();
});Unipile não constrói um arquivo de e-mail paralelo ou armazena o conteúdo da mensagem de forma independente. O acesso é limitado à sessão de cada usuário autenticado. Unipile recupera dados de e-mail em nome de cada conta vinculada e os entrega ao seu endpoint de webhook em tempo real. Nenhum dado é retido além do que é necessário para entregar a carga útil do webhook.
Unipile é um intermediário técnico independente. Ele atua em nome de cada usuário autenticado que autorizou seu aplicativo via OAuth. A Unipile não é afiliada, endossada ou patrocinada pelo Google. Ela utiliza os mesmos endpoints da API do Gmail descritos neste guia, em uma base por usuário, sob a autorização OAuth própria de cada usuário. Credenciais nunca são compartilhadas entre contas. Todas as operações são uma decisão do lado do cliente delegada à infraestrutura da Unipile.
O Unipile transmite os limites de taxa e as restrições de cota da API do Gmail para sua aplicação por meio de sua própria camada de gerenciamento de cotas. As decisões sobre volume de eventos, frequência de sondagem e processamento de mensagens permanecem uma decisão do cliente. O Unipile expõe erros de cota da API do Gmail como eventos webhook estruturados para que sua aplicação possa responder adequadamente.
Conecte sua primeira conta do Gmail em minutos. Sem projeto GCP. Sem cobrança do Pub/Sub. Sem cron de renovação de watch. Veja nosso Guia de integração da API do Gmail e o Visão geral do provedor de API de e-mail para explorar todos os provedores suportados.
Notificações Push da API do Gmail - Perguntas Frequentes
Respostas para as perguntas mais comuns sobre notificações push da API do Gmail, configuração do Pub/Sub, historyId, renovação de watch e alternativas de sincronização de e-mail em tempo real.
Notificações push da API do Gmail Google Cloud Pub/Sub para entregar eventos de alteração de caixa de correio em tempo real para o seu webhook HTTPS. Você registra um endpoint de watch via usuários.assistir, que vincula uma caixa de correio do Gmail a um tópico do Pub/Sub que você possui. Quando ocorre uma alteração - nova mensagem, alteração de rótulo - o Gmail publica uma notificação nesse tópico, que a encaminha para o seu webhook de push. Seu webhook, em seguida, chama usuários.histórico.lista com um armazenado idHistórico cursor para obter o delta da mensagem real. A notificação Pub/Sub em si contém apenas o e-mail do usuário e um historyId novo - não o conteúdo da mensagem.
usuários.assistir registra uma assinatura de notificação push para uma caixa de correio do Gmail e retorna um historyId de linha de base. É o ponto de entrada que conecta o Gmail ao seu tópico do Pub/Sub. usuários.histórico.lista é o endpoint de reconciliação que você chama após receber uma notificação push do Gmail para obter as alterações reais (adições de mensagens, exclusões, alterações de rótulos) que ocorreram desde o seu cursor de historyId armazenado. Watch informa ao Gmail para onde enviar alertas. History informa o que realmente mudou.
Os endpoints de observação da API do Gmail expiram após 7 dias. A prática recomendada é executar uma tarefa cron diária em vez de a cada 6 ou 7 dias, para que você tenha um buffer de vários dias contra falhas transitórias. A renovação de watch é idempotente: uma nova usuários.assistir A chamada simplesmente reinicia o cronômetro e retorna um historyId de base novo. A expiração ocorre silenciosamente - não há notificação de aviso, então um cron que falha significa eventos perdidos sem erros de nenhum dos lados.
A causa mais comum é um permissão IAM ausente. O Gmail usa a conta de serviço gmail-api-push@system.gserviceaccount.com para publicar no seu tópico Pub/Sub. Sem o Publicador Pub/Sub função no seu tópico para esta conta, usuários.assistir conseguiu, mas nenhuma notificação é entregue. Outras causas: tipo de assinatura é "Pull" em vez de "Push", certificado TLS inválido no seu endpoint de webhook ou seu endpoint retorna respostas não 2xx, fazendo com que o Pub/Sub pare de entregar.
O idHistórico é um inteiro monotonicamente crescente que o Gmail atribui a cada evento de alteração de caixa de correio. Ele funciona como um cursor de sincronização incremental. Quando você registra um usuários.assistir, o Gmail retorna um historyId base representando o estado atual. Notificações push subsequentes do Gmail incluem um novo historyId. Você passa seu historyId armazenado (anterior) como idDoInícioDoHistórico para usuários.histórico.lista para obter todas as alterações entre os dois pontos. Você deve armazenar o último historyId por usuário autenticado em seu banco de dados. Os HistoryIds mais antigos que 7 dias retornam um erro 404.
Não diretamente através da API do Gmail - o Pub/Sub é o canal de entrega necessário para notificações push do Gmail. No entanto, você pode pular completamente a infraestrutura do GCP usando uma API de e-mail unificada como Unipile, que atua como um intermediário técnico independente em nome de cada usuário autenticado, abstrai a camada Pub/Sub e entrega notificações push do Gmail ao seu webhook com uma carga útil normalizada. Nenhum projeto GCP, nenhuma permissão IAM, nenhuma renovação de "watch" via cron é necessária.
Executar um tarefa cron diária aquilo chama usuários.assistir para todos os usuários autenticados ativos. Armazene o historyId retornado como a nova linha de base e atualize o timestamp de expiração armazenado. Lide com erros por usuário sem abortar o lote: um 401 significa que o token de atualização OAuth foi revogado (o usuário precisa reautorizar), um 404 significa que o watch já expirou. Nunca espere até a expiração de 7 dias para renovar - trate a execução diária como manutenção, não como uma correção reativa.
As notificações push da API do Gmail são limitadas a aproximadamente 1 evento por segundo por usuário autenticado. Explosões acima disso são agrupadas ou atrasadas, não descartadas. usuários.histórico.lista a chamada custa 5 unidades de cota e usuários.assistir custa 100 unidades por chamada. A cota diária padrão da API do Gmail é de 1 milhão de unidades por projeto. Para um detalhamento completo dos limites por método e dos procedimentos de aumento de cota, consulte nossa Guia de limites de taxa da API do Gmail.
Precisa de ajuda para configurar notificações push da API do Gmail para seu aplicativo? Nossa equipe pode te ajudar.
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR