Documentação da API

Construa com o GoneBox. Crie caixas temporárias, leia mensagens e integre email descartável nos seus apps e workflows.

Visão Geral

A API do GoneBox é uma API RESTful que permite criar caixas de email temporárias e recuperar mensagens programaticamente. Perfeita para testes automatizados, pipelines CI/CD e workflows de agentes de IA.

Autenticação

Todas as requisições da API requerem uma chave de API no header X-API-Key. Obtenha sua chave no dashboard do GoneBox após assinar um plano pago.

X-API-Key: sua-chave-api-aqui

URL Base

https://api.gonebox.email

Endpoints

POST/v1/inboxes

Criar Caixa

Cria uma nova caixa de email temporária. Retorna o endereço de email e o ID da caixa.

Parameters

domainDomínio para o email (gonebox.email, sumiu.email, nemexiste.email). Padrão: gonebox.email
usernameNome de usuário opcional. Se não fornecido, um aleatório é gerado.
ttlTempo de vida em segundos. Padrão: 3600 (1 hora). Máximo depende do plano.

Response

{
  "id": "inbox_abc123",
  "email": "[email protected]",
  "created_at": "2026-05-19T10:00:00Z",
  "expires_at": "2026-05-19T11:00:00Z",
  "ttl": 3600
}

cURL

curl -X POST https://api.gonebox.email/v1/inboxes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"domain": "gonebox.email", "ttl": 3600}'
GET/v1/inboxes/{inbox_id}

Obter Caixa

Recupera detalhes e status da caixa.

Response

{
  "id": "inbox_abc123",
  "email": "[email protected]",
  "created_at": "2026-05-19T10:00:00Z",
  "expires_at": "2026-05-19T11:00:00Z",
  "message_count": 3,
  "status": "active"
}
GET/v1/inboxes/{inbox_id}/messages

Listar Mensagens

Lista todas as mensagens de uma caixa. Retorna um array de resumos de mensagens.

Response

{
  "messages": [
    {
      "id": "msg_def456",
      "from": "[email protected]",
      "subject": "Verifique seu email",
      "received_at": "2026-05-19T10:05:00Z",
      "size": 2048
    }
  ],
  "total": 1
}
GET/v1/inboxes/{inbox_id}/messages/{message_id}

Obter Mensagem

Recupera o conteúdo completo de uma mensagem específica, incluindo corpo HTML e anexos.

Response

{
  "id": "msg_def456",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Verifique seu email",
  "text": "Clique aqui para verificar...",
  "html": "<p>Clique <a href='...'>aqui</a> para verificar...</p>",
  "received_at": "2026-05-19T10:05:00Z",
  "attachments": []
}
DELETE/v1/inboxes/{inbox_id}

Deletar Caixa

Deleta imediatamente e permanentemente uma caixa e todas as suas mensagens.

Response

{
  "deleted": true
}

Limites de Taxa

Limites de taxa são aplicados por chave de API. Exceder os limites retorna HTTP 429.

PlanLimits
freeGratuito: Sem acesso à API
devDev: 60 requisições/minuto, 1.000 emails/dia
startupStartup: 300 requisições/minuto, 10.000 emails/dia
enterpriseEnterprise: 1.000 requisições/minuto, 100.000 emails/dia

Códigos de Erro

Todos os erros seguem um formato consistente com código e mensagem legível.

CodeDescription
400Bad Request — Parâmetros inválidos
401Unauthorized — Chave de API ausente ou inválida
403Forbidden — Plano não permite esta ação
404Not Found — Caixa ou mensagem não existe
429Too Many Requests — Limite de taxa excedido
500Internal Server Error — Algo deu errado do nosso lado
{
  "error": {
    "code": 401,
    "message": "Chave de API inválida"
  }
}

MCP Server

O GoneBox fornece um servidor MCP (Model Context Protocol) para agentes de IA como Claude, Cursor e outras ferramentas com LLM. O servidor MCP expõe a mesma funcionalidade da API REST em um formato otimizado para consumo por IA.

Install

npm install -g @gonebox/mcp-server

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "gonebox": {
      "command": "gonebox-mcp",
      "env": {
        "GONEBOX_API_KEY": "sua-chave-api"
      }
    }
  }
}

Exemplos de Código

JavaScript / TypeScript

const response = await fetch('https://api.gonebox.email/v1/inboxes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.GONEBOX_API_KEY,
  },
  body: JSON.stringify({
    domain: 'gonebox.email',
    ttl: 3600,
  }),
});

const inbox = await response.json();
console.log(inbox.email); // [email protected]

// Wait for messages...
const messages = await fetch(
  `https://api.gonebox.email/v1/inboxes/${inbox.id}/messages`,
  { headers: { 'X-API-Key': process.env.GONEBOX_API_KEY } }
).then(r => r.json());

console.log(messages);

Python

import requests
import os

API_KEY = os.environ["GONEBOX_API_KEY"]
BASE_URL = "https://api.gonebox.email"

# Create inbox
inbox = requests.post(
    f"{BASE_URL}/v1/inboxes",
    headers={"X-API-Key": API_KEY},
    json={"domain": "gonebox.email", "ttl": 3600},
).json()

print(inbox["email"])  # [email protected]

# Get messages
messages = requests.get(
    f"{BASE_URL}/v1/inboxes/{inbox['id']}/messages",
    headers={"X-API-Key": API_KEY},
).json()

print(messages)

cURL

# Create inbox
curl -X POST https://api.gonebox.email/v1/inboxes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GONEBOX_API_KEY" \
  -d '{"domain": "gonebox.email", "ttl": 3600}'

# List messages
curl https://api.gonebox.email/v1/inboxes/inbox_abc123/messages \
  -H "X-API-Key: $GONEBOX_API_KEY"

# Get specific message
curl https://api.gonebox.email/v1/inboxes/inbox_abc123/messages/msg_def456 \
  -H "X-API-Key: $GONEBOX_API_KEY"

# Delete inbox
curl -X DELETE https://api.gonebox.email/v1/inboxes/inbox_abc123 \
  -H "X-API-Key: $GONEBOX_API_KEY"