API 利用ガイド

chobitmailのHTTP APIを使うことでメールアドレスを使ったテストの自動化ができます。

また、OpenAPIの定義もあります。必要に応じてクライアントの生成などにお使いください。

• API詳細仕様書: https://chobitmail.com/api/docs
• OpenAPI JSON: https://chobitmail.com/api/openapi.json

基本

APIキーはダッシュボードで発行します。キーはチームあたり最大2個まで発行でき、無効化・再有効化・削除もダッシュボードから行えます。

よくある使い方

1. POST /api/inboxes でワンタイムアドレスを作成する
2. テストの中で、発行したワンタイムアドレスにメールを送信する
3. GET /api/inboxes/{id}/messages/wait で届くまで待つ
4. レスポンスJSONに含まれるOTPコードやURLを利用する
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/{inboxId}/messages/wait?timeout=25" \
  -H "Authorization: Bearer $KEY"
# => {"message":{"codes":["123456"],"links":["https://..."],...}}

エンドポイント概要

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

待受（messages/wait）

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

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

レスポンス:

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

作成時の ttl

秒単位。範囲は 60〜600（省略時 600＝10 分）。上限外の値は clamp されます。実効上限は GET /api/usage の ttl で確認できます。永続プランでは無視され、expiresAt は null です。

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 を推奨します。