API guide

chobitmail’s HTTP API lets you automate tests that involve email addresses.

An OpenAPI definition is also available — use it to generate clients when you need to.

• Full API reference: https://chobitmail.com/api/docs
• OpenAPI JSON: https://chobitmail.com/api/openapi.json

Basics

Create API keys in the dashboard. You can issue up to 2 keys per team, and disable, re-enable, or delete them from the dashboard as well.

Common flow

1. Create a one-time address with POST /api/inboxes
2. In your test, send email to that one-time address
3. Wait for delivery with GET /api/inboxes/{id}/messages/wait
4. Use OTP codes or URLs from the response JSON
5. When the test finishes, delete the address with DELETE /api/inboxes/{id}

KEY=$CHOBITMAIL_API_KEY
BASE=https://chobitmail.com

curl -s -X POST $BASE/api/inboxes -H "Authorization: Bearer $KEY"
# => {"id":"...","address":"...@chobitmail.com",...}

curl -s "$BASE/api/inboxes/<id>/messages/wait?timeout=25" \
  -H "Authorization: Bearer $KEY"
# => {"message":{"codes":["123456"],"links":["https://..."],...}}

Endpoint overview

Detailed request/response schemas live in OpenAPI. This section only describes purpose.

Waiting (messages/wait)

Waits until a matching message arrives, then returns it. If one is already present, it returns immediately.

Common query parameters (all optional):

Response:

408 is not a hard failure; it means “not yet.” Reconnect until your overall test timeout. Multiple filters are AND. Messages that don’t match are stored only and do not resolve the wait.

ttl on create

Values outside the plan range are clamped.

Message object

Main fields on the message JSON returned by list and wait.

links and codes are extracted server-side. Use links for confirmation URLs and codes for OTPs as-is.

Reading errors

404 does not distinguish the three cases so other tenants’ IDs cannot be probed. In tests, the usual cause of 404 is TTL expiry.

Free-tier reference

Values may change. For current limits, use GET /api/usage and Sender domain verification.

Other limits: up to 50 messages stored per inbox, max email size 1MB, attachment bodies not stored.

Node.js wait helper example

const BASE = "https://chobitmail.com";
const KEY = process.env.CHOBITMAIL_API_KEY;
const AUTH = { Authorization: `Bearer ${KEY}` };

async function createInbox(ttl = 600) {
  const res = await fetch(`${BASE}/api/inboxes`, {
    method: "POST",
    headers: { ...AUTH, "Content-Type": "application/json" },
    body: JSON.stringify({ ttl }),
  });
  return res.json();
}

async function waitForMessage(inboxId, params = {}, maxWaitMs = 120_000) {
  const query = new URLSearchParams({ timeout: "25", ...params });
  const deadline = Date.now() + maxWaitMs;
  while (Date.now() < deadline) {
    const res = await fetch(
      `${BASE}/api/inboxes/${inboxId}/messages/wait?${query}`,
      { headers: AUTH },
    );
    if (res.status === 200) return (await res.json()).message;
    if (res.status !== 408) throw new Error(`unexpected: ${res.status}`);
  }
  throw new Error("message did not arrive");
}

If you use Playwright, prefer @chobitmail/playwright instead of writing the above yourself (guide currently Japanese).