Crie já

Como Ler E-mails via API: Um Guia para Desenvolvedores de Acesso à Caixa de Entrada (2026)

Índice
Navegar por seções
Guia do Desenvolvedor 2026

Como Ler E-mails Via API: Um Guia para Desenvolvedores Acesso à Caixa de Entrada

Escopo: Este guia cobre APIs de sincronização para leitura de caixas de entrada existentes dos usuários - Gmail API, Microsoft Graph, IMAP e camadas unificadas como Unipile. Isso é distinto de serviços transacionais (SendGrid, Mailgun) que enviam e-mails de saída do seu domínio.

Construa produtos que leiam e-mails de usuários programaticamente. A partir de um único GET /api/v1/emails chamadas para webhooks em tempo real, este guia abrange todas as abordagens com código funcional em Node.js, Python e cURL.

Iniciar teste grátis Guia da API de e-mail
read_inbox.js
// Ler e-mails com uma única chamada de API unificada const response = await fetch( 'https://api3.unipile.com:PORT/api/v1/emails', { cabeçalhos: { 'X-API-KEY': process.env.UNIPILE_API_KEY, 'id_da_conta': accountId } } ); const { emails } = await resposta.json(); // Mesma estrutura JSON para Gmail, Outlook e IMAP emails.paraCada(email => { console.log(assunto do email, remetente do email); });
200 OK - 47 emails retornados (Gmail + Outlook + IMAP)
Funciona com: Gmail Perspectivas IMAP Gmail, Outlook e IMAP
Definição

O que é uma API de Leitura de E-mail?

Uma API de leitura de e-mail é uma interface HTTP que permite que seu aplicativo acesse, recupere e processe e-mails da caixa de entrada existente de um usuário, sem armazenar senhas ou criar integrações específicas do provedor. É a base de qualquer produto que necessite de visibilidade da caixa de entrada: sincronização de CRM, copilotos de e-mail com IA, automação de suporte ou arquivamento de conformidade.

Definição rápida

A ler email API expõe endpoints para autenticar contra a caixa de correio de um usuário (via OAuth 2.0 ou credenciais IMAP), listar mensagens da caixa de entrada, buscar corpos de e-mail completos com anexos e assinar eventos de entrega em tempo real. Ele opera na conta Gmail, Outlook ou IMAP existente do usuário - não um domínio que você controla. Isso o diferencia de APIs de e-mail transacional (SendGrid, Mailgun, Resend), que enviam e-mails de saída em nome do seu aplicativo.

Este guia cobre
APIs de Sincronização / Leitura de E-mail

Conecte-se às caixas de entrada existentes dos usuários. Leia, sincronize e reaja a e-mails em tempo real. Autenticação via OAuth 2.0 ou IMAP. O usuário concede acesso à sua própria caixa de correio.

Exemplos: API do Gmail, Microsoft Graph, IMAP, Unipile
Não este guia
APIs de E-mail Transacional

Envie e-mails de saída de um domínio que você controla. Usado para recibos, notificações, redefinições de senha. Sem acesso à caixa de entrada.

Exemplos: SendGrid, Mailgun, Resend, Postmark
Casos de uso

Por que ler e-mails programaticamente é importante

A capacidade de ler e-mails de usuários via API desbloqueia uma categoria de produtos que eram simplesmente impossíveis apenas com SMTP. Aqui estão os quatro principais casos de uso impulsionando a adoção em 2026.

Sincronização de CRM e Engajamento de Vendas

Ferramentas de vendas precisam ver todas as conversas de e-mail entre um representante e um cliente potencial - automaticamente, sem registro manual. Uma API de leitura de e-mail puxa conversas diretamente da caixa de entrada do representante e as sincroniza com seu CRM em tempo real.

Registrar automaticamente trocas de e-mail em registros de contato
Extrair sinais relevantes sobre negócios de linhas de assunto de e-mail
Detectar intenção de resposta e atualizar estágio do pipeline

Agentes de IA e Copilotos de E-mail

Modelos de linguagem grandes precisam de contexto. Ao alimentar seu agente de IA com um fluxo em tempo real de e-mails recebidos, você pode criar copilotos que redigem respostas, resumem conversas, extraem itens de ação e priorizam conversas automaticamente.

Transmita novos e-mails para um pipeline de processamento de LLM
Gerar rascunhos de respostas sensíveis ao contexto
Extrair tarefas, datas e compromissos de conversas

Automação de Suporte ao Cliente

As equipes de suporte recebem milhares de e-mails por dia. Uma API de leitura de e-mails permite que sua plataforma classifique solicitações recebidas, as direcione para a fila correta e acione respostas automatizadas — tudo antes que um humano sequer abra um ticket.

Classificar emails de suporte por tópico e urgência
Roteamento para filas de agentes com base no conteúdo do e-mail
Acionar respostas automáticas para padrões de solicitação comuns

Conformidade, Arquivamento e eDiscovery

Indústrias regulamentadas devem reter e indexar todos os e-mails. Uma API de e-mail para leitura fornece o acesso programático necessário para arquivar caixas de entrada continuamente, sinalizar violações de políticas e produzir registros de e-mail sob demanda para revisão legal.

Arquivamento contínuo da caixa de entrada para conformidade com GDPR / FINRA
Detecção de violação de políticas em caixas de correio de funcionários
eDiscovery de exportação sob demanda para retenção legal
Análise Profunda do Fornecedor

APIs Nativas para Lese de E-mails: Gmail, Outlook e IMAP

