# REST API

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

<a id="guide-content"></a>



<a id="set-up-a-client"></a>

## 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.

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

<a id="make-your-first-request"></a>

## Make your first request

The [curl quickstart](https://www.inboxspec.com/docs/markdown/first-email.md#first-email-bash) includes setup, inbox registration, a bounded wait and response handling. Keep the same terminal environment when continuing to body inspection and cleanup.

<a id="choose-your-language"></a>

## 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.

<a id="rest-javascript"></a>

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.

```javascript
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());
```

<a id="rest-python"></a>

Python

Save as list\_inboxes.py and run python3 list\_inboxes.py. Uses Python 3’s standard library.

```python
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))
```

<a id="rest-java"></a>

Java

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

```java
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());
  }
}
```

<a id="rest-curl"></a>

curl

Run in a Bash terminal with curl installed.

```bash
# 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](https://www.inboxspec.com/docs/markdown/first-email.md) next.

<a id="more-language-examples"></a>

### More languages and operations

The [interactive API reference](https://api.inboxspec.com/docs) 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](https://www.inboxspec.com/getting-started#javascript) 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](https://www.inboxspec.com/docs/markdown/first-email.md).

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](https://www.inboxspec.com/docs/markdown/cleanup.md) after your test senders and waits have finished.

<a id="schemas"></a>

## Request schemas

[Browse the API reference](https://api.inboxspec.com/docs) or download the [OpenAPI schema](https://api.inboxspec.com/openapi.json). [Error codes and remedies](https://api.inboxspec.com/docs/errors) explain failures separately from a successful wait that timed out.