API Documentation

Build with GoneBox. Create temporary inboxes, read messages, and integrate disposable email into your apps and workflows.

Overview

The GoneBox API is a RESTful API that lets you programmatically create temporary email inboxes and retrieve messages. Perfect for automated testing, CI/CD pipelines, and AI agent workflows.

Authentication

All API requests require an API key passed in the X-API-Key header. Get your API key from the GoneBox dashboard after subscribing to a paid plan.

X-API-Key: your-api-key-here

Base URL

https://api.gonebox.email

Endpoints

POST/v1/inboxes

Create Inbox

Create a new temporary email inbox. Returns the email address and inbox ID.

Parameters

domainDomain for the email (gonebox.email, sumiu.email, nemexiste.email). Default: gonebox.email
usernameOptional custom username. If not provided, a random one is generated.
ttlTime-to-live in seconds. Default: 3600 (1 hour). Max depends on plan.

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}

Get Inbox

Retrieve inbox details and status.

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

List Messages

List all messages in an inbox. Returns an array of message summaries.

Response

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

Get Message

Retrieve the full content of a specific message, including HTML body and attachments.

Response

{
  "id": "msg_def456",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Verify your email",
  "text": "Click here to verify...",
  "html": "<p>Click <a href='...'>here</a> to verify...</p>",
  "received_at": "2026-05-19T10:05:00Z",
  "attachments": []
}
DELETE/v1/inboxes/{inbox_id}

Delete Inbox

Immediately and permanently delete an inbox and all its messages.

Response

{
  "deleted": true
}

Rate Limits

Rate limits are applied per API key. Exceeding limits returns HTTP 429.

PlanLimits
freeFree: No API access
devDev: 60 requests/minute, 1,000 emails/day
startupStartup: 300 requests/minute, 10,000 emails/day
enterpriseEnterprise: 1,000 requests/minute, 100,000 emails/day

Error Codes

All errors follow a consistent format with a code and human-readable message.

CodeDescription
400Bad Request — Invalid parameters
401Unauthorized — Missing or invalid API key
403Forbidden — Plan does not allow this action
404Not Found — Inbox or message does not exist
429Too Many Requests — Rate limit exceeded
500Internal Server Error — Something went wrong on our end
{
  "error": {
    "code": 401,
    "message": "Invalid API key"
  }
}

MCP Server

GoneBox provides an MCP (Model Context Protocol) server for AI agents like Claude, Cursor, and other LLM-powered tools. The MCP server exposes the same functionality as the REST API in a format optimized for AI consumption.

Install

npm install -g @gonebox/mcp-server

Add to your MCP client configuration:

{
  "mcpServers": {
    "gonebox": {
      "command": "gonebox-mcp",
      "env": {
        "GONEBOX_API_KEY": "your-api-key"
      }
    }
  }
}

Code Examples

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"