Cada provedor de e-mail principal expõe sua própria API de leitura com diferentes endpoints, modelos de autenticação e capacidades. Veja como cada um se apresenta na prática.

API do Gmail

OAuth 2.0

A API do Gmail é uma API REST construída sobre a infraestrutura do Google. Ela usa usuários.mensagens.listar para paginar uma caixa de correio e usuários.mensagens.obter para buscar uma mensagem completa. Ele suporta notificações push via Google Pub/Sub, tornando o monitoramento da caixa de entrada em tempo real viável sem polling. Limite de taxa: 250 unidades de cota por usuário por segundo.

gmail_leitura.sh
# Listar mensagens da caixa de entrada (API do Gmail) enrolar -X GET \ "https://gmail.googleapis.com/gmail/v1/users/me/messages?labelIds=INBOX&maxResults=20" \ -H "Autorização: Bearer CÓDIGO_DE_ACESSO" # Recuperar um único e-mail com o corpo completo enrolar -X GET \ "https://gmail.googleapis.com/gmail/v1/users/me/messages/MESSAGE_ID?format=full" \ -H "Autorização: Bearer CÓDIGO_DE_ACESSO"
Observação: O Gmail retorna mensagens como partes MIME codificadas em base64. Você deve decodificar cada parte e analisar os limites multipart por conta própria para extrair o corpo em texto puro, o corpo em HTML e os anexos.

Microsoft Graph (Outlook e Microsoft 365)

OAuth 2.0

O Microsoft Graph é a API unificada para todos os serviços do Microsoft 365, incluindo contas pessoais do Outlook, Exchange Online e caixas de correio comerciais do Microsoft 365. A /eu/mensagens endpoint retorna mensagens com conteúdo completo do corpo em uma única solicitação. A paginação usa $skip e $superior Parâmetros OData. Veja o completo Guia de integração de email do Microsoft Graph para obter detalhes.

graph_read.sh
# Listar mensagens da caixa de entrada (Microsoft Graph) enrolar -X GET \ ""https://graph.microsoft.com/v1.0/me/messages?\$top=20&\$filter=parentFolderId eq 'inbox'"' \ -H "Autorização: Bearer CÓDIGO_DE_ACESSO" \ -H "Content-Type: application/json" # Recuperar uma única mensagem com corpo enrolar -X GET \ ""https://graph.microsoft.com/v1.0/me/messages/MESSAGE_ID?\$select=subject,body,from,receivedDateTime"" \ -H "Autorização: Bearer CÓDIGO_DE_ACESSO"
Observação: O Microsoft Graph limita em 10.000 requisições por 10 minutos por aplicativo por locatário. O conteúdo do corpo é retornado como HTML ou texto dependendo do $selecionar e Aceitar cabeçalhos.

IMAP

Protocolo Universal

IMAP (Internet Message Access Protocol) é o protocolo universal de email suportado por praticamente todos os servidores de email. Não é uma API REST, mas uma conexão TCP stateful sobre a porta 993 (TLS). Você emite comandos como BUSCAR, PESQUISAe IDLE na conexão. Para um mergulho mais profundo, veja nosso Guia de integração da API IMAP.

imap_leia.py
import imaplib, e-mail #: Conectar-se e autenticar-se correio = imaplib.IMAP4_SSL('imap.example.com') correio.login('user@example.com', 'senha_do_aplicativo') correio.selecionar('Caixa de entrada') #: Pesquisar mensagens ocultas status, message_ids = correio.pesquisa(Nenhum, 'INVISÍVEL') para id_msg em ids_de_mensagem[0].dividir(): _, data = correio.fetch(id_msg, '(RFC822)') mensagem = email.mensagem_de_bytes(dado[0][1]) print(msg)'assunto'], msg['de'])
Observação: O IMAP requer a manutenção de conexões TCP de longa duração e o gerenciamento de pools de conexão por conta própria. A entrega em tempo real usa o IDLE comando, que mantém uma conexão aberta e espera por notificações do servidor. Isso não escala facilmente além de algumas centenas de contas simultâneas.
E o Yahoo e outros provedores?

Yahoo Mail, ProtonMail, Zoho e outros provedores suportam IMAP como um recurso de fallback universal, portanto, são cobertos pela abordagem IMAP acima. Alguns (como o Yahoo) também expõem APIs proprietárias limitadas, mas nenhuma corresponde às capacidades da API do Gmail ou do Microsoft Graph. Para a maioria dos produtos com vários provedores, o IMAP é o recurso de fallback universal para qualquer caixa de correio não coberta pelo OAuth do Gmail ou Outlook. A API de e-mail unificada lida com essa negociação automaticamente.

Engenharia da Realidade

A Complexidade Oculta de Ler E-mails em Larga Escala

Construir uma integração de API para ler e-mails contra um único provedor para uma demonstração leva uma tarde. Construir uma que funcione de forma confiável em todos os provedores em escala de produção é um desafio completamente diferente. Aqui está o que a engenharia realmente envolve.

01

Fluxo OAuth por provedor

Cada provedor tem sua própria implementação OAuth 2.0, requisitos de tela de consentimento, escopos e ciclo de vida do token. Dar suporte a Gmail e Outlook significa manter dois aplicativos OAuth separados, dois consoles de desenvolvedor, duas estratégias de atualização de token e dois conjuntos de requisitos de conformidade (Google CASA Nível 2, Microsoft Publisher Verification).

