Esperar um e-mail no código: polling sem webhook

Push e pull, e o que cada um custa

Existem só duas formas de o seu código descobrir que uma mensagem chegou. Ou o outro lado te avisa, ou você pergunta. Tudo o mais — uma biblioteca cliente com um waitFor nela, um SDK que “transmite” uma caixa de entrada, um helper de teste que bloqueia — é uma dessas duas coisas com a maquinaria escondida, e vale a pena saber qual delas você tem nas mãos antes de precisar depurá-la.

Quatro arranjos cobrem quase tudo o que existe por aí.

Um webhook

O serviço faz uma requisição HTTP para um endereço que você controla, cada vez que um e-mail chega. É a espera mais barata que existe — você não faz nada até haver algo a fazer — e o preço é um endereço na internet pública, um listener de pé no exato momento em que o e-mail chega, um segredo compartilhado para provar que a requisição veio deles, e uma resposta sua própria para o que acontece quando o seu listener não estava lá.

Um long poll

Você faz a requisição e o servidor a mantém aberta até que o e-mail chegue ou um timeout expire. Não exige nada de você além de uma conexão de saída, e custa ao servidor um worker por espera — motivo pelo qual todo serviço que oferece isso limita tanto a duração da espera quanto o número de esperas simultâneas.

Um polling simples

Você pergunta, repetidamente, e cada requisição é respondida na hora com o que houver ali. É o único arranjo que funciona a partir de um laptop atrás de um roteador, de um runner de CI sem rota de entrada, e de um agente rodando dentro do sandbox de outra pessoa — e é o assunto inteiro deste guia.

Um protocolo de caixa de entrada

O IMAP tem o IDLE, que é um long poll com outra roupagem: a conexão fica aberta e o servidor anuncia o e-mail novo por ela. É genuinamente parecido com push, e exige uma caixa de entrada com credenciais, um cliente capaz de manter um socket aberto e reconectar quando ele cai, e um servidor que respeita o comando — o que é uma quantidade enorme de maquinaria para um job que precisa de uma mensagem.

Colocadas lado a lado, a escolha acaba sendo menos sobre elegância e mais sobre o que cada uma exige da máquina em que o seu código está rodando.

O loop que todo mundo escreve primeiro

São quatro linhas, funciona no dia em que é escrito, e cada um dos seus problemas aparece depois e em outro lugar: em um pipeline às três da manhã, em um agente que está “pensando” há onze minutos, em uma caixa de entrada que responde 429 a um colega porque o seu loop está consumindo todo o orçamento.

import time
import requests

while True:
    r = requests.get("https://grabmail.io/api/v1/mailbox",
                     params={"address": "signup-42@grabmail.io"})
    if r.json()["messages"]:
        break
    time.sleep(1)

Cinco coisas estão erradas nele, e só a primeira é óbvia.

Ele nunca desiste

Não há prazo, então quando a mensagem realmente não vai chegar — o formulário rejeitou o endereço, a fila do remetente travou, alguém digitou o domínio errado — esse loop não falha. Ele trava. Um job que trava é peor do que um que falha, porque o log termina sem nunca dizer o motivo.

Ele conta tentativas e chama isso de segundos

Mesmo com um limite no número de voltas, trinta tentativas de “um segundo” nunca são trinta segundos: cada volta também custa uma requisição, e uma requisição que leva 400 ms transforma os seus trinta segundos em quarenta e dois. Acrescente uma retentativa e a aritmética deixa de ser aritmética.

Todo runner pergunta no mesmo tick

Inicie vinte jobs a partir do mesmo pipeline e eles vão fazer polling em sincronia, porque todos começaram com poucos milissegundos de diferença entre si e todos dormem o mesmo segundo inteiro. O pico é vinte vezes a média, e é o pico que é recusado.

Ele pega a mensagem mais nova, não a sua

A primeira entrada da lista é o que estiver no topo daquela caixa de entrada, o que em um endereço público pode ser o e-mail de outra pessoa, e em um endereço reutilizado é o da semana passada. Um loop que sai ao ver a primeira mensagem vai sair tranquilamente antes mesmo de a mensagem esperada ter chegado.

