APIリファレンス

概要

メールボックスが作成されることはありません — アドレス宛にメッセージが届いた瞬間に 存在し、5 日後に消えます。登録するものは何もないため、公開ドメインでは API にユーザー、プロジェクト、トークンという概念がありません。

• レスポンスはエラーを含め、すべてJSONです。
• 時刻はすべてRFC 3339形式のUTCです — 2026-08-04T18:31:07Z。
• メッセージIDは不透明な文字列です。解析しないでください。
• 受信専用。メールを送信するエンドポイントは意図的に存在しません。

ベースURL

HTTPS のみです。平文の HTTP はリダイレクトされます。バージョンはパスに含まれており、 v1 の形は今後も変わりません — 破壊的変更があれば新しい番号が 割り当てられます。

認証: 不要

公開ドメインでは何もありません。アドレスを知っている人は誰でも、 ウェブサイトと同様に API からもそのメールボックスを読めます。それが共有の使い捨て サービスというものの取り決めであり、大切なものを公開アドレスに紐づけてはいけません。

こちらに向けたドメインも、同じエンドポイントで応答します。キーも不要です。MXを当方に向ければ、最初のメッセージがそのドメインを接続します。詳しくはドメインの接続をご覧ください。そのメールボックスは、公開ドメインとまったく同様に、アドレスを知っている人なら誰でも読めます。

この API における唯一の認証情報は、以下で説明するアカウントのキーです。無料アカウントでは1つ、有料プランではそれ以上持てます。キー自体には等級がありません。呼び出しのたびに、その時点のアカウントのプランで判断されるため、同じキーが登録した瞬間に無料の上限から外れてプレミアムプールを開き、プランが終わると無料の利用枠に戻ります。公開ドメインにキーは不要です。一緒に送ると、呼び出しは IP アドレスではなくアカウント単位で数えられます。送られたキーが不明か失効している場合、ドメインを問わずどのエンドポイントでも 401 と unauthorized が返ります——そのため入力ミスは、空に見えるメールボックスとしてではなく、その場ですぐに分かります。

プレミアムドメイン

上記のルールの唯一の例外です。 公開ドメインは 使い捨てメールのブロックリストに載っているため、登録フォームが そのアドレスを拒否することがあります。有料プランでは次のプールを利用できます: 非公開の .com ドメイン 97 件（これらのリストには載っていません）。

API は何も変わりません。同じパス、同じパラメータ、同じレスポンス形式です。違いはヘッダー1つだけ。プレミアムアドレスは Authorization: Bearer gm_live_…、つまりあなたのAPIキーで発行したキーで読み取ります。有料プランのキーがなければ、同じリクエストは 404 を返します——これは当方がホストしていないドメインへの応答と一字一句同じです。名前を推測してプールを列挙できないよう、あえてそうしています。受信箱が返ることは決してありません。

プールのドメインはどこにあるか

GET /api/v1/domains にキーを付けて呼び出すと、公開ドメインとプールのドメイン名が返ります。キーなし、または無料または失効したアカウントのキーで同じ呼び出しを行うと、公開ドメイン、プールが保有するドメイン数、その料金は返りますが、名前だけは絶対に返しません。それらを使い捨てメールのブロックリストから外しておくことこそ、プランが買うものです。ログイン済みの契約者は、ホームページのドメイン選択でもプールを見られます。

curl -s https://grabmail.io/api/v1/domains \
  -H "Authorization: Bearer gm_live_…"

{
  "public": ["grabmail.io", "mixozia.com", "linqmail.com"],
  "premium": {
    "count": 97,
    "unlocked": true,
    "domains": ["one-of-the-pool.com", "another-of-the-pool.com", "…"]
  }
}

キーを確認する

GET /api/v1/me は、キーだけを判定する唯一の呼び出しです。200 ならプラン、現在の期間、消費済みと残りの割り当て、保持しているアドレス、レート制限が返り、キーが不明か失効していれば 401 unauthorized が返ります。プール側の呼び出しが 404 を返したときは、まずこれを呼んでください。あの応答はキーの問題をあえて隠しますが、こちらは隠さず示します。

curl -s https://grabmail.io/api/v1/me \
  -H "Authorization: Bearer gm_live_…"

{
  "plan": "premium",
  "status": "active",
  "premium": true,
  "period": { "start": "2026-09-14T00:00:00Z", "end": "2026-10-14T00:00:00Z" },
  "usage": { "messages": 12, "addresses": 5, "consumed": 12, "quota": 2000, "left": 1988, "over": false },
  "addresses_held": 5,
  "limits": { "requests_per_second": 2, "requests_per_minute": null, "requests_per_day": null, "api_keys": 1, "address_cap": null },
  "pool": { "count": 97, "access": true, "domains": "GET https://grabmail.io/api/v1/domains" }
}