Gmail:Aplicativo Google Cloud Console, CASA Nível 2 para escopos sensíveis, tokens de acesso de 1 hora
Outlook:Registros de aplicativo do Azure AD, Verificação do Publicador, TTL de token configurável
IMAP:Senhas de aplicativo ou OAuth (o IMAP do Gmail usa o mesmo fluxo OAuth do Google)
02

Diferenças de Paginação

Cada provedor pagina de forma diferente. O Gmail usa tokens de página opacos. O Microsoft Graph usa OData $skip e próximoLink cursors. O IMAP usa intervalos de UID numéricos. Implementar uma abstração de paginação consistente em todos os três requer código de adaptador não trivial.

Gmail:pageToken cursor, max 500 resultados por página
Gráfico:URL @odata.nextLink, parâmetros $top/$skip
IMAP:UID FETCH intervalos, CONDSTORE para sincronização incremental
03

Análise MIME

Os e-mails chegam como documentos MIME brutos com limites multipart aninhados, codificação base64 ou quoted-printable, múltiplos conjuntos de caracteres e anexos inline. O Gmail retorna partes codificadas em base64url. O IMAP retorna RFC 822 brutos. Nenhum deles fornece um corpo de texto limpo sem analisar a árvore MIME completa.

RiscoCaracteres internacionais, emojis e texto RTL introduzem casos extremos de codificação que corrompem o conteúdo do corpo
AnexosDeve percorrer a árvore MIME para encontrar partes Content-Disposition: attachment
04

Limites de Taxa e Backoff

Gmail impõe 250 unidades de cota por usuário por segundo (listagens custam 5 unidades, buscas custam 5 unidades). O Microsoft Graph limita a 10.000 solicitações por 10 minutos por aplicativo por tenant. Ambos retornam erros 429 que exigem retrocesso exponencial com jitter (aleatoriedade). Com 1.000 contas vinculadas, o gerenciamento de limites de taxa se torna um problema de engenharia completo.

Gmail:250 unidades de cota/seg/usuário. Limite diário: 1 bilhão de unidades
Gráfico:10.000 requisições / 10 min / app / tenant. Cabeçalho Retry-After
IMAP:Específico do provedor, tipicamente de 10 a 20 conexões simultâneas por conta
05

Tempo Real: Webhooks vs Sondagem vs IDLE

Ser notificado quando um novo e-mail chega requer mecanismos completamente diferentes por provedor. O Gmail utiliza assinaturas push do Google Pub/Sub que devem ser renovadas a cada 7 dias. O Microsoft Graph utiliza assinaturas de notificação de alteração com um tempo de vida máximo de 4.230 minutos. O IMAP utiliza o comando IDLE, que mantém uma conexão TCP persistente aberta por conta.

Gmail:Pub/Sub push, expiração de 7 dias, requer ciclo de renovação
Gráfico:assinatura de notificações de alteração, expiração máxima de ~3 dias
IMAP:Comando IDLE, 1 conexão TCP persistente por conta
06

Inconsistências de threads entre provedores

O Gmail agrupa mensagens em threads nativamente. O Microsoft Graph possui um campo conversationId, mas os threads se comportam de maneira diferente do Gmail. O IMAP não tem threading nativo - você reconstrói threads combinando manualmente os cabeçalhos References e In-Reply-To. Construir uma visualização unificada de threads entre provedores requer uma lógica de normalização significativa.

Gmail:threadId nativo, messages.list?labelIds=INBOX retorna grupos de threads
Gráfico:conversationId, mas não equivalente a threads do Gmail
IMAP:É necessário analisar manualmente os cabeçalhos Message-ID / References
Arquitetura

Arquitetura da API de leitura de e-mail: 3 abordagens comparadas

Não existe uma única arquitetura "correta" para ler e-mails. A abordagem certa depende de quantos provedores você precisa suportar, sua capacidade de engenharia e seus requisitos de escala. Aqui está uma comparação honesta.

Abordagem Prós Cons Quando usar
APIs de provedor direto
API do Gmail, Microsoft Graph		 Nível gratuito, acesso completo a recursos, sem latência intermediária Configuração OAuth por provedor, análise MIME, gerenciamento separado de limites de taxa, sem normalização entre provedores Somente um provedor
IMAP auto-hospedado
imaplib, node-imap		 Protocolo universal, funciona com qualquer caixa de correio, sem necessidade de aplicativo OAuth Conexões TCP baseadas em estado, sem notificações push (polling ou IDLE), gerenciamento de pool de conexões, lento em escala Legado / apenas local
API unificada de leitura de e-mail
Unipile		 Um endpoint para todos os provedores, resposta JSON normalizada, OAuth gerenciado, webhooks unificados, lógica de retentativa integrada Custo adicional de chamada de API por conta vinculada, dependência externa Produtos Multi-provedores
APIs de provedor direto
API do Gmail, Microsoft Graph
Prós Nível gratuito, acesso completo a recursos, sem latência intermediária
Cons Configuração OAuth por provedor, análise MIME, gerenciamento separado de limites de taxa, sem normalização entre provedores
Quando usar Somente um provedor
IMAP auto-hospedado
imaplib, node-imap
Prós Protocolo universal, funciona com qualquer caixa de correio, sem necessidade de aplicativo OAuth
Cons Conexões TCP baseadas em estado, sem notificações push (polling ou IDLE), gerenciamento de pool de conexões, lento em escala
Quando usar Legado / apenas local
API unificada de leitura de e-mail
Unipile
Prós Um endpoint para todos os provedores, resposta JSON normalizada, OAuth gerenciado, webhooks unificados, lógica de retentativa integrada
Cons Custo adicional de chamada de API por conta vinculada, dependência externa
Quando usar Produtos Multi-provedores
Melhor para provedor único
API de Provedor Direto

