API para desenvolvedores

CoolMail API

Crie inboxes de e-mail temporário e receba códigos de verificação direto do seu código — sem mexer em caixa de entrada, sem browser. A mesma infraestrutura do painel, por Bearer token.

Comece em 3 passos

1Crie sua conta e recarregue via Pix (R$ 5,00 = 1 inbox)
2Crie sua chave no Painel, seção API
3Chame a API — o endpoint /code já entrega o código pronto

Quickstart

https://coolmail.click/api/v1

terminal

# 1) cria a inbox e recebe o endereçocurl -s -X POST https://coolmail.click/api/v1/inboxes \  -H "Authorization: Bearer cmk_live_SUA_CHAVE" \  -H "Content-Type: application/json" -d '{}' # 2) long-poll: segura até 25s esperando o código de verificaçãocurl -s "https://coolmail.click/api/v1/inboxes/SEU_INBOX_ID/code?wait=25" \  -H "Authorization: Bearer cmk_live_SUA_CHAVE"

resposta.json

{  "status": "ok",  "codigo": "482913",  "alts": [],  "from": "no-reply@example.com",  "subject": "Your verification code",  "received_at": 1760000000000,  "message_id": "b2c4…",  "address": "raposa-azul-4821@exemplo.com"}

Autenticação

Todas as rotas exigem o header Authorization com a sua chave (formato cmk_live_…). A chave aparece uma única vez na criação — guarde-a com segurança e revogue no painel se vazar.

Authorization: Bearer cmk_live_Ab3xY…

Endpoints

Método	Rota	Descrição
GET	/me	Saldo, e-mail e dados da chave
POST	/inboxes	Cria um inbox (R$ 5,00; com alias R$ 10,00). Campos opcionais: alias e domain (TLD do pool, mesmo preço)
GET	/domains	Domínios do pool — use no campo domain do POST /inboxes
GET	/inboxes	Lista os seus inboxes com contagem de mensagens
GET	/inboxes/{id}	Detalhe de um inbox
GET	/inboxes/{id}/messages	Últimas 100 mensagens (mais novas primeiro)
GET	/messages/{id}	Mensagem completa (texto, HTML, código, links)
GET	/inboxes/{id}/code?wait=25	Long-poll: espera até 25s e devolve o código pronto

O endpoint que você quer: /code

A automação de cadastro não quer ler e-mail — quer o código. O /code segura a conexão até 25 segundos, resolve o parse MIME, decodifica o assunto e roda a heurística de código pra você. Sem mensagem com código no prazo, devolve timeout — é só chamar de novo.

quickstart.py

import requests K = {"Authorization": "Bearer cmk_live_SUA_CHAVE"}base = "https://coolmail.click/api/v1" inbox = requests.post(f"{base}/inboxes", headers=K, json={}).json()print(inbox["address"])   # cole no cadastro do site r = requests.get(f"{base}/inboxes/{inbox['id']}/code",                 headers=K, params={"wait": 25}, timeout=35).json()print(r["codigo"])        # o código de verificação

quickstart.js

const K = { Authorization: "Bearer cmk_live_SUA_CHAVE" };const base = "https://coolmail.click/api/v1"; const inbox = await fetch(base + "/inboxes", {  method: "POST", headers: { ...K, "Content-Type": "application/json" },  body: "{}",}).then((r) => r.json()); const code = await fetch(base + "/inboxes/" + inbox.id + "/code?wait=25", {  headers: K,}).then((r) => r.json()); console.log(code.codigo);

Webhooks: o código chega no seu servidor

Prefere não fazer polling? Cadastre um endpoint https no Painel (seção Webhooks) e a CoolMail faz um POST assinado no instante em que o e-mail chega — com o código já extraído pelas mesmas heurísticas do /code. Sem custo por entrega.

payload.json

{  "type": "message.received",  "created_at": 1760000000000,  "data": {    "message_id": "9f1c8a…",    "address": "raposa-azul-4821@exemplo.com",    "from": "no-reply@example.com",    "subject": "Your verification code",    "codigo": "482913",    "alts": ["482913"],    "links": ["https://exemplo.com/verify?token=…"],    "received_at": 1760000000000,    "text": "Your code is 482913. It expires in…"  }}