Ele trata toda resposta como sucesso

Ler a lista de mensagens a partir de um 429 ou de um 404 gera um erro três frames longe de qualquer coisa que o explique, e ler a partir de um 500 pode não gerar erro nenhum. O código de status é a primeira coisa a olhar, não a última.

Pare pelo relógio, não pela contagem

Tome o prazo uma única vez, antes da primeira requisição, a partir de um relógio monotônico — um que não pode voltar no tempo quando a máquina corrige o próprio horário — e compare com ele no início de cada volta. Tudo o mais no loop fica então livre para mudar sem alterar a duração da espera: você pode alargar o intervalo, repetir uma recusa, ou acrescentar um segundo filtro, e noventa segundos continuam sendo noventa segundos.

Quanto tempo é tempo suficiente é uma pergunta sobre o remetente, não sobre você. Um e-mail que uma máquina gera em resposta a um formulário costuma ser entregue em segundos, quase sempre menos de dez; uma fila com atraso acumulado, um destinatário que faz greylisting, ou um lote de hora em hora, são de uma ordem de grandeza diferente, e nenhum intervalo que você escolher faz o e-mail chegar mais rápido.

O prazo também é o lugar honesto para colocar a sua mensagem de erro. “Nada correspondendo a ‘Confirm your email’ chegou em signup-42@grabmail.io dentro de 90 s” nomeia o endereço, o filtro e o orçamento, que são três das quatro coisas necessárias para entender o que aconteceu. A quarta — o que de fato chegou — também vale a pena imprimir: uma lista dos assuntos que o loop viu e rejeitou transforma “isso é instável” em “o assunto mudou” em uma única leitura.

Com que frequência perguntar, e quando alargar o intervalo

O piso é o que o serviço permitir, e aqui é uma requisição por segundo, por endereço. Isso não é um desincentivo — fazer polling uma vez por segundo é o padrão pretendido, não há cota diária, nem cota mensal, nem crédito de rajada para gerenciar — mas é um piso, e um loop que pergunta duas vezes dentro do mesmo segundo recebe um 429 na segunda vez, em vez de uma resposta mais rápida.

Um intervalo fixo

Um segundo, sempre, até o prazo acabar. Perfeitamente adequado para uma espera que vai terminar em dez segundos, e o padrão certo para um único teste em um único runner. Sua única falha é continuar perguntando no mesmo ritmo bem depois de já estar óbvio que o e-mail não vai chegar.

Um intervalo que se alarga

Um segundo enquanto a mensagem provavelmente ainda está em trânsito, depois dobrando — dois, quatro, oito — com um teto. Isso custa um pouco de latência em uma mensagem que chega atrasada, e economiza a maior parte das requisições em uma espera que ia falhar de qualquer jeito. Coloque um teto: um intervalo que dobra sem teto passa a segunda metade de um prazo de dois minutos dormindo.

Jitter, somado e nunca subtraído

Espalhe as voltas com uma fração aleatória, para que vinte runners parem de perguntar no mesmo tick. A receita usual — um valor aleatório entre zero e o intervalo — está errada aqui, porque metade da sua faixa cai abaixo do piso de um segundo. Em vez disso, some a aleatoriedade por cima: o intervalo é um mínimo, e o jitter só pode atrasar uma volta, nunca antecipá-la.

Uma pausa que não é sua para escolher

Quando a resposta é um 429, o intervalo é o que o Retry-After disser, e a volta que foi recusada não contou como tentativa. Contá-la como uma faz com que um loop sendo limitado passe o prazo inteiro colecionando recusas sem nunca ter lido a caixa de entrada.

Quinze segundos a um segundo, depois dobrando até um teto de oito, com jitter por cima, encaixa quase toda espera deste guia em seis linhas:

def delay(attempt: int) -> float:
    # One second while the message is probably still in flight, then
    # wider. Never below a second: the list endpoint allows one call
    # per second, per address, so jitter is added and never taken off.
    step = 1.0 if attempt < 15 else min(8.0, 2.0 ** (attempt - 14))
    return step + random.uniform(0.0, step / 2)

