Três endpoints, JSON na entrada e na saída. Sem chave e sem conta em domínios
públicos — cole uma requisição em um terminal e funciona.
Visão geral
Uma caixa de entrada nunca é criada — ela existe no momento em que uma
mensagem chega a um endereço, e desaparece 5 dias depois. Não há
nada para registrar, então nos domínios públicos a API não tem conceito de
usuário, projeto ou token.
Toda resposta é JSON, incluindo todo erro.
Todos os horários são UTC no formato RFC 3339 — 2026-08-04T18:31:07Z.
Os ids de mensagem são strings opacas. Não tente interpretá-los.
Somente recebimento. Não há endpoint que envie e-mail, por design.
URL base
https://grabmail.io/api/v1
Apenas HTTPS; HTTP puro é redirecionado. A versão fica no caminho, e
v1 não vai mudar de forma sob você — uma mudança que quebre
compatibilidade ganha um novo número.
Autenticação: nenhuma
Nenhuma nos domínios públicos. Qualquer pessoa que conheça
um endereço pode ler sua caixa de entrada, tanto pela API quanto pelo site.
Esse é o acordo que um serviço descartável compartilhado propõe, então nunca
use um endereço público para algo que importa.
Um domínio que você aponta para cá responde nesses mesmos endpoints, também sem chave. Aponte o MX para nós e a primeira mensagem o conecta; veja conectar um domínio. As caixas de entrada nele podem ser lidas por qualquer um que conheça o endereço, exatamente como nos domínios públicos.
A única credencial nesta API é a chave da sua conta, descrita abaixo — uma numa conta gratuita, mais nos planos pagos. Uma chave não tem nível próprio: cada chamada é julgada pelo plano que a conta tem nesse momento, por isso a mesma chave perde os tetos gratuitos e abre o conjunto premium assim que você assina, e volta à quota gratuita quando o plano termina. Os domínios públicos não precisam de nenhuma; enviada com eles, ela conta as suas chamadas para a sua conta em vez do seu endereço IP. Uma chave enviada que seja desconhecida ou tenha sido revogada responde 401 com unauthorized em todos os endpoints, seja qual for o domínio — assim um erro de digitação aparece na hora, em vez de parecer uma caixa vazia.
Domínios premium
A única exceção à regra acima. Os domínios públicos
constam das listas públicas de correio descartável, e por isso um formulário de registo
recusa por vezes um endereço neles alojado. Um plano pago abre um pool de
97 domínios .com privados, fora dessas listas.
A API não muda em nada. Mesmos caminhos, mesmos parâmetros, mesmos formatos de resposta. A única diferença é um cabeçalho: um endereço premium lê-se com Authorization: Bearer gm_live_…, com uma chave de as suas chaves de API. Sem uma chave de um plano pago, o mesmo pedido responde 404 — palavra por palavra a mesma resposta de um domínio que não hospedamos, de propósito, para que o pool não possa ser listado adivinhando nomes. Nunca uma caixa.
Onde estão os domínios do pool
GET /api/v1/domains com a sua chave devolve os domínios públicos e os nomes de domínio do pool. A mesma chamada sem chave — ou com uma chave de uma conta gratuita ou vencida — devolve os domínios públicos, quantos domínios o pool tem e quanto custa, mas nunca um nome: mantê-los fora das listas negras de correio descartável é o que o plano paga. Um assinante com sessão iniciada também vê o pool no seletor de domínios da página inicial.
GET /api/v1/me é a única chamada que avalia uma chave por si só: 200 com o plano, o período atual, a cota consumida e restante, os endereços mantidos e o seu limite de taxa — ou 401unauthorized se a chave for desconhecida ou tiver sido revogada. Chame-a primeiro quando algo no pool responder 404: essa resposta esconde um problema de chave de propósito, esta mostra.
Cada caso, com o motivo por trás dele. Os dois primeiros parecem surpreendentes até você ler o motivo.
404
unknown_domain — sem chave, ou uma chave de uma conta gratuita ou vencida. Idêntico, de propósito, à resposta para um domínio que não hospedamos: distinguir os dois permitiria listar o pool adivinhando nomes. Verifique a chave com /api/v1/me.
401
unauthorized — a chave enviada é desconhecida ou foi revogada. É respondido em todos os endpoints, seja qual for o domínio: isso diz algo sobre a chave, nunca sobre um domínio.
402
quota_reached — a cota deste período acabou e o excedente está desativado. overage_cap / overage_funds — o excedente está ativado, mas o teto que você definiu foi atingido ou o saldo é insuficiente. Os endereços já mantidos continuam funcionando nos três casos.
403
address_taken — outro assinante mantém esse endereço. Escolha outro nome.
409
address_limit — reservado para um plano que limita o número de endereços. Hoje, nenhum plano faz isso.
429
rate_limited — no plano gratuito (sem chave, ou com uma gratuita), mais de 60 requisições por minuto, ou mais de uma leitura por segundo em um endereço; com uma chave paga, mais de 2, 3 ou 5 leituras por segundo em um endereço. daily_limit_reached — as 1.000 requisições grátis do dia acabaram. Os planos pagos não têm nem o limite por minuto nem o diário. Os dois trazem Retry-After.
Endereços mantidos e a cota
Um endereço premium é mantido pela primeira conta que o lê com uma chave válida — qualquer leitura, em qualquer endpoint ou pelo MCP, sem nada para reservar antes. Enquanto estiver mantido, só essa conta pode lê-lo; qualquer outra recebe 403. Ele continua mantido até você liberá-lo no painel, ou até o plano terminar — na sua data de término, sem carência.
A cota conta unidades: uma mensagem recebida em um endereço premium ou um novo endereço premium aberto, o que vier primeiro — então um endereço que você abre e nunca lê ainda assim usa uma unidade. Ler de novo um endereço já mantido é gratuito. Nenhum plano limita quantos endereços uma conta mantém; quem limita isso é a cota, e /api/v1/me mostra o que resta.
O alias, também nos endereços premium
Toda listagem de caixa de entrada carrega um alias: um segundo endereço que entrega na mesma caixa e não revela nada sobre ela. Dê o alias a um formulário e consulte o endereço; quem tiver o alias sempre vê uma caixa vazia. Ele é estável para um determinado endereço, gratuito, e é devolvido para endereços premium exatamente como para os públicos. O domínio dele é um dos nossos e não é listado em lugar nenhum, de propósito.
Tudo isso, em quatro chamadas
KEY="gm_live_…" # da página das suas chaves de API, com um plano pago
# 1. Verificar a chave: plano, cota restante, limite de taxa. 401 se for inválida.
curl -s https://grabmail.io/api/v1/me -H "Authorization: Bearer $KEY"
# 2. Listar o pool. Os nomes só aparecem na resposta com uma chave paga.
curl -s https://grabmail.io/api/v1/domains -H "Authorization: Bearer $KEY"
# 3. Ler uma caixa em um deles. Esta primeira leitura mantém o endereço e conta como uma unidade.
curl -sG https://grabmail.io/api/v1/mailbox -H "Authorization: Bearer $KEY" \
--data-urlencode "address=a7f3k2@one-of-the-pool.com"
# 4. Ler uma mensagem, mesmo cabeçalho.
curl -sG https://grabmail.io/api/v1/message/MESSAGE_ID -H "Authorization: Bearer $KEY" \
--data-urlencode "mailbox=a7f3k2@one-of-the-pool.com"
Os domínios públicos e os seus próprios domínios continuam gratuitos, sem chave e sem limite em todos os planos, incluindo o gratuito. A cota conta apenas o pool premium e mais nada. Os planos e os preços estão em a página dos planos.
Endpoints
GET/api/v1/mailbox
Tudo o que está esperando em um endereço, do mais novo ao mais antigo. Esta é a chamada que seu conjunto de testes consulta repetidamente.
Parâmetros
Nome
Em
Tipo
Obrigatório
Descrição
address
query
string
sim
A caixa de entrada a ser lida, ex.: k7fq2m@grabmail.io.
limit
query
integer
não
Quantas mensagens retornar nesta chamada, 1–200. O padrão é 50, mais recentes primeiro. Isso limita uma resposta, não a caixa de entrada — use before para ler além dela.
before
query
string
não
O id da mensagem mais antiga que você já tem; retorna a página seguinte a ela. Devolva o campo next da resposta anterior. Quando next for null, você tem tudo.
A caixa de entrada foi lida. Uma caixa de entrada vazia é um 200 com count: 0, nunca um 404. next carrega o cursor para a página seguinte, ou null no final. alias é um segundo endereço que entrega aqui e não revela nada sobre esta — dê-o a um formulário em vez de address; quem o tiver sempre vê uma caixa vazia. Ele é estável, gratuito, e também é devolvido para endereços premium.
400
O endereço está malformado, ou before não é um id de mensagem.
400
address está ausente ou não é um endereço válido.
401
Uma chave de API foi enviada e é desconhecida ou foi revogada. Uma chave errada é recusada em qualquer domínio; os domínios públicos não precisam de nenhuma.
402
Somente no pool premium: a cota do plano acabou — quota_reached, ou overage_cap / overage_funds quando o excedente está ativado. Os endereços já mantidos continuam funcionando.
403
Somente no pool premium: outro assinante mantém esse endereço (address_taken).
404
Esse domínio não é hospedado aqui — verifique o registro MX. Um domínio do pool premium lido sem uma chave de um plano pago responde exatamente isso, de propósito.
429
Limite de requisições excedido. Tente novamente após o atraso em Retry-After.
GET/api/v1/message/{id}
Cabeçalhos, a parte em texto simples, a parte em HTML e quaisquer anexos.
Parâmetros
Nome
Em
Tipo
Obrigatório
Descrição
id
path
string
sim
O id de mensagem retornado pela chamada de listagem.
Excluído. A chamada é idempotente: excluir duas vezes ainda responde 200.
400
mailbox está ausente ou é inválido.
404
Nenhuma mensagem encontrada nessa caixa de entrada.
429
Limite de requisições excedido.
Anexos
Toda mensagem lista seus anexos com uma URL pronta. Baixe-o com a mesma
autorização usada para a mensagem em si.
GET /api/v1/attachment/{id}?mailbox={address}
Ele sempre responde application/octet-stream com
Content-Disposition: attachment, seja qual for o rótulo do
remetente. Isso é proposital: devolver o text/html de um
estranho permitiria que um anexo rodasse como página nesta mesma origem. O
tipo real está no JSON da mensagem, onde é dado, não instrução.
Erros
Toda falha é um JSON com os mesmos dois campos, então um cliente trata
todas em um único lugar. O status carrega a categoria, error é
um identificador estável e legível por máquina, e message é
para humanos e pode mudar de texto a qualquer momento.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_address",
"message": "address must look like name@domain"
}
Nunca decida com base em message. Os identificadores em uso são invalid_address, bad_cursor, unknown_domain, not_found, rate_limited, daily_limit_reached, unauthorized e, somente no pool premium, quota_reached, overage_cap, overage_funds, address_taken e address_limit.
Alguns erros trazem mais que os dois campos: um hint dizendo o que fazer, um link docs, em 404 e 429 um bloco premium_pool com o preço do pool e como desbloqueá-lo, e em um 429 de limite gratuito um bloco upgrade dizendo o que um plano pago remove — pensados para um assistente que lê o corpo da resposta em nome de alguém, para que ele possa repassar a opção em vez de desistir.
Limites de taxa
Grátis, sem chave: 60 requisições por minuto e 1.000 por dia, por endereço IP. Toda chamada a uma caixa de entrada conta — listá-la, ler uma mensagem, o corpo HTML dela, um anexo, uma exclusão — e o mesmo vale para cada chamada de ferramenta MCP. O contador diário zera às 00:00 UTC.
Com uma chave de API gratuita, a mesma quota acompanha a sua conta em vez do seu endereço IP — útil quando as suas chamadas saem de endereços que mudam, como um runner de CI. Uma conta gratuita tem uma chave, e as caixas que ela lê são listadas nas suas caixas. Criar uma chave gratuita
Dentro disso, uma leitura por segundo por endereço: consultar uma caixa de entrada uma vez por segundo é o ritmo previsto.
Os planos pagos não têm limite por minuto nem limite diário. Envie a chave de um plano pago como Authorization: Bearer e passa a valer só a taxa por endereço do plano — 2, 3 ou 5 requisições por segundo, em qualquer domínio, contadas por conta. O Premium custa a partir de $12,99 por mês. Ver os planos
A caixa de entrada deste site não consome a cota gratuita da API: uma página deixada aberta continua verificando se chegou e-mail pelo tempo que você precisar.
Ao passar de um limite você recebe 429 com um cabeçalho Retry-After em segundos inteiros: rate_limited para o limite por minuto ou por endereço, daily_limit_reached para o limite diário, com o tempo que falta até a meia-noite UTC. Toda resposta gratuita mostra em que pé você está: X-RateLimit-Remaining para o minuto, X-RateLimit-Daily-Remaining para o dia.
Retenção
Uma mensagem é apagada 5 dias
depois de chegar, lida ou não. Toda mensagem traz
expires_at, então você nunca precisa calcular essa data.
É um limite fixo, não uma configuração — nenhum parâmetro o estende. Se uma
mensagem precisa sobreviver além dessa janela, busque-a e guarde-a do seu
lado.
Seu próprio domínio
Aponte seu MX para smtp.grabmail.io e todo endereço do seu domínio responde por esses mesmos endpoints — sem uma segunda API para aprender, sem registro e sem chave.
