APIリファレンス

概要

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

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

ベースURL

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

認証: 不要

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

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

唯一ヘッダーを使うケースがあります。要請により閉鎖したドメインは、Authorization: Bearer <key> を使って読み取ります。キーが誤っている、または指定されていない場合は401とともにunauthorizedが返されます。キーの比較には一定時間を要する方式を用いているため、誤ったキーの拒否にかかる時間は、正しいキーが受理されるまでの時間と変わりません。

プレミアムドメイン

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

API は何も変わりません。同じパス、同じパラメータ、同じレスポンス形式です。違いはヘッダー 1 つだけ。プレミアムアドレスは Authorization: Bearer gm_live_… と、あなたのAPIキー で発行した鍵で読み取ります。有効な鍵がなければ、同じリクエストが 402 または 403 を返します — 受信箱は返しません。

# A public domain: no header at all.
curl -sG https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=a7f3k2@grabmail.io"

# A premium domain: the same call, plus a key.
curl -sG https://grabmail.io/api/v1/mailbox \
  -H "Authorization: Bearer gm_live_…" \
  --data-urlencode "address=a7f3k2@one-of-the-pool.com"

公開ドメインとご自身のドメインは、無料プランを含むすべてのプランで、無料・鍵なし・無制限のままです。クォータはプレミアムプールに届いたメッセージだけを数えます。プランと料金は プラン一覧 にあります。

エンドポイント

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

{
  "address": "k7fq2m@grabmail.io",
  "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、unknown_domain、 not_found、rate_limited です。

レート制限

アドレスごとに1秒あたり1リクエスト。メールボックスを1秒に1回 ポーリングするのが想定された使い方で、制限されることはありません。

上限を超えると、秒数を示すRetry-After付きの429が 返ります。1日あたりのクォータや管理が必要なバーストクレジットはありません。

保存期間

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

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

独自ドメイン

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

ドメインを接続 →