APIリファレンス

概要

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

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

ベースURL

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

認証

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

所有するドメインではメールボックスは非公開になるため、リクエストにはキーを付けます — これがメールボックスの所有を証明するものです。キーはドメインを確認する時に発行され、 一度だけ表示され、ここにはハッシュとしてのみ保存されます。

Authorization: Bearer <your key>

非公開ドメインでキーが間違っているか欠けている場合、unauthorized付きの 401が返ります。キーは一定時間で比較されるため、誤ったキーの拒否に かかる時間は、正しいキーの受理にかかる時間と同じです。

エンドポイント

$ 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 はなく、 メールボックスはキーを持つ本人だけが読めます。

ドメインを接続 →