Guide

Adicione sincronização de e-mail sem IMAP

Criar sincronização de e-mail geralmente significa manter uma conexão IMAP IDLE persistente por caixa de correio, renovar OAuth e lidar com reconexões em escala. Este guia mostra o padrão que substitui tudo isso: webhooks para novas mensagens, leituras sob demanda para backfill e um protótipo completo pelo terminal.

Written by Caleb Geene Director, Site Reliability Engineering

Reviewed by Qasim Muhammad

Verified — CLI 3.1.17 · Gmail, Outlook, IMAP · last tested June 9, 2026

Por que é difícil criar infraestrutura de sincronização IMAP?

A sincronização IMAP é difícil porque entrega em tempo real exige uma conexão IDLE persistente aberta para cada caixa de correio. Segundo a RFC 2177, um cliente precisa reenviar IDLE pelo menos a cada 29 minutos ou o servidor pode derrubar a conexão. Com 10.000 usuários, isso significa 10.000 sockets de longa duração para manter vivos, reconectar e rebalancear entre processos.

Sobre esses sockets ficam a renovação de token OAuth por conta, autenticação XOAUTH2, particularidades de cada provider e tempestades de reconexão quando um nó reinicia e milhares de caixas renegociam ao mesmo tempo. São semanas de infraestrutura antes de você fazer parse de uma única mensagem — e é essa parte que gera alerta às 3 da manhã, não o recurso que você queria criar.

O que substitui a sincronização IMAP?

O substituto é um modelo push-plus-pull: um webhook entrega uma pequena notificação quando chega uma nova mensagem, e seu app lê a mensagem sob demanda apenas quando precisa do conteúdo. Você mantém zero conexões persistentes. O provider avisa quando algo mudou; você busca só aquilo, que é como os modelos de push do Gmail e do Microsoft Graph funcionam por baixo.

Isso inverte o custo. Em vez de pagar para manter milhares de sockets ociosos aquecidos, você paga um webhook barato por nova mensagem mais as leituras que de fato usa. Uma caixa que recebe 50 mensagens por dia custa 50 notificações, não 24 horas de conexão mantida.

Como faço um protótipo de sincronização de e-mail sem IMAP?

Você prototipa o padrão inteiro no terminal com dois comandos. Registre um webhook message.created para seu endpoint ser notificado a cada nova mensagem, depois rode o receiver embutido para ver os payloads chegarem. Sem framework de servidor, sem pool de sockets — você vê exatamente o formato de push que seu app vai processar.

# 1. Push new mail to your endpoint
nylas webhook create \
  --url https://your-app.example.com/inbound \
  --triggers message.created \
  --description "email sync"

# 2. Watch payloads locally while you build the handler
nylas webhook server --port 9000

Quando uma notificação chegar, busque o corpo da mensagem sob demanda. O comando nylas email read recebe o ID da mensagem enviado pelo webhook e retorna o conteúdo completo como JSON — a única busca que você faz, e só quando precisa dela.

# In your handler: fetch just the message the webhook pointed at
nylas email read "$MESSAGE_ID" --json | jq '{from: .from, subject: .subject}'

Como faço backfill de e-mails existentes?

Você faz backfill do histórico com busca sob demanda, não com uma sincronização completa. O comando nylas email search consulta a caixa diretamente, e o filtro de data --after limita a importação a uma janela recente para você não puxar anos de e-mail que não precisa. A maioria dos apps precisa apenas dos últimos 30–90 dias no onboarding.

# One-time backfill of the last 30 days at user onboarding
nylas email search "*" --after 2026-05-10 --json > backfill.json
jq 'length' backfill.json

Quando ainda preciso de IMAP?

Você ainda precisa de IMAP quando uma caixa não tem API moderna — um servidor Dovecot auto-hospedado, um host legado ou um provider de nicho que expõe apenas IMAP. Nesses casos não há webhook para assinar, então um client de polling ou IDLE é inevitável. O trade-off honesto: o modelo push precisa de um provider que ofereça suporte a notificações.

Mesmo assim, o CLI conecta contas IMAP genéricas pela mesma superfície de comandos, então você obtém o modelo de leitura unificado sem escrever o client IMAP por conta própria. A maioria dos times descobre que o caminho sem IMAP cobre Gmail, Outlook e os principais providers — a maior parte dos usuários reais — e reserva um fallback por polling para a cauda longa.

Próximos passos