Início rápido
Do zero a uma mensagem lida de volta pelo HTTP, em quatro comandos. Sem conta, sem chave, sem SDK.
1. Escolha um endereço
Qualquer nome, em qualquer um dos nossos domínios públicos. Não há nada para chamar nem para registrar — o endereço se torna real no momento em que algo é entregue a ele.
Mantenha-o difícil de adivinhar se preferir que ninguém entre por acaso: em um domínio público, o endereço é a única coisa entre a caixa de entrada e o mundo.
$ ADDR="ci-$(openssl rand -hex 4)@grabmail.io"; echo "$ADDR"2. Envie algo para ele
Use-o no formulário de cadastro, no fluxo de redefinição de senha ou no que você estiver testando. A entrega normalmente leva alguns segundos.
Nossos servidores de e-mail aceitam mensagens de até 5 MB. Qualquer coisa maior é recusada no momento do SMTP, então o remetente é avisado na hora em vez de ficar sem saber.
$ curl -sX POST https://your-app.example/signup --data-urlencode "email=$ADDR"3. Consulte a caixa de entrada
Uma requisição por segundo é o ritmo previsto e nunca é limitado. Uma caixa de entrada vazia responde 200 com count: 0 — nunca um 404, então seu loop não precisa tratar esse caso à parte.
Este trecho desiste depois de um minuto em vez de ficar rodando para sempre, o que é o ideal na CI.
$ for i in $(seq 60); do
ID=$(curl -sG https://grabmail.io/api/v1/mailbox --data-urlencode "address=$ADDR" | jq -r '.messages[0].id // empty')
[ -n "$ID" ] && break
sleep 1
done; echo "$ID"4. Leia e depois descarte
Busque a mensagem e extraia o que você veio procurar — aqui, um código de seis dígitos da parte em texto simples.
Apagar é opcional: tudo some sozinho depois de 5 dias. Faça isso mesmo assim na CI, e a próxima execução começa com uma caixa de entrada limpa.
$ curl -sG https://grabmail.io/api/v1/message/$ID --data-urlencode "mailbox=$ADDR" \
| jq -r .text | grep -oE '[0-9]{6}'
curl -sX DELETE -G https://grabmail.io/api/v1/message/$ID --data-urlencode "mailbox=$ADDR"Integrando ao CI
Dois hábitos evitam que uma suíte que lê e-mails reais fique instável:
- Um endereço novo por execução
- Derive-o do id do build ou de um sufixo aleatório. Reutilizar um endereço entre execuções significa que a mensagem de ontem pode satisfazer a verificação de hoje.
- Um prazo, não um número de tentativas
- Faça polling contra um tempo limite de relógio, como acima. As tentativas ficam silenciosamente mais longas se o remetente ficar mais lento.
- Nunca dependa do tempo de entrega
- Email não é síncrono. Verifique que a mensagem chega, não que ela chega dentro de um segundo específico.
- Use seu próprio domínio para algo real
- Uma caixa de entrada pública pode ser lida por qualquer um que adivinhe o endereço. Isso é aceitável para um cadastro descartável, e não é aceitável para um ambiente de staging com dados de clientes. Um registro MX resolve isso.
Para agentes de IA: MCP
Um agente não consegue ler esta página, decidir qual endpoint quer e escrever uma requisição. Ele pergunta a um servidor quais ferramentas existem e as chama. O grabmail roda um servidor Model Context Protocol exatamente para isso, em https://grabmail.io/mcp — sem chave, sem conta.
Aponte qualquer cliente MCP para o endpoint. Claude Desktop, Cursor, Continue e o OpenAI Agents SDK entendem esse formato.
Seis ferramentas: create_inbox, list_domains, list_messages, read_message, delete_message e wait_for_message.
$ {"mcpServers":{"grabmail":{"url":"https://grabmail.io/mcp"}}}wait_for_message é o que importa. O motivo de um agente querer uma caixa de entrada descartável é quase sempre um código de confirmação entre ele e o próximo passo. Em vez de ficar consultando em loop e gastando tokens com isso, ele pede um endereço, envia o formulário e bloqueia até a mensagem chegar:
Espera até 25 segundos e retorna a mensagem completa — remetente, assunto, corpo — ou informa que houve tempo esgotado, para que o agente simplesmente chame de novo.
Também pode esperar por uma mensagem específica: passe subject_contains ou from_contains e tudo o mais que chegar é ignorado.
$ 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":"you@grabmail.io","subject_contains":"code"}}}'Há também uma especificação OpenAPI 3.1 (YAML) para geradores de código, e o llms.txt para quem prefere ler texto simples.
Próximo
Referência da API
Cada parâmetro, cada código de status, o formato de erro.
Limites
O que tem limite, o que não tem, e o que acontece no teto.
Seu próprio domínio
Torne toda caixa de entrada do seu domínio privada só para você.