O expoente é deslocado para que o alargamento comece depois do trecho fixo, e não a partir da primeira volta. Sem esse deslocamento, o intervalo já teria chegado a oito segundos no momento em que um e-mail de cadastro lento chegasse, e uma espera que deveria durar doze segundos passaria a durar vinte.

Nada disso vale para a primeira requisição. Pergunte imediatamente, antes de dormir: uma mensagem que já estava na caixa de entrada quando o loop começou — o caso normal para qualquer coisa disparada antes de a espera começar — não deveria custar nem um segundo de latência para ser percebida.

Lendo uma recusa

Toda resposta do endpoint de listagem é JSON, e as que não são uma caixa de entrada compartilham um formato: um slug error, que é estável e é o que deve orientar a decisão, e uma message, que é texto livre e pode ser reformulada a qualquer momento. Uma recusa por excesso de velocidade também carrega um header:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json; charset=utf-8

{"error":"rate_limited","message":"one request per second, per address"}

O Retry-After vem em segundos inteiros, e é o número real — tirado de quanto ainda resta do orçamento daquele endereço, não de uma constante na documentação. Dormir exatamente esse tempo é ao mesmo tempo a coisa mais educada e a mais rápida a fazer: uma pausa mais curta é recusada de novo, uma mais longa é tempo desperdiçado. Aqui está tudo que um loop de polling pode encontrar, e o que cada resposta está realmente pedindo dele.

Duas dessas sete significam pare, e são as duas que vale a pena destacar. Um loop que trata unknown_domain como “ainda não” gasta noventa segundos inteiros para provar algo que o serviço já tinha dito nos primeiros quarenta milissegundos.

Qual mensagem é sua

Uma caixa de entrada não é uma fila, e a coisa mais nova nela não é necessariamente a que você está esperando. Em um domínio público, qualquer um que adivinhar o endereço pode enviar para ele; em uma suíte de testes o mesmo endereço é frequentemente reutilizado entre execuções; e um único cadastro costuma enviar duas mensagens — uma de boas-vindas e uma de confirmação — das quais só uma carrega o código. A solução é um watermark, e ele precisa ser registrado antes da coisa que causa o e-mail.

1. Antes de enviar o formulário, liste a caixa de entrada com limit=1 e guarde o id da mensagem mais nova, ou nada, se estiver vazia. Esse id é o watermark.
2. Faça a coisa — envie o formulário, chame o endpoint, clique no botão.
3. Consulte a lista. As mensagens voltam da mais nova para a mais antiga, então desça a partir do topo e pare no instante em que encontrar o watermark: tudo dali para baixo é mais antigo que a sua ação e pode ser ignorado sem ser lido.
4. Filtre o que está acima dele pelo remetente, pelo assunto, ou por ambos. Uma substring geralmente basta, e deve ser a parte que não vai ser localizada — um teste que procura por “Confirm your email” falha no dia em que a conta usada no teste é trocada para outro idioma.
5. Só então, e não antes, abra a mensagem. A listagem carrega um preview curto, não o corpo, e o código que você procura está frequentemente depois do fim dele. Mais uma requisição traz a mensagem completa, e ela é cobrada contra um orçamento separado e muito maior do que o da listagem.

Em um shell, essas duas leituras se parecem com isto — primeiro o watermark, depois a consulta:

curl -sG https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=signup-42@grabmail.io" --data-urlencode "limit=1"
curl -sG https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=signup-42@grabmail.io" --data-urlencode "limit=25"

As duas requisições nomeiam o endereço completo, porque aqui o endereço é a caixa de entrada: não há sessão, não há cursor guardado em seu nome, e nada em uma chamada que a próxima se lembre. É também por isso que é seguro observar um endereço a partir de dois lugares ao mesmo tempo — ler não consome nada, então dois loops na mesma caixa de entrada veem cada mensagem, e nenhum consegue tirar uma mensagem de debaixo do outro.

Agindo exatamente uma vez

