LinkedIn
Instagram
Facebook
WhatsApp
Telegram
Google Agenda
Calendário do Outlook
Participe da comunidade do SlackComo 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.
// 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);
});
Gmail, Outlook e IMAP
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.
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.
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.
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.
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.
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.
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.
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.
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.0A 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. Observação: O Gmail requer OAuth 2.0 - as chaves de API não funcionam para acesso à caixa de correio. Veja Por que o Gmail rejeita chaves de API.
# 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"
Microsoft Graph (Outlook e Microsoft 365)
OAuth 2.0O 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.
# 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"$selecionar e Aceitar cabeçalhos.
IMAP
Protocolo UniversalIMAP (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.
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'])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.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.
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.
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).
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.
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.
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.
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.
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.
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 |
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.
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.
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.
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.
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.
# 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 deleAssim 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.
#: 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"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.
#: 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" }] }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.
// 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);
});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.
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.
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));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"])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)
}
}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.
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.
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.
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.
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.
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.
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.
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 |
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átisArmadilhas 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.
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.
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.
última_sincronização_em timestamp e alerta quando excede seu intervalo de sincronização esperado.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.
TUDO mensagens (não apenas Caixa de Entrada) e filtragem por data do seu lado.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).
Content-Transfer-Encoding e recodificar para UTF-8. Testar especificamente com conteúdo de e-mail com muitos caracteres japoneses, árabes e emojis.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.
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.
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.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./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.email.received evento webhook que dispara para contas Gmail, Outlook e IMAP com gerenciamento automático de assinatura tratado internamente.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.