クイックスタート

何もない状態からHTTPでメッセージを読み返すまで、4つのコマンドで完了します。アカウントもキーもSDKも不要です。

1. アドレスを選ぶ

弊社の公開ドメインであれば、どの名前でも構いません。呼び出すものも登録するものもなく、何かが配信された瞬間にそのアドレスは実在するものになります。

誰にも立ち寄られたくなければ、推測されにくい名前にしておいてください。公開ドメインでは、アドレスだけがメールボックスと世界とを隔てる唯一のものです。

シェル

$ ADDR="ci-$(openssl rand -hex 4)@grabmail.io"; echo "$ADDR"

2. 何かを送ってみる

サインアップフォーム、パスワードリセットのフロー、その他テストしたいものに使ってください。配信は通常数秒で完了します。

弊社のメールサーバーは最大5 MBまでのメッセージを受け付けます。それを超えるものは SMTP の時点で拒否されるため、送信者はその場で結果を知ることができます。

シェル

$ curl -sX POST https://your-app.example/signup --data-urlencode "email=$ADDR"

3. メールボックスをポーリング

1秒に1リクエストが想定されたリズムであり、制限されることはありません。空のメールボックスは404ではなくcount: 0を伴う200を返すため、ループ側で特別扱いする必要はありません。

このサンプルは無限に回り続けるのではなく1分で諦めます。これは CI で望ましい挙動です。

届くまでポーリングする

$ for i in $(seq 60); do
  ID=$(curl -sG https://grabmail.io/api/v1/mailbox --data-urlencode "address=$ADDR" | jq -r '.messages[0].id // empty')
  [ -n "$ID" ] && break
  sleep 1
done; echo "$ID"

4. 読んだら破棄する

メッセージを取得し、目的のものを取り出します — ここではプレーンテキスト部分から6桁のコードを取り出しています。

削除は任意です。5 日後にはすべて自然に消えます。それでも CI では削除しておくと、次の実行はきれいなメールボックスから始められます。

読み取りと削除

$ curl -sG https://grabmail.io/api/v1/message/$ID --data-urlencode "mailbox=$ADDR" \
  | jq -r .text | grep -oE '[0-9]{6}'

curl -sX DELETE -G https://grabmail.io/api/v1/message/$ID --data-urlencode "mailbox=$ADDR"

CIへの組み込み

実際のメールを読み取るテストスイートを不安定にしないための、2つの習慣があります。

実行ごとに新しいアドレス: ビルドIDやランダムな接尾辞から生成してください。実行のたびに同じアドレスを使い回すと、前日のメッセージが今日のアサーションを満たしてしまうことがあります。
再試行回数ではなく期限: 上記と同様、壁時計時間のタイムアウトに対してポーリングしてください。送信側が遅くなるほど、再試行回数は見えないところで増えていきます。
配信時間について保証しない: メールは同期的ではありません。特定の秒数以内に届くことではなく、届くこと自体を検証してください。
実際の用途に自分のドメインを使う: 公開メールボックスは、アドレスを知っている、あるいは推測した誰からでも読み取れます。使い捨てのサインアップには問題ありませんが、顧客データを扱うステージング環境には向きません。MXレコード1件で解決します。

AIエージェント向け：MCP

エージェントはこのページを読んで、必要なエンドポイントを選び、リクエストを書くことはできません。サーバーにどんなツールがあるかを尋ね、それを呼び出します。grabmail はまさにそのために、https://grabmail.io/mcp でModel Context Protocolサーバーを提供しています — キーもアカウントも不要です。

任意の MCP クライアントをこのエンドポイントに向けてください。Claude Desktop、Cursor、Continue、OpenAI Agents SDK はいずれもこの形式を読み取れます。

6つのツール: create_inbox、list_domains、list_messages、read_message、delete_message、wait_for_message。

mcp.json

$ {"mcpServers":{"grabmail":{"url":"https://grabmail.io/mcp"}}}

wait_for_message が最も重要です。エージェントが使い捨てのメールボックスを欲しがる理由は、ほぼ常に次のステップへ進む前に立ちはだかる確認コードです。トークンを消費するループでポーリングする代わりに、アドレスを要求し、フォームを送信し、メールが届くまでブロックします。

最大25秒待機し、送信者・件名・本文を含むメッセージ全体を返します。タイムアウトした場合はその旨を返すので、エージェントは単純にもう一度呼び出せます。

特定のメッセージを待つこともできます。subject_contains またはfrom_containsを渡せば、それ以外に届いたものは無視されます。

MCP · wait_for_message

$ curl -sX POST https://grabmail.io/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"wait_for_message","arguments":{"address":"you@grabmail.io","subject_contains":"code"}}}'

コード生成ツール向けにOpenAPI 3.1 spec(YAML)も、プレーンテキストで読みたい場合向けにllms.txtも用意されています。

APIリファレンス

すべてのパラメータ、すべてのステータスコード、エラーの形。

リファレンスを開く →

制限

何に上限があり、何にないか、上限に達すると何が起きるか。

制限を見る →

独自ドメイン

ドメイン上のすべてのメールボックスを、自分だけの非公開にできます。

設定方法を見る →