Uma consulta que é repetida pode ver a mesma mensagem duas vezes, e isso não é raro: o servidor responde, a conexão cai antes de o corpo chegar até você, o seu cliente HTTP tenta de novo, e a segunda resposta contém a mensagem que a primeira já trazia. Se o que você faz com uma mensagem é clicar em um link, confirmar um pagamento ou postar em um canal, fazer isso duas vezes é um bug com consequências fora do seu processo.

Guarde os ids que você já processou

Um conjunto de ids em memória basta para uma espera que nasce e morre dentro de uma única função. Para qualquer coisa que precise sobreviver a um reinício — uma caixa de entrada esvaziada por um job agendado, um agente trabalhando em um backlog — isso precisa ser anotado em algum lugar que sobreviva junto.

Apagar é idempotente

Apagar uma mensagem responde 200 tanto na segunda vez quanto na primeira, então uma exclusão repetida nunca parece uma falha e nunca precisa de um caso especial. Apague depois de ter agido, e não antes: uma queda entre as duas etapas custa então uma releitura, que é recuperável, em vez da mensagem, que não é.

O id aqui não é o Message-ID do remetente

O id da API é nosso: é restrito a uma caixa de entrada, e deixa de existir quando a mensagem expira. O header Message-ID é do remetente, viaja com a mensagem, e é o que você quer usar se estiver correspondendo o mesmo e-mail entre dois sistemas — o guia sobre headers mostra onde encontrá-lo.

Nada disso é necessário para um teste que espera por um código e depois descarta a caixa de entrada. Tudo isso passa a ser necessário no momento em que um loop passa a rodar sem supervisão, porque a falha que ele evita não parece uma falha: parece o trabalho sendo feito, duas vezes, corretamente.

Quando a espera é responsabilidade do servidor

Existe um único lugar aqui onde você não escreve o loop, e ele existe para quem não pode se dar ao luxo de escrever um. Um agente de IA paga por cada turno que gasta verificando, então uma ferramenta que responde “ainda não” nove vezes são nove turnos de nada. O wait_for_message do servidor MCP mantém a requisição aberta, faz o polling do nosso lado, e responde uma única vez — com a mensagem, ou com uma declaração simples de que esperou e nada chegou.

$ curl -sX POST https://grabmail.io/mcp -H "Content-Type: application/json" -d '{
  "jsonrpc":"2.0","id":1,"method":"tools/call",
  "params":{"name":"wait_for_message","arguments":{
    "address":"signup-42@grabmail.io","subject_contains":"code",
    "timeout_seconds":25}}}'

Quatro coisas sobre isso vale a pena saber antes de construir em cima dele.

Ele espera no máximo 25 segundos

timeout_seconds pode pedir menos, nunca mais. O teto não é arbitrário: cada espera ocupa um worker que não faz nada além de dormir, e uma requisição mantida aberta por minutos é uma requisição que morre no timeout de algum proxy bem antes de retornar.

Ele filtra na entrada

from_contains, subject_contains e since_id são as mesmas três decisões da seção anterior, só que tomadas no servidor. since_id é o watermark, e ele importa mais aqui do que em qualquer outro lugar: sem ele a chamada retorna imediatamente com o que já estiver na caixa de entrada.

Um timeout é uma resposta, não um erro

Quando nada chega, ele retorna timed_out definido, junto com quanto tempo realmente esperou, e diz em bom português que chamar de novo é como você continua esperando. Duas ou três chamadas são uma espera normal para um e-mail de cadastro: esse é o loop, e são três turnos em vez de noventa.

Existem 8 vagas de espera, e nenhuma fila

Quando todas estão ocupadas, a chamada volta na hora e diz isso, em vez de entrar em uma fila atrás de outros sete agentes. É a falha certa: um agente que recebe “muitas esperas em andamento” pode listar a caixa de entrada e seguir em frente, enquanto um agente parado em uma fila só pode ficar parado.

