Inbox management

GET /v1/inboxes

Returns all inboxes registered to your account.

curl

curl "https://api2.freecustom.email/v1/inboxes" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200Success

json

{
  "success": true,
  "data": {
    "inboxes": ["test@freecustom.email", "staging@acme.com"],
    "count": 2
  }
}

200Empty

json

{
  "success": true,
  "data": { "inboxes": [], "count": 0 }
}

401Missing or invalid API key

json

{
  "success": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key. Pass your key in the Authorization header: Bearer fce_..."
}

POST /v1/inboxes

Request body:

Field	Type	Required	Description
inbox	string	Yes	Full email address (e.g. test@freecustom.email)
isTesting	boolean	No	Flag this inbox for testing purposes to enable zero-latency event timelines in the Auth Flow Debugger.

curl

curl -X POST https://api2.freecustom.email/v1/inboxes \
  -H "Authorization: Bearer fce_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"inbox":"mytest@ditapi.info", "isTesting": true}'

Responses

201Inbox registered

json

{
  "success": true,
  "data": {
    "inbox": "mytest@ditapi.info",
    "registered_at": "2026-03-04T10:00:00.000Z"
  }
}

400Missing inbox

json

{
  "success": false,
  "error": "missing_field",
  "message": "inbox is required."
}

400Invalid email format

json

{
  "success": false,
  "error": "invalid_inbox",
  "message": "\"not-an-email\" is not a valid email address."
}

403Custom domain requires upgrade

json

{
  "success": false,
  "error": "plan_restriction",
  "message": "Custom domain inboxes require the Growth plan or higher.",
  "upgrade_url": "https://freecustom.email/api/pricing"
}

409Already registered

json

{
  "success": false,
  "error": "already_registered",
  "message": "mytest@ditapi.info is already registered to this account."
}

POST /v1/inboxes/{inbox}/tests

Marks the start of a testing boundary for this inbox. Useful in test suites (Playwright, Cypress, Selenium) to group timeline events together under a single test run ID. Logs a test_started event in the Timeline.

Field	Type	Required	Description
test_id	string	No	Optional custom test ID. If omitted, one will be generated automatically.

curl

curl -X POST https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/tests \
  -H "Authorization: Bearer fce_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"test_id":"e2e-signup-1"}'

Responses

200Test started

json

{
  "success": true,
  "data": {
    "test_id": "e2e-signup-1",
    "inbox": "mytest@ditapi.info",
    "started_at": "2026-03-04T10:05:00.000Z"
  }
}

GET /v1/inboxes/{inbox}/timeline

Returns the timeline history for a specific inbox. This shows the test run history and event sequence for debugging failed tests. If the inbox was registered with isTesting: true, zero-latency early timeline events like smtp_rcpt_received will be tracked.

Field	Type	Required	Description
test_id	string	No	Optional test ID to filter the timeline events by a specific test run.

curl

curl "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/timeline?test_id=e2e-signup-1" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200Success

json

{
  "success": true,
  "data": {
    "inbox": "mytest@ditapi.info",
    "events": [
      { "id": "evt_1", "type": "test_started", "timestamp": 1714152000000, "test_run_id": "e2e-signup-1" },
      { "id": "evt_2", "type": "smtp_rcpt_received", "timestamp": 1714152000500, "latency_ms": 500, "test_run_id": "e2e-signup-1" },
      { "id": "evt_3", "type": "email_received", "timestamp": 1714152001000, "latency_ms": 1000, "test_run_id": "e2e-signup-1", "metadata": { "subject": "Verify your email" } },
      { "id": "evt_4", "type": "otp_extracted", "timestamp": 1714152001200, "latency_ms": 200, "test_run_id": "e2e-signup-1", "metadata": { "otp": "123456", "score": 0.99 } }
    ],
    "duration_hours": 24,
    "event_count": 4
  }
}

GET /v1/inboxes/{inbox}/insights

Returns automated failure insights for a specific inbox. This analyzes the inbox activity and detects common issues with test flows.

curl

curl "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/insights" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200Success

json

{
  "success": true,
  "data": {
    "inbox": "mytest@ditapi.info",
    "insights": [
      { "type": "slow_delivery", "message": "Email took >3s" },
      { "type": "multiple_detected", "message": "Multiple emails detected" }
    ],
    "analyzed_at": "2026-03-04T10:05:00.000Z"
  }
}

DELETE /v1/inboxes/{inbox}

Unregisters the inbox. Path inbox must be URL-encoded (e.g. test%40freecustom.email).

curl

curl -X DELETE "https://api2.freecustom.email/v1/inboxes/mytest%40ditapi.info" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200Unregistered

json

{
  "success": true,
  "message": "mytest@ditapi.info has been unregistered."
}

404Not registered

json

{
  "success": false,
  "error": "not_found",
  "message": "mytest@ditapi.info is not registered on this account."
}