Verificando a assinatura

Cada entrega traz o header X-CoolMail-Signature: t=<unix>,v1=hmac_sha256(secret, "<t>.<corpo>") — mesmo esquema do Stripe. Valide com o secret whsec_… que você recebeu na criação do webhook (e confira |now − t| < 5 min pra bloquear replay):

verificar.py

import hmac, hashlib # o v1 é sobre o corpo CRU — leia o body sem parsear antesdef verifica(secret, header, raw_body):    partes = dict(p.split("=", 1) for p in header.split(",")]    esperado = hmac.new(        secret.encode(), f"{partes['t']}.".encode() + raw_body,        hashlib.sha256,    ).hexdigest()    return hmac.compare_digest(esperado, partes["v1"])

verificar.js

import crypto from "node:crypto"; // o v1 é sobre o corpo CRU — leia o body sem parsear antesfunction verifica(secret, header, rawBody) {  const p = Object.fromEntries(    header.split(",").map((x) => x.split("="))  );  const esperado = crypto    .createHmac("sha256", secret)    .update("${p.t}." + rawBody)    .digest("hex");  return crypto.timingSafeEqual(    Buffer.from(esperado), Buffer.from(p.v1)  );}

Entrega at-least-once: o mesmo message_id pode chegar mais de uma vez — dedupe no seu lado
Timeout de 10s por tentativa + 1 retry imediato; 20 falhas seguidas pausam o webhook (você reativa no painel)
O payload não traz HTML — o corpo completo é GET /v1/messages/{id} com a sua chave
Até 3 endpoints ativos por conta, gerenciados no Painel (seção Webhooks)

MCP Server

Conecte agentes de IA (Claude, Cursor, Cline…) ao CoolMail via Model Context Protocol: o agente cria a inbox, espera o e-mail e lê o código de verificação — sem painel, sem copiar-e-colar.

create_inbox	cria uma inbox (debita R$5 do saldo — o cliente MCP pede sua confirmação; máx. 100/dia por chave). Parâmetros opcionais: alias e domain (TLD do pool, mesmo preço — a descrição da tool lista os domínios disponíveis)
list_inboxes	lista as inboxes da conta
wait_for_email	long-poll de até 25s esperando um código de verificação chegar na inbox
get_message	lê o conteúdo completo de uma mensagem (texto, código e links)
extract_otp	extrai só o código de verificação de uma mensagem
extract_links	extrai os links de uma mensagem (o melhor palpite de link de verificação vem primeiro)

Erros

Toda resposta de erro é JSON {erro, codigo}. Os códigos estáveis:

401chave_ausente / chave_invalida / chave_revogadaproblema na Authorization

400dominio_invalidodomain fora do pool — pegue a lista no GET /domains

402saldo_insuficientevem com precisa_cents — recarregue no painel

404—inbox/mensagem não existe ou não é seu (nunca 403)

409alias_em_usoalias customizado já taken

429rate_limitedestourou o limite por chave

Limites

10 inboxes/min, 30 chamadas /code/min e 120 leituras/min, por chave
100 inboxes/dia por chave (cap diário, vale pra API e pro MCP)
wait máximo de 25s por chamada /code (re-chame em loop)
GET /messages/{id} devolve text, html, codigo, alts e links (todos os URLs; o primeiro é o melhor palpite de link de verificação — com um único URL na mensagem, ele é devolvido direto)
Listas retornam até 100 mensagens; /code procura nas 10 mais recentes
E-mails acima de 512KB são truncados (o parse tolera)
Inbox é permanente: paga-se uma vez, recebe pra sempre

Preço

Mesmo preço do painel, debitado da mesma carteira Pix: R$ 5,00 por inbox com alias aleatório e R$ 10,00 com alias que você escolher. Escolher o domínio (TLD) sai no mesmo preço. Sem mensalidade, sem cobrança por mensagem recebida.