API

REST + JSON para criar endereços temporários e ler mensagens de forma automatizada (testes, QA, cadastros em massa legítimos). Endereço base: https://instamail.sbs/api/v1

Duas coisas diferentes: o serviço e os domínios de e-mail

Você chama a API no endereço base acima (o domínio do próprio serviço). Os endereços de e-mail gerados usam outros domínios — os ativos agora são: lolipopa.online. Você não precisa chamar esses domínios; a API devolve o endereço pronto, com um domínio sorteado (ou o que você escolher em domain).

Autenticação

Envie sua chave em todas as requisições, em um destes cabeçalhos:

X-API-Key: tm_xxxxxxxxxxxxxxxxxxxxxxxx
Authorization: Bearer tm_xxxxxxxxxxxxxxxxxxxxxxxx

As chaves são emitidas pelo administrador do serviço. Cada chave tem validade (7 dias, 1 mês, 3 meses ou 1 ano, definida na emissão). Depois que a validade termina a chave deixa de funcionar e a resposta é 401 com chave_expirada. Para continuar, peça uma nova chave ao administrador. Há um teto de uso razoável por minuto por chave; se for excedido, a resposta é 429.

Fluxo típico

# 1. criar um endereço
curl -X POST https://instamail.sbs/api/v1/mailboxes -H "X-API-Key: $KEY"
# {"address":"k3m8q2xz7a@lolipopa.online"}

# 2. (use o endereço no cadastro do seu sistema)

# 3. esperar o e-mail chegar (até 60 s)
curl "https://instamail.sbs/api/v1/mailboxes/k3m8q2xz7a@lolipopa.online/wait?timeout=30&subject=confirm" -H "X-API-Key: $KEY"

Endpoints

GET/domains

Lista os domínios ativos.

{ "domains": ["lolipopa.online"] }
POST/mailboxes

Gera um endereço. Corpo opcional (JSON):

CampoDescrição
domainUm dos domínios de /domains. Se omitido, é sorteado.
nameParte antes do @ (a-z, 0-9, . - _, até 64). Se omitido, é aleatório.

Resposta 201: { "address": "..." }. Nada é gravado até chegar um e-mail.

GET/mailboxes/{address}/messages?since={ms}

Lista mensagens (mais recentes primeiro). since é opcional (epoch em milissegundos) e retorna só as posteriores.

{ "address": "k3m8q2xz7a@lolipopa.online",
  "messages": [
    { "id": "612b41cfb2507b38", "date": 1791821416301,
      "from": { "name": "Teste", "address": "teste@exemplo.com" },
      "subject": "Olá", "preview": "Trecho do texto…", "attachments": 0 }
  ] }
GET/mailboxes/{address}/messages/{id}

Mensagem completa: text, html (sanitizado, sem imagens remotas) e metadados de anexos.

GET/mailboxes/{address}/messages/{id}/attachments/{n}

Baixa o anexo n. Anexos acima de 3 MB não são guardados (available: false).

GET/mailboxes/{address}/wait

Espera (long-poll) pela próxima mensagem. Retorna a mensagem completa assim que ela existir.

ParâmetroDescrição
timeoutSegundos, de 1 a 60 (padrão 30).
sinceSó considera mensagens com date maior que este valor (ms). Padrão: 0.
fromFiltro: remetente contém o texto.
subjectFiltro: assunto contém o texto.

Responde 204 se nada chegar no prazo. Dica: guarde o date da última mensagem e use em since para esperar a seguinte.

DELETE/mailboxes/{address}/messages/{id}

Apaga uma mensagem.

DELETE/mailboxes/{address}/messages

Esvazia a caixa.

Erros

HTTPerrorSignificado
400endereco_invalido, dominio_invalido, nome_invalidoParâmetro inválido ou domínio não ativo
401chave_invalidaChave ausente, errada ou excluída
401chave_expiradaA validade da chave terminou
404nao_encontradaMensagem inexistente ou expirada
429limite_excedidoTeto de requisições por minuto excedido

Exemplo em JavaScript

const H = { 'X-API-Key': process.env.TEMPOMAIL_KEY };
const base = 'https://instamail.sbs/api/v1';

const { address } = await (await fetch(base + '/mailboxes', { method: 'POST', headers: H })).json();
// ... dispare o cadastro usando `address` ...
const r = await fetch(`${base}/mailboxes/${address}/wait?timeout=60&subject=confirm`, { headers: H });
if (r.status === 204) throw new Error('e-mail não chegou');
const msg = await r.json();
console.log(msg.subject, msg.text);

Boas práticas