Se todos os seus usuários usam o Gmail, integre-se diretamente à API do Gmail. Você terá paridade completa de recursos, sem custo adicional e acesso a funcionalidades específicas do Gmail, como marcadores, threads e push do Pub/Sub.

Melhor para sistemas legados
IMAP auto-hospedado

Servidores de e-mail locais (on-premises), implantações empresariais do Exchange sem acesso à API do Graph ou qualquer cenário onde o OAuth não esteja disponível. Use o IMAP como recurso de fallback, não como estratégia primária para novos produtos.

Melhor para produtos SaaS
API Unificada para Leitura de E-mails

Quando seus usuários têm caixas de correio do Gmail, Outlook e IMAP e você precisa de uma API de leitura de e-mail consistente em todas elas, uma camada unificada como a Unipile elimina completamente o problema da integração com múltiplos provedores.

Configuração em 5 Minutos

Lendo Emails com a API Unificada de Leitura de Email da Unipile

Unipile abstrai a API do Gmail, o Microsoft Graph e o IMAP sob uma única API de leitura de e-mail. Um fluxo OAuth, um endpoint, um formato JSON normalizado - independentemente de onde a caixa de correio do seu usuário esteja hospedada. Veja como ler sua primeira caixa de entrada em menos de 5 minutos.

1
Autenticar um usuário com o link de autenticação hospedado

Gere um URL de autenticação hospedado no seu painel Unipile. Envie este link para o seu usuário - ele completa o fluxo de consentimento OAuth para seu provedor (credenciais Gmail, Outlook ou IMAP) na página hospedada da Unipile. Nenhuma configuração de aplicativo OAuth, nenhuma configuração de URI de redirecionamento do seu lado. Veja o guia da API de e-mail unificada para o fluxo completo de autenticação.

auth_link.sh
# Gerar um link de autenticação hospedado para o seu usuário enrolar -X POST \ "https://api3.unipile.com:PORT/api/v1/hosted/accounts/link" \ -H "X-API-KEY: SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type":"EMAIL","name":"user@example.com","success_redirect_url":"https://yourapp.com/connected"}' Resposta #: { "url": "https://auth.unipile.com/..." } # Envie este URL ao seu usuário — ele concluirá o OAuth no provedor dele
2
Listar emails recebidos - GET /api/v1/emails

Assim que o usuário vincular a conta dele, chame o endpoint de e-mails com o account_id. A resposta é idêntica, independentemente de a caixa de correio subjacente ser Gmail, Outlook ou IMAP.

list_emails.sh
#: Listar e-mails da caixa de entrada (funciona com Gmail, Outlook e IMAP) enrolar -X GET \ "https://api3.unipile.com:PORT/api/v1/emails?account_id=ACCOUNT_ID&limit=50" \ -H "X-API-KEY: SUA_API_KEY" # Filtrar por pasta enrolar "...?account_id=ACCOUNT_ID&folder=INBOX&limit=50" -H "X-API-KEY: SUA_API_KEY" #: Filtrar apenas mensagens não lidas enrolar "...?account_id=ACCOUNT_ID&unread=true" -H "X-API-KEY: SUA_API_KEY"
200 OK - JSON normalizado, mesma estrutura para todos os provedores
3
Obter um único e-mail com corpo e anexos

Recupere um e-mail completo por ID. O Unipile retorna um objeto decodificado e normalizado com corpo em texto puro, corpo em HTML e metadados de anexos - sem necessidade de análise MIME do seu lado.

get_email.sh
#: Recuperar um único e-mail com o corpo completo + anexos enrolar -X GET \ "https://api3.unipile.com:PORT/api/v1/emails/EMAIL_ID" \ -H "X-API-KEY: SUA_API_KEY" Campos de resposta # (sempre normalizados): # { "id", "assunto", "data", "remetente", "destinatários", # "corpo", "corpo_simples", "anexos": [{ "id", "nome_do_arquivo", "tamanho" }] }
4
Receba novos e-mails em tempo real via webhooks

Registre um endpoint de webhook em seu painel Unipile. O Unipile abstrai o Gmail Pub/Sub, as notificações de alteração do Microsoft Graph e o IMAP IDLE em uma única email.received evento. Sem renovação de assinatura, sem pool de conexões ocioso para gerenciar.

webhook_handler.js
// Unipile chama seu endpoint quando um novo e-mail chega // Mesmo evento para usuários do Gmail, Outlook e IMAP aplicativo.postagem('/webhooks/email', (req, res) => { const { evento, id_conta, id_email } = req.body; se (evento === 'email.recebido') { // Busca detalhes completos do e-mail processarNovoEmail(account_id, email_id); } res.enviarStatus(200); });
Um evento de webhook substitui Gmail Pub/Sub + assinaturas do Graph + IMAP IDLE
Quer a referência completa de integração?

O Guia Completo da API de E-mail cobre em detalhes autenticação, todos os endpoints, paginação, download de anexos, segurança e conformidade.

Leia o Guia da API de E-mail
Exemplos de Código

Leitura de E-mails: Exemplos de Código por Idioma

