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. Sem chave, a API permite 60 requisições por minuto e 1.000 por dia por endereço IP; uma chave paga remove os dois limites. 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.
A listagem também devolve um alias: um segundo endereço que entrega nesta mesma caixa e não revela nada sobre ela. Dê o alias ao formulário e consulte o endereço — quem tiver o alias só vê, sempre, uma caixa vazia.
$ 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"Se o endereço for recusado
Acontece, e não é um defeito. Os domínios públicos constam das listas negras públicas de correio descartável, e boa parte dos formulários de registo consulta-as. Mudar a parte antes do @ não ajuda — é o domínio que é recusado.
Aponte o seu próprio domínio para nós e o problema desaparece, de graça: ligar um domínio. Se preferir não usar o seu, um plano pago abre 97 domínios .com privados, fora dessas listas — as mesmas quatro chamadas, mais um cabeçalho Authorization: Bearer. Ver os planos.
Com uma chave, vale a pena conhecer mais duas chamadas: GET /api/v1/me verifica a chave e mostra o que resta da cota, e GET /api/v1/domains lista os nomes de domínio do pool — apenas para uma chave paga. O passo a passo completo, com os códigos de erro, está em a referência da API.
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 — e os domínios públicos estão impressos neste site, então eles são adivinhados. Em um domínio seu, um endereço só pode ser encontrado por quem já o conhece. Um registro MX, e nada mais para fazer.
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
Um registro MX, e todo endereço do seu domínio funciona aqui — nada para registrar.