O limite por endereço continua valendo por dentro disso — o nosso loop está sujeito ao mesmo limite de taxa que o seu, então uma espera do lado do servidor não é um jeito de contornar o piso, só um jeito de parar de pagar por ele em turnos. Para uma suíte de testes nada disso vale o esforço: um teste já é um processo que tem permissão para dormir, e um loop na linguagem em que o teste foi escrito é muito mais fácil de depurar do que um loop remoto. O guia de MCP cobre o resto das ferramentas.

O loop completo, de uma vez

Tudo o que veio antes, em um único arquivo: um prazo tirado de um relógio monotônico, um intervalo que se alarga com jitter de um lado só, Retry-After respeitado e não contado como tentativa, um watermark para decidir o que é novo, um filtro no assunto, e uma requisição extra para buscar a mensagem que a listagem só mostra em preview.

import random
import time
import requests

API     = "https://grabmail.io/api/v1"
ADDRESS = "signup-42@grabmail.io"


def delay(attempt: int) -> float:
    # One second while the message is probably still in flight, then
    # wider. Never below a second: the list endpoint allows one call
    # per second, per address, so jitter is added and never taken off.
    step = 1.0 if attempt < 15 else min(8.0, 2.0 ** (attempt - 14))
    return step + random.uniform(0.0, step / 2)


def watermark(s):
    # Read this BEFORE the form is submitted. Every id above it
    # afterwards is mail that arrived because of what you did.
    r = s.get(f"{API}/mailbox", params={"address": ADDRESS, "limit": 1})
    r.raise_for_status()
    seen = r.json()["messages"]
    return seen[0]["id"] if seen else None


def wait_for(s, subject, since, timeout=120.0):
    deadline = time.monotonic() + timeout
    attempt  = 0
    rejected = set()

    while time.monotonic() < deadline:
        r = s.get(f"{API}/mailbox", params={"address": ADDRESS, "limit": 25})

        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue                      # refused, so it was not an attempt
        if r.status_code == 200:
            for m in r.json()["messages"]:        # newest first
                if m["id"] == since:
                    break                 # older than the watermark
                if subject.lower() in m["subject"].lower():
                    full = s.get(f"{API}/message/{m['id']}",
                                 params={"mailbox": ADDRESS})
                    full.raise_for_status()
                    return full.json()
                rejected.add(m["subject"])
        elif r.status_code < 500:
            raise RuntimeError(r.json().get("error", r.status_code))
        # a 5xx falls through: transient, and the deadline still governs

        time.sleep(delay(attempt))
        attempt += 1

    raise TimeoutError(
        f"nothing matching {subject!r} at {ADDRESS} in {timeout:.0f}s; "
        f"saw {sorted(rejected) or 'nothing at all'}")

São, de propósito, cinquenta e poucas linhas de biblioteca padrão e um cliente HTTP. Não há nada para instalar, nada para configurar, e nenhum segredo em lugar nenhum — e esse é o ponto: a mesma forma se move sem mudanças para o Node, para um script shell, ou para o que quer que o seu framework de teste já use para fazer requisições.

1. Leia o watermark antes da ação que causa o e-mail, nunca depois.
2. Pergunte uma vez, imediatamente, e só então durma. Nunca durma primeiro.
3. Tire o prazo de um relógio monotônico, e verifique-o no início de cada volta.
4. Mantenha o intervalo em um segundo por endereço, ou mais, e adicione jitter só para cima.
5. Durma exatamente o que o Retry-After disser, e não conte uma recusa como tentativa.
6. Decida com base no slug error: unknown_domain e invalid_address significam pare, não espere.
7. Filtre por remetente ou assunto, e pare de percorrer a lista ao alcançar o watermark.
8. Abra a mensagem antes de fazer o parse dela — a listagem carrega um preview, não o corpo.
9. Falhe informando o endereço, o filtro, o orçamento, e os assuntos que o loop rejeitou.

Nove regras, e oito delas existem por causa de uma falha que alguém teve que reconstruir a partir de um log. A que não é sobre falha é a segunda: perguntar uma vez antes da primeira pausa é o que faz uma espera por uma mensagem que já chegou durar quatro milissegundos em vez de um segundo — o que, em uma suíte de duzentos testes, são três minutos de tempo real que depois ninguém precisa explicar.

Perguntas