Snippets prontos para produção para ler e-mails com a API unificada de leitura de e-mails do Unipile. Todos os exemplos leem de contas Gmail, Outlook e IMAP com o mesmo código.

Node.js / TypeScript
Python
Ir
readEmails.ts
import fetch from 'node-fetch'; const BASE = 'https://api3.unipile.com:PORT/api/v1'; const CHAVE_API = process.env.UNIPILE_API_KEY!; interface Email { identificador: string; Assunto: string; data: string; de_participante: { nome_exibido: string; identificador: string }; body: string; corpo_texto string; anexos: { id: string; nome do arquivo: string; tamanho: número }[]; } // Listar e-mails da caixa de entrada - funciona para Gmail, Outlook e IMAP async function listaremail(accountId: string, limite = 50) { const res = await fetch( `${BASE}/emails?account_id=${accountId}&limit;=${limit}&folder;=INBOX`, { cabeçalhos: { 'X-API-KEY': CHAVE_DA_API } } ); const dados = await res.json(); return dados.itens como Email[]; } // Busca um único e-mail com corpo completo + anexos async function obterEmail(emailId: string) { const res = await fetch(`${BASE}/emails/${emailId}`, { cabeçalhos: { 'X-API-KEY': CHAVE_DA_API } } ); return await res.json() como Email; } // Uso const e-mails = await listaremail('acc_01abc...'); emails.paraCada(e => console.log(e.assunto, e.remetente.identificador));
Guia completo da API de E-mail para JavaScript
read_emails.py
import os import solicitações BASE = "https://api3.unipile.com:PORT/api/v1" CABEÇALHOS = {"X-API-KEY": os.environ["UNIPILE_API_KEY"]} def listar_e-mails(account_id: str, limit: int = 50) -> list: "Listar e-mails da caixa de entrada - funciona para Gmail, Outlook e IMAP." resposta = pedidos.obter( f"{BASE}/emails", headers=HEADERS, parâmetros={ "id_da_conta"id_da_conta, "limite"limite, "pasta": "Caixa de entrada", }, ) resp.raise_for_status() return resp.json()["itens"] def obter_email(email_id: str) -> dict: "Buscar um único e-mail com corpo e anexos." resposta = pedidos.obter(f"{URL_BASE}/emails/{id_email}", headers=HEADERS) resp.raise_for_status() return resp.json() # Uso e-mails = listar_e-mails("acc_01abc...") para e-mail em e-mails: print(email"assunto"], e-mail["de_participante"]["identificador"]) #: Carregar o corpo completo do primeiro e-mail completo = obter_email(emails[0]["identificador"]) printcompleto["corpo_texto"])
Guia completo da API de e-mail para Python
read_emails.go
pacote principal import ( "encoding/json" "fmt" "net/http" "os" ) tipo Email estrutura { ID string `json:"id"` Assunto string `json:"assunto"` CorpoSimples string `json:"corpo_simples"` } tipo ListResponse estrutura { Itens []Email `json:"itens"` } função listaremail(accountID string) ([]Email, erro) { url := "https://api3.unipile.com:PORT/api/v1/emails?account_id=" + ID da conta req, _ := http.NovaSolicitaçāo("PEGAR", url, nulo) req.Header.Definir("X-API-KEY", os.Getenv("UNIPILE_API_KEY")) resp, erro := http.DefaultClient.Faça(req) se err != nulo { return nulo, erro } adiar resp.Corpo.Fechar() declarar resultado ListResponse json.Decodificador(resp.Corpo).Decodificar(&resultado) return result.Items, nulo } função principal() { e-mails, _ := listaremail("acc_01abc...") para _, e := intervalo e-mails { fmt.Imprimir(e.Assunto) } }
Em tempo real

Leitura de E-mail em Tempo Real: Webhooks vs Polling

Saber quando um novo e-mail chega é tão importante quanto poder lê-lo. Existem três mecanismos disponíveis, cada um com características operacionais muito diferentes em escala.

Evitar em escala

Pesquisa de opinião

Sua aplicação chama o endpoint de listar e-mails em um temporizador (a cada 30s, a cada 5 minutos). Simples de implementar, mas consome cota, introduz latência e não escala para além de um punhado de contas.

Simples - sem configuração de servidor
Cotas da API de queima proporcionais a contas x frequência
Enquete de 5 minutos = atraso de notificação de 5 minutos
Não escala além de ~100 contas ativas
Específico do provedor

Webhooks do Provedor Nativo

Notificações push do Gmail Pub/Sub e do Microsoft Graph enviam eventos para seu servidor imediatamente. Rápido e eficiente em termos de cota, mas cada um requer configuração separada, lógica de renovação separada e esquemas de eventos diferentes.

Entrega quase instantânea (segundos)
Eficiente em termos de cota - acionado apenas em novos e-mails
Gmail: Assinatura do Pub/Sub expira a cada 7 dias
Gráfico: assinatura máxima ~3 dias, deve renovar
IMAP IDLE: 1 conexão TCP por conta
Recomendado

Webhooks Unificados Unipile

Unipile abstrai todos os mecanismos de push dos provedores por trás de uma única email.received evento. Um endpoint recebe notificações para contas Gmail, Outlook e IMAP, com renovação automática de assinatura tratada internamente.

Uma URL de webhook para todos os provedores
Renovação automática de Pub/Sub e Grafos
IMAP IDLE gerenciado internamente por conta
Carga útil normalizada - os mesmos campos toda vez
Como a Unipile abstrai a entrega de e-mail em tempo real