プールは何を返すか

すべてのケースと、その理由です。最初の2つは、理由を読むまで意外に感じられるはずです。

404

unknown_domain — キーがないか、無料または失効したアカウントのキーです。当方がホストしていないドメインへの応答とあえて同一にしています。両者を見分けられると、名前を推測してプールを列挙できてしまうからです。キーは /api/v1/me で確認してください。

401

unauthorized — 送られたキーが不明か失効しています。ドメインを問わずどのエンドポイントでも返され、キーについて何かを示すものであって、ドメインについて示すものでは決してありません。

402

quota_reached — 今期の割り当てを使い切っており、超過分の利用はオフです。overage_cap / overage_funds — 超過分の利用はオンですが、設定した上限に達しているか、残高が不足しています。すでに保持しているアドレスは、いずれの場合も動作を続けます。

403

address_taken — そのアドレスは別の契約者が保持しています。別の名前を選んでください。

409

address_limit — アドレス数に上限を設けるプラン向けに予約されています。現時点でそのようなプランはありません。

429

rate_limited — 無料プラン（キーなし、または無料キー）で毎分 60 リクエストを超えた場合、または同じアドレスを一秒に一回より多く読み取った場合。有料キーでは、同じアドレスを毎秒2、3または5回より多く読み取った場合。daily_limit_reached — その日の無料リクエスト 1,000 件を使い切った場合。有料プランには毎分の上限も一日の上限もありません。どちらにも Retry-After が付きます。

保持されるアドレスと割り当て

プレミアムアドレスは、有効なキーで最初に読み取ったアカウントに保持されます——エンドポイントを問わずどんな読み取りでも、あるいは MCP 経由でもよく、事前に確保しておく必要はありません。保持されている間はそのアカウントだけが読み取れ、ほかのアカウントは 403 になります。ダッシュボードから手放すか、プランが終了するまで保持は続きます——終了日に、猶予期間なしで。

割り当てが数えるのはユニットです。プレミアムアドレスに届いたメッセージ、または新しく開いたプレミアムアドレス、どちらか先に達したほうを1つと数えます——つまり開いたきり一度も読まないアドレスでも1ユニット消費します。すでに保持しているアドレスを再度読むのは無料です。アカウントが保持できるアドレス数にプランによる上限はなく、割り当てだけがその歯止めになります。残りは /api/v1/me で確認できます。

プレミアムアドレスでも使えるエイリアス

どのメールボックス一覧にも alias が付いています。同じメールボックスに配送されつつ、そのメールボックスについて何も明かさない第二のアドレスです。このエイリアスをフォームに渡してアドレスをポーリングしてください。エイリアスを持つ人が見るのは、常に空のメールボックスです。特定のアドレスに対して常に同じ値で、無料であり、プレミアムアドレスでも公開アドレスとまったく同様に返されます。そのドメインは当方のものの1つで、あえてどこにも一覧掲載していません。

4回の呼び出しで全体を

KEY="gm_live_…"   # 有料プランの場合、APIキーのページから
# 1. キーを確認: プラン、残りの割り当て、レート制限。不正なら401。
curl -s https://grabmail.io/api/v1/me -H "Authorization: Bearer $KEY"

# 2. プールを一覧表示。名前が応答に含まれるのは有料キーのときだけ。
curl -s https://grabmail.io/api/v1/domains -H "Authorization: Bearer $KEY"

# 3. そのうちの1つのメールボックスを読み取り。最初の読み取りでアドレスが保持され、1ユニットとして数えられます。
curl -sG https://grabmail.io/api/v1/mailbox -H "Authorization: Bearer $KEY" \
  --data-urlencode "address=a7f3k2@one-of-the-pool.com"

# 4. メッセージを1件読み取り、ヘッダーは同じ。
curl -sG https://grabmail.io/api/v1/message/MESSAGE_ID -H "Authorization: Bearer $KEY" \
  --data-urlencode "mailbox=a7f3k2@one-of-the-pool.com"

公開ドメインとご自身のドメインは、無料プランを含むすべてのプランで、無料・キー不要・無制限のままです。割り当てが数えるのはプレミアムプールだけで、それ以外は数えません。プランと料金はプラン一覧にあります。

エンドポイント

$ curl -G https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=k7fq2m@grabmail.io"

{
  "address": "k7fq2m@grabmail.io",
  "alias": "hq8kd2m4p7zt@alias-domain.example",
  "count": 1,
  "next": null,
  "messages": [
    {
      "id": "01JR8W2K4Q",
      "from": "no-reply@example.com",
      "subject": "Your verification code",
      "date": "2026-08-04T18:31:07Z",
      "seen": false,
      "attachments": 0,
      "expires_at": "2026-08-09T18:31:07Z"
    }
  ]
}

