API · testing

Create a temporary inbox

POST /api/v2/testing/inboxes

Authorization

inboxes:create. Use a workspace-scoped bearer key or an authorized user session.

Parameters

Required header: Idempotency-Key (1–100 alphanumeric, underscore or hyphen characters).

Name	Type	Contract
name	string · required	1–60 characters
ttl_seconds	integer · optional	60–86400; default 3600

Request

Set INBOXIT_API_KEY in your server environment. The CLI can also use an authenticated user session.

Example

curl -X POST 'https://inboxit.wtf/api/v2/testing/inboxes' \
  -H "Authorization: Bearer $INBOXIT_API_KEY" \
  -H "Content-Type: application/json" --data @request.json \
  -H "Idempotency-Key: request-001"

JSON body

Save this JSON as request.json for the request above. Replace example values with your own.

Example

{
  "name": "Signup test",
  "ttl_seconds": 3600
}

CLI equivalent

Use INBOXIT_TOKEN for a scoped key, or inboxit login for a user session.

Example

inboxit testing create --data @request.json --idempotency-key request-001

Response

HTTP 201. Example values are illustrative; excerpts are marked.

Example

{
  "id": "INBOX_UUID",
  "address": "agent-generated@agents.inboxit.wtf",
  "status": "pending",
  "test_expires_at": "2026-10-23T20:00:00Z"
}

Behavior & errors

Native provisioning is asynchronous. Poll list until active. Idempotency-Key required. Same key with changed parameters returns 409. Incoming volume and storage limits apply. Common errors: 400 invalid input, 401 unauthenticated, 403 insufficient permission, 404 missing/inaccessible resource, 409 conflict, 429 rate/usage limit, 503 service unavailable. See Errors & retries for recovery guidance.