Por baixo dos panos, a Unipile gerencia assinaturas Pub/Sub do Gmail, assinaturas de notificação de alterações do Microsoft Graph e conexões IMAP IDLE – por conta vinculada, renovadas automaticamente. Sua aplicação registra uma URL de webhook e recebe um evento normalizado, independentemente do provedor subjacente.

Gmail Pub/Sub
+
Assinaturas de Grafo
+
IMAP IDLE
->
evento.email.recebido
Segurança e conformidade

Segurança e Conformidade ao Ler E-mails de Usuários

O acesso a e-mails de usuários acarreta responsabilidades legais e de segurança significativas. Aqui estão as quatro áreas que você deve abordar antes de colocar em produção uma integração de API para leitura de e-mails.

Minimização de Escopo OAuth

Sempre solicite o escopo mínimo do OAuth necessário. Para ler e-mails, use escopos somente leitura - nunca solicite permissões de envio ou composição se seu aplicativo precisar apenas de acesso à caixa de entrada. O escopo somente leitura do Gmail é gmail.somente leitura. O equivalente no Microsoft Graph é Mail.Read. Solicitar escopos amplos aciona processos de revisão mais rigorosos do Google e da Microsoft e reduz a confiança do usuário na tela de consentimento.

Melhores Práticas de Armazenamento de Tokens

Tokens de acesso OAuth e tokens de atualização são credenciais. Armazene-os criptografado em repouso usando AES-256 ou equivalente, nunca em texto puro em seu banco de dados. Rotacione as chaves de criptografia em uma programação. Nunca registre tokens em logs de aplicativos. Implemente o revogamento de tokens quando um usuário desconectar sua conta - chame o endpoint de revogação do provedor, não simplesmente exclua o registro do banco de dados.

LGPD e Residência de Dados

Corpos de e-mail muitas vezes contêm dados pessoais cobertos pelo GDPR. Você deve documentar em sua política de privacidade exatamente quais dados de e-mail você coleta, retém, processa e por quanto tempo. Implemente um fluxo de exclusão de dados que remova o conteúdo do e-mail quando um usuário solicitar o apagamento. Se você armazena o conteúdo do e-mail em sua própria infraestrutura, considere os requisitos de residência de dados para clientes da UE.

Verificação do Google CASA e Microsoft Publisher

Aplicativos solicitando escopos sensíveis do Gmail (incluindo gmail.somente leitura) deve concluir o Google's CASA Nível 2 avaliação de segurança antes de ser permitido além do limite de teste de 100 usuários. A Microsoft exige a Verificação do Editor para aplicativos que solicitam determinados escopos do Graph. Ambos os processos levam semanas - planeje de acordo antes da sua data de lançamento. Usar o Unipile herda essas certificações da camada de plataforma.

Certificações de conformidade da Unipile

Unipile gerencia a certificação CASA Tier 2 do Gmail, Verificação do Microsoft Publisher, auditoria SOC 2 Tipo II e acordos de processamento de dados do GDPR em nível de plataforma. Produtos construídos sobre Unipile herdam essas certificações em vez de completá-las de forma independente.

SOC 2 Tipo II
Google CASA Nível 2
Em conformidade com o GDPR
Escopos de Somente Leitura do OAuth 2.0
Preços

Preços da API de Leitura de E-mail: Níveis Gratuitos e Modelos de Custo

Os níveis gratuitos para APIs de provedores nativos são generosos em baixa escala, mas os custos ocultos aparecem quando você precisa dar suporte a vários provedores, gerenciar a atualização de tokens em volume ou atingir os limites máximos de taxa. Aqui está uma análise honesta.

Fornecedor Plano gratuito Modelo de custo Limite de taxa Custos ocultos
API do Gmail Grátis com cotas Unidades de cota por solicitação. Sem cobrança por conta 250 unidades/seg/usuário, 1 bilhão de unidades/dia Revisão CASA Nível 2, análise MIME, lógica de renovação Pub/Sub
Microsoft Graph Grátis com limitação Incluído com o tenant do Microsoft 365. Sem taxa por chamada 10.000 req/10 min/app/tenant Processo de Verificação do Editor, renovação de assinatura, aplicativos OAuth por locatário
IMAP (auto-hospedado) Protocolo gratuito Custo zero de API. Custo de infraestrutura para pools de conexão Específico do provedor, ~10-20 conexões/conta Infraestrutura de servidor, gerenciamento de conexão ociosa, sem suporte a push
Unipile Teste gratuito de 7 dias Por conta vinculada por mês. Ver API de e-mail gratuita Gerenciado internamente, lógica de retentativa embutida Custo da chamada da API por conta - compensado pela eliminação da engenharia de OAuth/MIME
API do Gmail
Grátis com cotas
Modelo de custo Unidades de cota por solicitação. Sem cobrança por conta
Limite de taxa 250 unidades/seg/usuário, 1 bilhão de unidades/dia
Custos ocultos Revisão CASA Nível 2, análise MIME, lógica de renovação Pub/Sub
Microsoft Graph
Grátis com limitação
Modelo de custo Incluído com o tenant do Microsoft 365. Sem taxa por chamada
Limite de taxa 10.000 req/10 min/app/tenant
Custos ocultos Processo de Verificação do Editor, renovação de assinatura, aplicativos OAuth por locatário
IMAP (auto-hospedado)
Protocolo gratuito
Modelo de custo Custo zero de API. Custo de infraestrutura para pools de conexão
Limite de taxa Específico do provedor, ~10-20 conexões/conta
Custos ocultos Infraestrutura de servidor, gerenciamento de conexão ociosa, sem suporte a push
Unipile
Teste gratuito de 7 dias
Modelo de custo Por conta vinculada por mês. Ver API de e-mail gratuita
Limite de taxa Gerenciado internamente, lógica de retentativa embutida
Custos ocultos Custo da chamada da API por conta - compensado pela eliminação da engenharia de OAuth/MIME