$ curl -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "id": "01JR8W2K4Q",
  "from": "no-reply@example.com",
  "to": "k7fq2m@grabmail.io",
  "subject": "Your verification code",
  "date": "2026-08-04T18:31:07Z",
  "text": "Your code is 481920. It expires in 10 minutes.",
  "html": null,
  "attachments": []
}

$ curl -X DELETE -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "deleted": true,
  "id": "01JR8W2K4Q"
}

添付ファイル

すべてのメッセージに、そのまま使える URL 付きの添付ファイル一覧があります。 メッセージ本体と同じ認可情報で取得します。

GET /api/v1/attachment/{id}?mailbox={address}

送信者がどのように指定していても、常にContent-Disposition: attachment を付けてapplication/octet-streamを返します。これは意図的な仕様です。 見知らぬ相手のtext/htmlをそのまま返すと、添付ファイルがこのオリジン上の ページとして実行されかねません。実際の種類はメッセージの JSON にあり、 そこでは指示ではなくデータとして扱われます。

エラー

すべてのエラーは同じ2つのフィールドを持つ JSON で返るため、クライアント側は 1か所で処理できます。ステータスがカテゴリを表し、error は安定した 機械可読なスラッグ、message は人間向けで、いつ言い回しが変わっても 構いません。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":   "invalid_address",
  "message": "address must look like name@domain"
}

message で分岐しないでください。使われるスラッグは invalid_address、bad_cursor、unknown_domain、not_found、rate_limited、daily_limit_reached、unauthorized、そしてプレミアムプールに限り quota_reached、overage_cap、overage_funds、address_taken、address_limit です。

一部のエラーには、この二つのフィールド以外の情報も含まれます。何をすべきかを示す hint、ドキュメントへの docs リンク、404 と 429 では、プールの料金と使えるようにする方法を記した premium_pool ブロック、そして無料枠の上限による 429 では、有料プランなら何の制限が外れるかを示す upgrade ブロックです——誰かの代わりに本文を読むアシスタントが、諦めるのではなくその選択肢を伝えられるように書かれています。

レート制限

無料・キーなしなら、IPアドレスごとに毎分 60 リクエスト、一日 1,000 リクエストまで。メールボックスへの呼び出しはすべて数えられます。一覧の取得、メッセージの読み取り、そのHTML本文、添付ファイル、削除のいずれも対象で、MCPツールの呼び出しも同様です。一日のカウントは 00:00 UTC にリセットされます。

無料APIキーを使うと、同じ利用枠がIPアドレスではなくアカウントに紐づきます。CIランナーのように、呼び出し元のアドレスが変わる場合に便利です。無料アカウントのキーは1つで、そのキーで読み取った受信箱はあなたの受信箱に表示されます。 無料キーを作成

その範囲内で、読み取りはアドレスごとに一秒に一回です。メールボックスを一秒に一回ポーリングする、それが想定されたリズムです。

有料プランには、毎分の上限も一日の上限もありません。有料プランのキーを Authorization: Bearer として送れば、残るのはプランごとのアドレスあたりの速度だけです——毎秒2、3または5リクエストで、すべてのドメインに適用され、アカウントごとに数えられます。Premiumは月 $12.99 からです。 プランを見る

このサイトの受信箱は、無料APIの枠を消費しません。ページを開いたままにしておけば、必要なあいだずっとメールの到着を確認し続けます。

上限を超えると Retry-After ヘッダー付きの 429 が返ります。値は秒単位の整数です。毎分の上限またはアドレスごとの上限なら rate_limited、一日の上限なら daily_limit_reached で、後者の場合は UTC で日付が変わるまでの残り時間が入ります。無料のレスポンスには、現在の残りが毎回含まれます——その分の残りは X-RateLimit-Remaining、その日の残りは X-RateLimit-Daily-Remaining です。

保存期間

メッセージは届いてから5 日後に削除されます。既読か未読かは 関係ありません。すべてのメッセージにexpires_atが付くため、 その日付を自分で計算する必要はありません。

これは設定ではなく、固定された上限です — どのパラメータを使っても延長できません。 メッセージをこの期間より長く残す必要があるなら、取得して自分側に保存してください。

独自ドメイン

MXをsmtp.grabmail.ioに向ければ、ドメイン上のすべてのアドレスが同じエンドポイントを通じて応答します — 覚えるべき2つ目のAPIはなく、登録もキーも不要です。

ドメインを接続 →