API 利用ガイド

chobitmail の HTTP API は、テストごとにワンタイムメールアドレスを発行し、届いたメールの本文・OTP・確認リンクを JSON で返すためのものです。

エンドポイント定義・スキーマの正本は OpenAPI です。このページは日本語の利用ガイドです。

• インタラクティブ仕様: https://chobitmail.com/api/docs（英語）
• OpenAPI JSON: https://chobitmail.com/api/openapi.json

基本

API キーはダッシュボードで GitHub ログイン後に発行します。平文は発行直後に一度だけ表示されます。 キーはチームあたり最大 2 本まで並行発行でき、無効化・再有効化・削除もダッシュボードから行えます。 同じチームのキーなら同じ受信箱を作成・参照できます。クォータもチーム単位です。

典型フロー

1. POST /api/inboxes でワンタイムアドレスを作成する
2. テスト対象アプリにその address を使わせる
3. GET /api/inboxes/{id}/messages/wait で届くまで待つ
4. レスポンスの codes / links をテストに使う
5. （推奨）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://..."],...}}

エンドポイント概要

詳細なリクエスト／レスポンスは OpenAPI を正とします。ここでは用途だけ示します。

待受（messages/wait）

条件に合うメールが届くまで待って返します。すでに届いていれば即座に返します。

よく使うクエリ（すべて省略可）:

レスポンス:

408 は失敗ではなく「まだ無い」の合図です。テスト全体の上限時間まで再接続を繰り返す想定です。 複数条件は AND です。条件に合わないメールは保存だけされ、待受は解決しません。

作成時の ttl

プラン上限外の値は clamp されます。

Message オブジェクト

一覧・待受が返すメール JSON の主なフィールドです。

links と codes はサーバー側で抽出済みです。確認リンクは links、OTP は codes をそのまま使えます。

エラーの読み方

404 が 3 状態を区別しないのは、他テナントの ID 探索を防ぐためです。テストで 404 になる典型原因は TTL 切れです。

無料枠の目安

値は変更されることがあります。最新は GET /api/usage と送信元ドメイン検証を参照してください。

その他: 受信箱あたり保存 50 通、メールサイズ 1MB まで、添付本体は非保存。

Node.js での待受ヘルパー例

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("メールが届きませんでした");
}

Playwright を使う場合は、上記を自分で書かずに @chobitmail/playwright を推奨します。