Começando com uma API de e-mail de leitura gratuita? A API do Gmail e o Microsoft Graph oferecem acesso gratuito dentro dos limites de cota. O Unipile oferece um teste gratuito de 7 dias, sem necessidade de cartão de crédito, cobrindo contas vinculadas do Gmail, Outlook e IMAP.

Iniciar teste grátis
Erros Comuns

Armadilhas Comuns ao Construir uma Integração de E-mail para Leitura

Estes são os erros que consistentemente causam incidentes de produção para equipes que estão implementando pela primeira vez a integração de API de leitura de e-mail. Aprenda-os antes de cometê-los.

01
Esgotamento de cota no Gmail em escala

A cota de 250 unidades por segundo por usuário do Gmail parece generosa até que você tenha 500 contas e precise fazer uma sincronização inicial da caixa de entrada. Listar 500 mensagens custa 2.500 unidades; buscar cada mensagem completa custa mais 2.500. Sincronizações iniciais para caixas de correio grandes podem esgotar as cotas diárias em horas.

Correção: Implemente o backoff exponencial em respostas 429, priorize mensagens recentes para sincronização inicial e use requisições em lote quando disponíveis para reduzir a sobrecarga por chamada.
02
Falhas silenciosas de renovação de token

Tokens de atualização do OAuth expiram silenciosamente - O Google os revoga após 6 meses de inatividade, após uma alteração de senha ou quando um usuário revoga o acesso nas configurações da sua Conta Google. Se a sua lógica de atualização de token não detectar um erro 401 e apresentá-lo ao usuário, seu aplicativo simplesmente parará de ler e-mails sem nenhum erro visível.

Correção: Trate respostas 401 como eventos de desconexão de conta. Notifique o usuário e solicite reautenticação. Armazene um última_sincronização_em timestamp e alerta quando excede seu intervalo de sincronização esperado.
03
E-mails perdidos devido a filtros de pasta incorretos

As etiquetas do Gmail e as pastas IMAP não são conceitos equivalentes. As do Gmail INBOX A etiqueta não inclui mensagens que foram arquivadas (removidas da Caixa de Entrada, mas não excluídas). A pasta "Caixa de Entrada" do Microsoft Graph exclui a "Caixa de Entrada em Destaque" em comparação com outras divisões de painéis, a menos que você consulte ambas. As equipes frequentemente descobrem que estão faltando 20-40% de mensagens devido a suposições incorretas sobre as pastas.

Correção: Teste suas consultas de pasta com contas reais, incluindo mensagens arquivadas, filtradas e categorizadas. Para sincronização abrangente, considere consultar TUDO mensagens (não apenas Caixa de Entrada) e filtragem por data do seu lado.
04
Erros de codificação em e-mails internacionais

Corpos de e-mail chegam em uma ampla gama de codificações de caracteres: UTF-8, ISO-8859-1, Windows-1252, Shift-JIS. O Gmail retorna partes codificadas em base64url. O IMAP retorna partes codificadas em quoted-printable. Decodificar uma codificação como outra produz um corpo de texto corrompido que é invisível em seu ambiente de teste local (que provavelmente envia apenas e-mails ASCII).

Correção: Sempre decodifique partes MIME de acordo com seus Content-Transfer-Encoding e recodificar para UTF-8. Testar especificamente com conteúdo de e-mail com muitos caracteres japoneses, árabes e emojis.
05
Inconsistências de thread entre provedores

A construção de uma visualização unificada de threads entre contas Gmail, Outlook e IMAP requer a normalização de três modelos de threading completamente diferentes. O Gmail possui IDs de thread nativos. O Outlook possui IDs de conversa que se comportam de forma diferente. O IMAP não tem nenhum threading nativo - você reconstrói os threads a partir de ID da Mensagem, Referênciase Em-Resposta-A cabeçalhos, que nem sempre estão presentes ou corretos.

Correção: Uma API unificada para ler e-mails como a Unipile normaliza o encadeamento em um modelo consistente em todos os provedores, eliminando a necessidade de implementar lógica de reconstrução de thread específica do provedor.
PERGUNTAS FREQUENTES

Ler API de E-mail - Perguntas Frequentes

As perguntas mais comuns de desenvolvedores criando sua primeira integração de API de leitura de e-mail.

