Developer tools

REST API

Choose JavaScript, Python, Go, Java, C#, PHP or curl examples for the hosted API.

Set up a client

REST works directly with your project key and the API address below. SDK and CLI archives are available in the private Clients 0.1.0 release. npm registry publication is pending. The SDK supports Node.js 24+ or Bun 1.4+; the CLI needs Bun 1.4+ on Linux or macOS.

export INBOXSPEC_API_URL='https://api.inboxspec.com'
# Set INBOXSPEC_API_KEY to your saved project key in this terminal.

Make your first request

The curl quickstart includes setup, inbox registration, a bounded wait and response handling. Keep the same terminal environment when continuing to body inspection and cleanup.

Choose your language

These examples make the same read-only request: list inboxes in your project. Set INBOXSPEC_API_KEY in your environment to a project key with inbox read permission. Optionally set INBOXSPEC_API_URL to your API origin without a trailing slash. Run these on your server or development machine; keep credentials out of source control.

JavaScript / TypeScript

Save as list-inboxes.mjs and run node list-inboxes.mjs with Node.js 24+. The same code works in a server-side TypeScript module.

const origin = process.env.INBOXSPEC_API_URL || "https://api.inboxspec.com";
const key = process.env.INBOXSPEC_API_KEY;
if (!key) throw new Error("Set INBOXSPEC_API_KEY first");
const response = await fetch(origin + "/v1/inboxes", {
  headers: { Authorization: "Bearer " + key },
  signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error("HTTP " + response.status);
console.log(await response.json());

Python

Save as list_inboxes.py and run python3 list_inboxes.py. Uses Python 3’s standard library.

import json
import os
import urllib.request

origin = os.environ.get("INBOXSPEC_API_URL", "https://api.inboxspec.com")
key = os.environ["INBOXSPEC_API_KEY"]
request = urllib.request.Request(
    origin + "/v1/inboxes",
    headers={"Authorization": "Bearer " + key},
)
# HTTP errors raise HTTPError; they are not an empty inbox list.
with urllib.request.urlopen(request, timeout=10) as response:
    print(json.load(response))

Java

Save as ListInboxes.java and run java ListInboxes.java with Java 17+. Uses the standard HTTP client.

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

class ListInboxes {
  public static void main(String[] args) throws Exception {
    String origin = System.getenv("INBOXSPEC_API_URL");
    if (origin == null) origin = "https://api.inboxspec.com";
    String key = System.getenv("INBOXSPEC_API_KEY");
    if (key == null || key.isBlank())
      throw new IllegalStateException("Set INBOXSPEC_API_KEY first");
    var client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();
    var request = HttpRequest.newBuilder(URI.create(origin + "/v1/inboxes"))
        .header("Authorization", "Bearer " + key)
        .timeout(Duration.ofSeconds(10)).GET().build();
    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() < 200 || response.statusCode() >= 300)
      throw new IllegalStateException("HTTP " + response.statusCode());
    System.out.println(response.body());
  }
}

curl

Run in a Bash terminal with curl installed.

# Set INBOXSPEC_API_KEY in this terminal first.
: "${INBOXSPEC_API_KEY:?Set your project key first}"
curl --fail-with-body --silent --show-error --max-time 10 \
  "${INBOXSPEC_API_URL:-https://api.inboxspec.com}/v1/inboxes" \
  -H "Authorization: Bearer $INBOXSPEC_API_KEY"

A successful response contains this project’s inbox list, which may be empty. These examples stop on an HTTP error. They do not create an inbox or send mail; follow the first-email workflow next.

More languages and operations

The interactive API reference generates examples from the same OpenAPI schema as the API. In Client Libraries, select a language; use More to see all clients. Each operation also has a language selector above its request example.

JavaScript / TypeScript: choose Node.js → Fetch for server-side code. The JavaScript quickstart shows the complete inbox, wait and body flow.
Python: choose Requests, HTTPX or http.client.
Go: choose NewRequest.
Java: choose java.net.http or OkHttp.
C#: choose HttpClient.
PHP: choose cURL, Guzzle or Laravel HTTP Client.
Ruby: choose net::http.
curl: choose Shell → Curl, or follow the step-by-step quickstart.

These are HTTP client examples; install any third-party library you select. Keep project keys in your server-side environment or secret store, never browser code. Register an inbox before waiting, allow more time in your HTTP client than the requested wait, and check status before reading a matched message. Follow cleanup after your test senders and waits have finished.

Request schemas

Browse the API reference or download the OpenAPI schema. Error codes and remedies explain failures separately from a successful wait that timed out.