Your first email

// Save as first-email.mjs. Requires Node.js 24+; no packages to install.
const apiUrl = process.env.INBOXSPEC_API_URL || "https://api.inboxspec.com";
const apiKey = process.env.INBOXSPEC_API_KEY;
if (!apiKey) throw new Error("Set INBOXSPEC_API_KEY to your project API key first.");

async function request(path, body) {
  const response = await fetch(new URL(path, apiUrl), {
    method: body === undefined ? "GET" : "POST",
    headers: { Authorization: "Bearer " + apiKey, "Content-Type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(70_000),
  });
  if (!response.ok) {
    // An HTTP error is different from a successful wait that found no email.
    const problem = await response.json().catch(() => null);
    throw Object.assign(new Error("HTTP " + response.status + ": check the API error reference before retrying."), {
      code: problem?.error?.code,
    });
  }
  return response;
}

const runId = "first-" + crypto.randomUUID();
const inbox = await (await request("/v1/inboxes/for-run", {
  run_id: runId, retention_seconds: 600,
})).json();
if (typeof inbox.address !== "string") throw new Error("No inbox address returned.");
console.log("Run ID:", runId);
console.log("Send a test email containing 'Your code is 123456' to: " + inbox.address);
console.log("Waiting up to 60 seconds…");
const result = await (await request("/v1/messages/wait", {
  inbox: inbox.address, match: { has_code: true }, timeout_ms: 60_000,
})).json();
if (result.status === "timeout") {
  console.log("No matching email. Check the address and your sender, then try a new run.");
  console.log({ reason: result.reason, arrivals: result.non_matching_arrivals, hint: result.hint });
  process.exitCode = 1;
} else if (result.status === "matched" && typeof result.message?.id === "string") {
  console.log("Code candidates:", result.message.codes);
  const bodyPath = "/v1/messages/" + encodeURIComponent(result.message.id) + "/body?format=";
  let body;
  try {
    body = await request(bodyPath + "text");
  } catch (error) {
    if (error.code !== "unsupported_format") throw error;
    console.log("This email is HTML-only. Email HTML:");
    body = await request(bodyPath + "html");
  }
  console.log(await body.text());
} else {
  throw new Error("Unexpected wait response. Check the API error reference.");
}
// Messages expire after ten minutes; the inbox remains until explicitly deleted. Accepted messages still count toward usage.

node first-email.mjs

import json
import os
import sys
import uuid
from urllib.request import Request, urlopen
from urllib.error import HTTPError
from urllib.parse import quote

origin = os.environ.get("INBOXSPEC_API_URL", "https://api.inboxspec.com")
key = os.environ["INBOXSPEC_API_KEY"]

def request(path, body=None):
    data = None if body is None else json.dumps(body).encode()
    req = Request(origin + path, data=data, headers={
        "Authorization": "Bearer " + key,
        "Content-Type": "application/json",
    })
    # Longer than the server's 60-second wait; HTTP errors remain errors.
    with urlopen(req, timeout=70) as response:
        return response.read().decode()

run_id = "first-" + str(uuid.uuid4())
inbox = json.loads(request("/v1/inboxes/for-run", {
    "run_id": run_id, "retention_seconds": 600,
}))
print("Run ID:", run_id)
print("Send 'Your code is 123456' to:", inbox["address"], flush=True)
result = json.loads(request("/v1/messages/wait", {
    "inbox": inbox["address"], "match": {"has_code": True}, "timeout_ms": 60000,
}))
if result["status"] == "timeout":
    print("No matching email. Check the address and sender.")
    print(result)
    sys.exit(1)
if result["status"] != "matched" or not isinstance(result.get("message", {}).get("id"), str):
    raise ValueError("Unexpected wait response")

print("Code candidates:", result["message"].get("codes", []))
path = "/v1/messages/" + quote(result["message"]["id"], safe="") + "/body?format="
try:
    body = request(path + "text")
except HTTPError as error:
    problem = json.loads(error.read())
    if problem.get("error", {}).get("code") != "unsupported_format":
        raise
    print("This email is HTML-only. Email HTML:")
    body = request(path + "html")
print(body)
# Messages expire after ten minutes; delete this run's inbox when finished.

python3 first_email.py

import com.google.gson.*;
import java.net.*;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.*;

class FirstEmail {
  static final Gson JSON = new Gson();
  static final String ORIGIN = Optional.ofNullable(System.getenv("INBOXSPEC_API_URL"))
      .orElse("https://api.inboxspec.com");
  static final String KEY = System.getenv("INBOXSPEC_API_KEY");
  static final HttpClient CLIENT = HttpClient.newBuilder()
      .connectTimeout(Duration.ofSeconds(10)).build();

  static class ApiError extends Exception {
    final String code;
    ApiError(int status, String code) { super("HTTP " + status); this.code = code; }
  }

  static String request(String path, Object body) throws Exception {
    var builder = HttpRequest.newBuilder(URI.create(ORIGIN + path))
        .header("Authorization", "Bearer " + KEY)
        .header("Content-Type", "application/json")
        .timeout(Duration.ofSeconds(70));
    if (body == null) builder.GET();
    else builder.POST(HttpRequest.BodyPublishers.ofString(JSON.toJson(body)));
    var response = CLIENT.send(builder.build(), HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() < 200 || response.statusCode() >= 300) {
      String code = "";
      try { code = JsonParser.parseString(response.body()).getAsJsonObject()
          .getAsJsonObject("error").get("code").getAsString(); }
      catch (RuntimeException ignored) { }
      throw new ApiError(response.statusCode(), code);
    }
    return response.body();
  }

  public static void main(String[] args) throws Exception {
    if (KEY == null || KEY.isBlank()) throw new IllegalStateException("Set INBOXSPEC_API_KEY first");
    String runId = "first-" + UUID.randomUUID();
    var inbox = JsonParser.parseString(request("/v1/inboxes/for-run",
        Map.of("run_id", runId, "retention_seconds", 600))).getAsJsonObject();
    String address = inbox.get("address").getAsString();
    System.out.println("Run ID: " + runId);
    System.out.println("Send 'Your code is 123456' to: " + address);
    var result = JsonParser.parseString(request("/v1/messages/wait", Map.of(
        "inbox", address, "match", Map.of("has_code", true), "timeout_ms", 60000))).getAsJsonObject();
    String status = result.get("status").getAsString();
    if (status.equals("timeout")) {
      System.out.println("No matching email. Check the address and sender.");
      System.out.println(result);
      System.exit(1);
    }
    if (!status.equals("matched")) throw new IllegalStateException("Unexpected wait response");
    var message = result.getAsJsonObject("message");
    System.out.println("Code candidates: " + message.get("codes"));
    String id = URLEncoder.encode(message.get("id").getAsString(), StandardCharsets.UTF_8);
    String path = "/v1/messages/" + id + "/body?format=";
    String body;
    try { body = request(path + "text", null); }
    catch (ApiError error) {
      if (!error.code.equals("unsupported_format")) throw error;
      System.out.println("This email is HTML-only. Email HTML:");
      body = request(path + "html", null);
    }
    System.out.println(body);
    // Messages expire after ten minutes; delete this run's inbox when finished.
  }
}

curl --fail --location --output gson-2.14.0.jar \
  https://repo.maven.apache.org/maven2/com/google/code/gson/gson/2.14.0/gson-2.14.0.jar
java --class-path gson-2.14.0.jar FirstEmail.java