01
O que é uma API de leitura de e-mail?
A ler email API é uma interface HTTP que permite que seu aplicativo se autentique em uma caixa de correio existente do usuário (via credenciais OAuth 2.0 ou IMAP) e recupere mensagens de e-mail programaticamente. É diferente das APIs de e-mail transacional, como SendGrid ou Mailgun, que enviam e-mails de saída de um domínio que você controla. As APIs de leitura de e-mail operam na conta Gmail, Outlook ou IMAP do próprio usuário. Veja a Comparação completa de provedores de API de e-mail para ter um contexto sobre o ecossistema mais amplo.
02
Posso ler o e-mail de alguém com uma API?
Você só pode ler e-mails de contas cujos proprietários tenham explicitamente concedido acesso ao seu aplicativo via consentimento OAuth 2.0. O usuário deve autorizar seu aplicativo na tela de consentimento do Google ou da Microsoft. Você não pode acessar e-mails sem o consentimento do proprietário da conta - tentar fazer isso viola os termos de serviço do provedor e a legislação aplicável na maioria das jurisdições.
03
Como ler e-mails usando a API do Gmail?
Para ler e-mails com a API do Gmail: crie um projeto do Google Cloud, ative a API do Gmail, configure um cliente OAuth 2.0, solicite o gmail.somente leitura escopo, obter um token de acesso via consentimento OAuth, então chamar GET /gmail/v1/users/me/messages listar mensagens e GET /users/me/messages/{id}?format=full para buscar e-mails individuais. As mensagens são retornadas como partes MIME codificadas em base64url que você deve decodificar.
04
Qual é a diferença entre IMAP e a API do Gmail?
A API do Gmail é uma API REST moderna com OAuth 2.0, notificações push via Google Pub/Sub e respostas JSON. O IMAP é um protocolo TCP universal suportado por todos os provedores de e-mail, utilizando conexões stateful e comandos de texto. A API do Gmail é mais capaz para casos de uso exclusivos do Gmail (push em tempo real, acesso a threads, gerenciamento de rótulos). O IMAP fornece cobertura universal em todos os provedores, mas requer polling ou conexões IDLE e não possui uma interface REST nativa. Leia nosso Guia de integração da API IMAP para uma comparação mais aprofundada.
05
Existe uma API gratuita para ler e-mails?
Sim. A API do Gmail é gratuita dentro dos limites de cota do Google (250 unidades/segundo/usuário, 1 bilhão de unidades/dia). O Microsoft Graph para Outlook é gratuito com limites de limitação. O IMAP é um protocolo aberto e gratuito. Para suporte multi-provedor, o Unipile oferece um teste gratuito de 7 dias cobrindo contas vinculadas do Gmail, Outlook e IMAP. Veja nosso Guia da API de e-mail gratuita para uma comparação completa de níveis gratuitos e seus limites reais.
06
Como ler e-mails de múltiplos provedores com uma única API?
Use uma API unificada de leitura de e-mail como a Unipile. A Unipile expõe um único endpoint (GET /api/v1/emails) que retorna JSON normalizado para contas Gmail, Outlook e IMAP. Você autentica os usuários uma vez através de um link OAuth hospedado, e o Unipile cuida dos fluxos OAuth específicos do provedor, análise MIME e abstração de webhook em tempo real sob uma única interface consistente. Veja nosso Guia da API de e-mail para referência completa.
07
Posso ler anexos de e-mail via API?
Sim. A API do Gmail retorna metadados de anexos no payload da mensagem e fornece um endpoint separado para baixar os dados do anexo por ID. O Microsoft Graph retorna anexos via /mensagens/{id}/anexos. O IMAP requer a análise da árvore MIME para identificar partes de anexos. Com o Unipile, os metadados de anexos (nome do arquivo, tamanho, tipo MIME) são incluídos na resposta do e-mail e o conteúdo do anexo está disponível por meio de um endpoint dedicado - sem necessidade de análise MIME.
08
Como recebo notificações quando um novo e-mail chega?
Cada provedor tem um mecanismo diferente: o Gmail usa assinaturas push do Google Pub/Sub (expiram a cada 7 dias, exigem renovação). O Microsoft Graph usa assinaturas de notificação de alteração (expiram após ~3 dias). O IMAP usa o comando IDLE em uma conexão TCP persistente. Alternativamente, o Unipile abstrai todos os três em um único email.received evento webhook que dispara para contas Gmail, Outlook e IMAP com gerenciamento automático de assinatura tratado internamente.
09
Quais são os limites de taxa para leitura de e-mails no Gmail e Outlook?
API do Gmail: 250 unidades de cota por usuário por segundo. Listar mensagens custa 5 unidades, buscar uma mensagem completa custa 5 unidades. O limite diário é de 1 bilhão de unidades de cota. Microsoft Graph: 10.000 requisições a cada 10 minutos por aplicação por inquilino. Ambos retornam HTTP 429 quando limitados, com um Tentar Novamente Após header. Implemente backoff exponencial com jitter para confiabilidade em produção. Os limites do IMAP são específicos do provedor, tipicamente de 10 a 20 conexões simultâneas por conta.
10
Ler e-mails de usuários via API está em conformidade com o GDPR?
A leitura de e-mails de usuários via API pode estar em conformidade com o GDPR quando implementada corretamente. Os requisitos incluem: consentimento explícito do usuário via OAuth (a tela de consentimento cumpre o requisito de base legal), uma política de privacidade documentando quais dados de e-mail você coleta e retém, um mecanismo de exclusão de dados para solicitações de apagamento, e um acordo de processamento de dados com qualquer camada de API de terceiros que você utilize. Unipile é certificada SOC 2 Tipo II e está em conformidade com o GDPR, simplificando a documentação de conformidade para produtos construídos na plataforma.

Ainda tem dúvidas? Converse com um desenvolvedor que implementou integrações de API de leitura de e-mail em escala para Gmail, Outlook e IMAP.

Fale com um especialista
pt_BRBR
en_USEN fr_FRFR es_ESES de_DEDE it_ITIT nl_NLNL pl_PLPL tr_TRTR pt_BRBR