コンテンツにスキップ
ドキュメント

キーワードを入力して、ガイド、API リファレンス、MCP server を検索できます。

REST API

Markdown で表示英語のページをプレーンテキストでClaude で開くこのページについて質問するChatGPT で開くこのページについて質問する

英語から自動翻訳されています。

英語で読む

ベース URL は https://api.proxymail.qa/v1 で、Authorization: Bearer qa_… を使います。すべてのエンドポイントは、OpenAPI の記述 から生成された REST API リファレンス に載っています。

JavaScript や TypeScript を使っていますか？ npm の proxymail-qa パッケージが、型付きでこれらの呼び出しをラップします。

クイックスタート

Section titled “クイックスタート”

  1. API キー を取得する

    Section titled “API キー を取得する”

    テスト対象のプロジェクトの API キー を使います。

  2. アドレスを作成する

    Section titled “アドレスを作成する”

    ペルソナとパスワード付きでアドレスを作成し、それを使ってアプリに登録します。

    curl -X POST https://api.proxymail.qa/v1/addresses \
      -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" -H "Content-Type: application/json" \
      -d '{"label": "Sign-up test", "persona": true, "password": true}'

  3. コードを待つ

    Section titled “コードを待つ”

    次にコードを待ちます。コードは自動的に返ってきます。

    curl "https://api.proxymail.qa/v1/addresses/k7f2x9ab12cd@mailclub.dev/code" \
      -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY"
    {
      "type": "code",
      "subtype": "otp",
      "value": "986512",
      "service": "Spotify",
      "received_at": "2026-10-12T10:00:03Z",
      "expires_at": "2026-10-12T10:10:03Z"
    }

エンドポイント

Section titled “エンドポイント”
メソッドとパス 機能
GET /v1/project キーのプロジェクト、そのメールドメインと上限
PATCH /v1/project プロジェクト設定と同様に、プロジェクトの name、website、environments、email_prefix、mail_domain を変更します。プロジェクトのリード、または組織のオーナーか管理者が必要です。各変更はアクティビティログに記録されます
POST /v1/project/dev-hosts localhost:3000 などのホストを開発環境（host）として指定し、メールチェックがそのホストへのリンクを通すようにします
POST /v1/addresses アドレスを作成します（label、name、persona、password、lifetime_days、domain、age または date_of_birth、country、使用場所：site と environment）
POST /v1/form-values 登録フォームの各フィールドに入力または選択する値。そのために作成した新しいアドレス、または以前に作成したアドレスから取得します（詳細）
GET /v1/addresses アドレスを新しい順に一覧表示するか、以前に作成したものを探します（tag、country、min_age、max_age、has_password、search、site、environment）
GET / PATCH / DELETE /v1/addresses/{address} 1 件を読み取る、更新する（first_name、last_name、username、date_of_birth、country、label、notes、tags）、または削除します
GET /v1/addresses/{address}/code コードを待ちます（timeout、service、since。unused=true は使用済みのコードを飛ばします。type=coupon はクーポンやプロモーションコード用で、割引と有効期限付き）
GET /v1/addresses/{address}/link リンクを待ちます（type：verify、magic_signin、invite、reset、any。配信停止リンク には unsubscribe または list_unsubscribe。モバイルアプリを開くリンクには app=true）
GET /v1/addresses/{address}/count 届いたメールを数えます（since、service、type：コードまたはリンク、subtype、category）。各メールは内容なしで要約されます
GET /v1/addresses/{address}/none メールが届かないことを確認します。最大 30 秒待機し（timeout）、何も届かなければ 200、何か届いた時点で 409 を返します。category=marketing はオファーとニュースレターだけを監視し、until は呼び出しをまたいで最大 1 時間ウィンドウを開いたままにします
GET, PUT /v1/addresses/{address}/consent Labs。 国ごとのマーケティングルールのために、アドレスが登録時に同意した内容（マーケティング、事前にチェックされたボックス、ダブルオプトイン）
POST /v1/addresses/{address}/coupon-result Labs。 チェックアウトでのクーポンの扱い（accepted、rejected、error、アプリのメッセージ付き）と coupon_result の判定
POST /v1/addresses/{address}/sequence Labs。 ウェルカムシリーズやドリップキャンペーン：since の後、各メールが順番どおり、時間どおりに届いたか
GET /v1/addresses/{address}/offers Labs。 送信者ごとのクーポンと、それぞれが届いたアドレスのバージョン（そのまま、大文字、+tag）。1 人が同じオファーを 2 回受け取った場合は reused
GET, POST, DELETE /v1/addresses/{address}/unsubscribed Labs。 配信停止の監視：POST はアドレスが送信者から配信停止したことを、DELETE は再登録したことを記録し、GET はその後に届いたマーケティングメールを一覧にします
GET /v1/addresses/{address}/checks メールを確認します：SPF、DKIM、DMARC、ローカルや素の http リンク、リンクの行き先（expect_host）、記載された有効期限、クーポンの終了日、プレーンテキストパート、サイズ、画像だけのメール、指定したフレーズ（expect_text）、言語（expect_language）、届くまでの時間（expect_within）、添付ファイル（expect_attachment）。判定のみを返します
GET /v1/addresses/{address}/messages コードとリンク付きのメール。include=text でテキスト、include=html で HTML、include=text,html で両方を追加します
GET /v1/addresses/{address}/variants 登録フォームのテスト用の、アドレスの珍しいバージョン：受信トレイに届くもの、届かないもの、無効なもの（詳細）
GET /v1/variants/names フォームの名前フィールド用の扱いにくい名前（field、max_length）：受け付けるべきもの、拒否すべきもの、テキストとして保存すべき HTML や SQL、アプリによって扱いが異なるもの（詳細）
GET /v1/variants/passwords フィールドのルール内の扱いにくいパスワード（min_length、max_length、symbols）：最小と最大、各記号クラス、スペース、非 ASCII、アプリによって扱いが異なるもの（詳細）
GET /v1/addresses/{address}/delivery アドレスを確認します：届いたもの、こちらで拒否したもの、Cloudflare のメールサーバーが拒否したものとその理由、ヒント
GET /v1/addresses/{address}/password 保存されたパスワード。読み取りを許可されたキー向け
POST /v1/addresses/sign-in サインインに使う保存済みテストアカウントとそのパスワードを 1 回の呼び出しで取得します（site、environment、tags）。パスワードの読み取りを許可されたキー向け（詳細）
PUT /v1/addresses/{address}/password テストアカウントが現在使っているパスワードを保存します（password。省略すると生成され、1 回だけ返されます）。どのキーでも保存できます
POST /v1/addresses/checkout プールからアカウントをチェックアウトします：フィルター（tags、country、min_age、max_age、has_password、search、site、environment）に一致し、他の誰も保持していないものを minutes の間（詳細）
POST /v1/addresses/{address}/extend, POST /v1/addresses/{address}/return 保持を延長するか、返却します（token。返却時に add_tags と remove_tags が状態を記録します）
POST /v1/runs 実行を開始します（name、source、meta）。Proxy-Mail-QA-Run ヘッダーでその ID を送る呼び出しは、確認した内容を追加します（詳細）
GET /v1/runs, GET /v1/runs/{id} 実行を一覧表示するか、証拠付きで 1 件を読み取ります。format=markdown でレポートを取得します
POST /v1/runs/{id}/notes, POST /v1/runs/{id}/tests, POST /v1/runs/{id}/finish 独自の行（text、failed）、テスト結果、合計を追加するか、終了します（failed）

Labs の付いたエンドポイントは、Labs 機能であるマーケティング・オファーメールの一部です。キーの作成者がアプリの Account settings → Labs でオンにします。それまでは、その旨を伝えるメッセージとともに 403 forbidden を返します。

クーポンとオファー

Section titled “クーポンとオファー”

オファーに登録した後、type=coupon でクーポンを待ちます（クーポンまたはサインインコードには any）。オファーは数分かかることが多いため、長めに待つか再度リクエストしてください。since を指定すると、after_seconds がそこからメールが届くまでの時間を示します。

curl "https://api.proxymail.qa/v1/addresses/$ADDRESS/code?type=coupon&since=$SIGNED_UP&timeout=30" -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY"
# { "value": "WELCOME20", "subtype": "coupon", "discount": "20% off", "valid_until": "2026-10-31", "after_seconds": 212, … }

discount はオファーの読み取り結果（20% off、$10 off、Free shipping、Buy one, get one）で、valid_until はメールに記載された終了日です（「10 月 31 日まで有効」「Oct 31 終了」「7 日間有効」など）。メールに記載がない場合、それぞれ null になります。種類を指定しない待機はクーポンを除外するため、サインインのテストでオファーのコードを拾うことはありません。時間どおりに届いたかを確認するには、GET /checks?since=$SIGNED_UP&expect_within=5m が遅れた場合に arrival_time を失敗にします。

オファーは 1 人 1 回。 name+promo1@… と NAME@… へのメールは同じ受信トレイに届くため、1 回限りのオファーやウェルカムオファーの「2 人目の顧客」として便利です。そのままのアドレスと GET /variants のバージョンで登録し、それぞれのクーポンを待ってから GET /v1/addresses/{address}/offers を実行します。送信者ごとに、クーポンとそれぞれが届いたバージョン（plain、capitals、または +tag）、2 つ以上のバージョンが受け取った場合は reused、1 つの共有コードだった場合は same_code を返します。オファーが再利用されていれば passed は false になり、最初以降の各クーポンは /checks で offer_reuse を失敗にします。Gmail のドットの手法はここではテストできません。これらのドメインでは、ドットを入れると別のアドレスになります。

チェックアウト時。 ステージング環境でテスト決済のみを使い、自分のツールでクーポンを適用してから、アプリの動作を記録します。

curl -X POST "https://api.proxymail.qa/v1/addresses/$ADDRESS/coupon-result" \
  -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" -H "Content-Type: application/json" \
  -d '{"result": "rejected", "code": "WELCOME20", "message": "Code already used", "one_time": true}'

result は accepted、rejected、error のいずれかです。code のデフォルトはアドレスの最新のクーポンです。すべての試行が保存され、応答の check は coupon_result の判定です。終了日以降に受け付けられたクーポン、アドレスの別バージョンにすでに提供されたオファーで受け付けられたクーポン、one_time の場合に 2 回受け付けられたクーポンは失敗になり、エラーや理由のない拒否には警告が出ます。実行中の場合、判定が失敗すると実行も失敗します。

サインアップフォーム用の値

Section titled “サインアップフォーム用の値”

フォームがメール以外の情報を求める場合、各フィールドについてページの記載を送ると、入力または選択する値が返ってきます。値はフォームのために作成した新しいアドレスから取得されます。フォームが求めれば生年月日（age を渡さない限り成人）、フォームのドロップダウンにある国（または country）、パスワードフィールドの min_length、max_length、pattern に合うパスワードが付きます。パスワードはアドレスに保存され、この応答にだけ表示されます。代わりに以前作成したアドレスを使うには address を渡します（保存済みパスワードは返されません）。

curl -s -X POST https://api.proxymail.qa/v1/form-values -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" \
  -H "Content-Type: application/json" -d '{
    "fields": [
      { "id": "email", "type": "email", "label": "Email" },
      { "id": "user", "name": "username", "label": "Username", "max_length": 15 },
      { "id": "pw", "type": "password", "label": "Password", "min_length": 12 },
      { "id": "dob", "type": "text", "label": "Date of birth", "placeholder": "DD/MM/YYYY" },
      { "id": "country", "type": "select", "label": "Country", "options": [{ "value": "de", "label": "Germany" }, { "value": "uk", "label": "United Kingdom" }] },
      { "id": "terms", "type": "checkbox", "label": "I agree to the terms" }
    ]
  }'
# { "address": "k7f2x9ab12cd@mailclub.dev", "created": true, "password": "…", "persona": {…},
#   "values": [ { "id": "email", "kind": "email", "value": "k7f2x9ab12cd@mailclub.dev" },
#               { "id": "dob", "kind": "date_of_birth", "value": "04/05/1990" },
#               { "id": "country", "kind": "country", "value": "uk" },
#               { "id": "terms", "kind": "other", "value": null, "note": "Not a sign-up detail Proxy Mail QA fills: fill it yourself, or leave it." }, … ] }

各フィールドには id（独自の値で、値とともに返されます）、type（または select）、name、label、placeholder、autocomplete、group（日・月・年のドロップダウンの上にある「生年月日」など、周囲のグループの記載）、pattern、min_length、max_length、options（value と label）を指定できます。日・月・年のフィールドにはそれぞれの部分が、日付ピッカーには YYYY-MM-DD が、入力式の日付にはラベルやプレースホルダーに記された形式が入ります（記載がなければ米国式の順序で note 区切り）。Proxy Mail QA はページを見たり入力したりしません。入力はあなたが行い、その後いつもどおりコードやリンクを待ちます。

アドレスのバリエーション

Section titled “アドレスのバリエーション”

API がアドレスを受け付ける場所では、バリエーションも使えます。大文字や、k7f2x9ab12cd+o'brien@mailclub.dev のようなプラスタグ（パスでは URL エンコード）です。操作はそのままのアドレスに対して行われ、+tag バリエーションに対する待機やメッセージ一覧は、そのバリエーション宛てのメールだけを見つけます。珍しいメールアドレス を参照してください。

名前とパスワード

Section titled “名前とパスワード”

フォームの他のフィールドも同じように扱えます。GET /v1/variants/names?field=first_name&max_length=50 は名前を 4 つのグループで一覧にします：accept（実在の人名：O'Brien、Smith-Jones、José、Straße、李、Мария、محمد、สมชาย、1 文字、ちょうど最大長）、reject（最大長より 1 文字多い、空、スペースのみ）、store_as_text（<b>Jane</b>、script タグ、SQL インジェクション、{{7*7}}：アプリは入力どおりに保存・表示し、決して実行してはいけません）、decide（数字、記号、絵文字、前後のスペース、合成済みと分解されたアクセント、最大長が指定されていない場合は 64、128、255 文字：アプリによって扱いが異なるため、アプリの動作を記録してください）。GET /v1/variants/passwords?min_length=8&max_length=64&symbols=true はパスワードについて同じことを行います：accept（ちょうど最小長と最大長、引用符・バックスラッシュ・スペースを含む各記号クラス、非 ASCII 文字）、reject と decide（数字のみ、小文字のみ、先頭や末尾のスペース、絵文字、最大長が許す場合は最初の 72 バイトが共通するペア。bcrypt はそこで処理を打ち切ります）。パスワードは呼び出しごとに新しく生成されます。各項目には tests（確認する内容）と value（入力する値）があります。珍しい名前とパスワード を参照してください。

生年月日

Section titled “生年月日”

"age": "under13"（または adult、over21、under18、under15、any、turns18tomorrow、turned18today）を追加すると、ペルソナにその範囲の生年月日が付きます。独自の値を "date_of_birth": "2012-05-01" として送ることもできます。persona.date_of_birth として YYYY-MM-DD 形式で返され、アドレスに生年月日がある場合にだけ含まれます。

テストアカウントをもう一度見つける

Section titled “テストアカウントをもう一度見つける”

GET /v1/addresses はフィルターを受け付けるため、テストやエージェントは新しく作らずに、以前作成したアカウントに戻れます。指定したフィルターはすべて一致する必要があります。

  • tag：繰り返すか、タグをカンマで区切ると、すべてに一致する必要があります
  • country：ペルソナの国（GB など）
  • min_age と max_age：ペルソナの生年月日から算出した今日時点の満年齢（max_age=17 で 18 歳未満を検索）。生年月日のないアドレスは一致しません
  • has_password：true または false。パスワードが保存されているか
  • search：アドレス、ラベル、メモ、名前、ユーザー名の一部
  • site と environment：使用場所。ホストまたはページの URL（site=staging.example.com）と名前（environment=staging）です。アドレス作成時に設定します。Chrome 拡張機能も記録し、アプリは各アカウントにこれを表示します
curl "https://api.proxymail.qa/v1/addresses?tag=age-gate&country=GB&max_age=17&has_password=true" \
  -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY"

テストアカウントで再度サインインする

Section titled “テストアカウントで再度サインインする”

POST /v1/addresses/sign-in は、Chrome 拡張機能のサインイン一覧と同様に、サインインに使う保存済みテストアカウントを選び、パスワードとともに返します。対象は、パスワードが保存され、指定したすべてのタグを持ち、どのテストもチェックアウトしていないアカウントです。この site で使われたものが優先され、次に最も最近メールを受け取ったものが選ばれます。site を指定すると、まだどこでも使われていないアカウントはそこで使用済みとして記録されます。保存済みパスワードの読み取りを許可されたキーが必要で、すべての表示はログに記録されます。該当するアカウントがない場合は 404 を返します。

curl -s -X POST https://api.proxymail.qa/v1/addresses/sign-in -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" \
  -H "Content-Type: application/json" -d '{"site": "staging.example.com", "tags": ["verified"]}'
# { "address": "…", "password": "…", "persona": {…}, "site": "staging.example.com", "used_on_site": true, … }

メール自体を確認する

Section titled “メール自体を確認する”

メールテンプレート（文言、ボタン、フッター）をテストするには、メッセージエンドポイントに内容を要求します。GET /v1/addresses/{address}/messages?include=html で各メールの HTML、include=text でプレーンテキストが追加されます。HTML はメール受信時にクリーンアップされたコピーです。スクリプト、フレーム、メディアは削除され、フォームコントロールは外され、Web、mailto:、tel: 以外のリンクは除去されます（myapp:// のようなアプリリンクはコードとリンクに残ります）。上限は 200 KB です。内容は送信者が書いたものなので、信頼できないものとして扱ってください。MCP 経由で接続したエージェントはメールの内容を受け取らず、コードやリンクだけを受け取ります。

国

Section titled “国”

居住地を尋ねる登録フォームや、地域に応じたコンテンツのテストには、"country": "GB"（任意の ISO 3166-1 alpha-2 コード、大文字・小文字どちらでも可）を追加します。persona.country として大文字で返され、アドレスに国がある場合にだけ含まれます。PATCH と "country": null で変更またはクリアします。MCP 経由で接続したエージェントも、create_address と update_address に country を渡せます。

待機の仕組み

Section titled “待機の仕組み”

待機は、過去 15 分以内に受信した一致する最新のコードやリンクを返すか、届くまで最大 30 秒（timeout、0〜30）待機し、その後 404 を返します。それより古いものを無視するには since を渡します（たとえばテストがフォームを送信した時刻）。送信者で絞り込むには service=spotify を使います。

コードやリンクは、待機がそれを返したとき、またはアプリや Proxy Mail QA for Chrome で誰かが開いた、コピーした、入力したときに使用済みになります。アプリでは使用済みと表示され、待機で unused=true を指定するとそれをスキップします。since を変えずに 2 つ目のコードを求めるテストに使えます。

メールが届かなかったこと、または 1 回だけ届いたことの確認

Section titled “メールが届かなかったこと、または 1 回だけ届いたことの確認”

何も起きないことで合格するテストもあります。購読を解除したユーザーにニュースレターが届かない、1 分以内の 2 回目のリセット要求が拒否される、サインアップで確認メールが 2 通ではなく 1 通だけ届く、などです。

  • GET /v1/addresses/{address}/none?since=…&timeout=20 は待機と同じように応答を保留します。一致するメールが届かなければ、200 と "arrived": false、および監視した時刻である until を返します。1 通でも届くとすぐに 409 と "error": "email_arrived"、count、最初のメールの時刻、サービス、種類を返すので、curl --fail はそのステップを失敗にします。since に操作の時刻を渡すと、呼び出し前に届いたメールも数えられます。渡さない場合はリクエスト時点から監視します。より長く監視するには until を追加し(since から最大 60 分)、応答が "done": false を示している間は同じ since と until で再度呼び出します。残り時間は seconds_left でわかります。
  • GET /v1/addresses/{address}/count?since=… はすぐに count と最初の 50 通のメールを古い順に返します。「ちょうど 1 通」を確認するには、最初のメールの待機が返り、重複が届くだけの時間が経ってから数えてください。

どちらも待機と同じように絞り込みます。service と、type=code(クーポン以外のコード)または type=link(確認、マジックサインイン、招待、リセットのリンク)を使い、type=link&subtype=reset のような subtype や category でさらに絞り込めます。「購読を解除したユーザーにニュースレターが届かない」には category=marketing を使うと、届くべき領収書やパスワードリセットで失敗しません。+tag 版は自身のメールだけを数えます。どちらもメールの内容は返しません。各メールは received_at、service、および主なコードやリンクの type と subtype で要約されます。Node.js クライアントには countEmails と expectNoEmail が、Python ヘルパーには count_emails と expect_no_email があります。

メールの種類、購読解除リンク、添付ファイル

Section titled “メールの種類、購読解除リンク、添付ファイル”

届いた各メールには、理由とともに種類が付けられます。

category 条件
auth 主なコードやリンクがサインイン、確認、パスワードリセット、招待を行う、または件名がそう示している
transactional 件名が領収書、注文、支払い、予約、セキュリティ通知のように読める、または請求書の PDF やカレンダー招待が添付されている。また、サインインでもマーケティングでもないもの
marketing List-Unsubscribe、List-Unsubscribe-Post、List-Id のヘッダー、Precedence: bulk、クーポン、販促的な件名、または購読解除リンクがある

領収書はあえてマーケティングより優先されます。「次回 10% オフ」のコードが付いた領収書も領収書です。/count、/none、/checks は category を受け付け、/count は各メールの category、gap_seconds(前のメールからの時間)、添付ファイルの種類、拡張子、サイズを返します。種類が追加される前に届いたメールには種類がありません。

メールの購読解除リンクは値として保存されます。GET /link?type=unsubscribe はメール本文の購読解除またはメール設定のリンクを、type=list_unsubscribe は List-Unsubscribe ヘッダーのリンク(Gmail の購読解除ボタンが使うもの)を返します。そのボタンと同じことをするには、ご自身のツールでそこへ List-Unsubscribe=One-Click を POST してください。Proxy Mail QA はどちらも開きません。

添付ファイルは各ファイルの名前、種類、サイズとして保存され、ファイル自体は保存されません。GET /checks?expect_attachment=.pdf(複数指定するには繰り返します)は、いずれかがないと expected_attachment を失敗にします。パターンは種類(application/pdf、image/*)、拡張子(.ics)、または * を含むファイル名(invoice-*.pdf)です。/messages は名前付きで一覧にします。

購読解除の監視

Section titled “購読解除の監視”

購読解除が機能するかをテストするには、ご自身のツールでアドレスの購読を解除します。メールの購読解除リンクを開く(GET /link?type=unsubscribe)か、ヘッダーのリンクへ List-Unsubscribe=One-Click を POST します(type=list_unsubscribe)。その後、記録します。

curl -X POST "https://api.proxymail.qa/v1/addresses/k7f2x9ab12cd@mailclub.dev/unsubscribed" \
  -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" -H "Content-Type: application/json" \
  -d '{"email_id": "…", "at": "2026-10-19T10:02:00Z"}'

email_id は購読を解除したメールです。service(名前、または acme.com のようなドメイン)も使えます。どちらもない場合は、最新のマーケティングメールで決まります。at で日時をさかのぼれます。2 回記録しても問題ありません。grace(2h や 1d など、最大 30 日)は、すでに送信途中だったマーケティングを許容します。その期間内のメールは数えません。以降、その送信者からのマーケティングメールは、どれだけ後でも /checks の after_unsubscribe を失敗にし、Reports ダッシュボードに表示されます。領収書、パスワードリセット、サインインメールは数えません。GET /unsubscribed は各監視を、その後に届いたメール(after_unsubscribe:ID、時刻、after_seconds のみで内容は含みません)と passed とともに一覧にします。実行を指定すると、失敗したチェックはその実行を失敗にします。DELETE /unsubscribed?service=acme.com はアドレスが再度購読したことを記録します。

テスト内でチェックするには、別のキャンペーンを送信し、GET /none?category=marketing&since=…&until=… を数分間開いたままにします。

一連のメール

Section titled “一連のメール”

ウェルカムシリーズやドリップキャンペーンでは、POST /v1/addresses/{address}/sequence が各メールが順番どおり、時間どおりに届いたかを確認します。

curl -X POST "https://api.proxymail.qa/v1/addresses/$ADDRESS/sequence" \
  -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" -H "Content-Type: application/json" \
  -d '{"since": "2026-10-01T10:00:00Z", "steps": [{"subject": "Welcome"}, {"subject": "tips", "after": "1d"}, {"category": "marketing", "after": "7d", "within": "12h"}]}'

各ステップには、subject の語句、category、type(コードまたはリンク)、after(since から数えて届くべき時期、最大 90 日)、within(どれだけずれても合格とするか。既定値は after の 10 分の 1、最小 10 分)を指定できます。各ステップは前のステップ以降で最初に当てはまるメールを取り、pass、early、late、missing、waiting(まだ期限前)のいずれかを received_at と off_seconds とともに返します。待機中のステップがある間 done は false なので、後で再度確認してください。件名はサーバー上で照合され、返されることはありません。

国ごとの同意とマーケティングのルール

Section titled “国ごとの同意とマーケティングのルール”

アカウントがサインアップ時に同意した内容を記録すると、/checks はペルソナの居住地(アドレス作成時に設定する country)のルールで各マーケティングメールを判定します。

curl -X PUT "https://api.proxymail.qa/v1/addresses/$ADDRESS/consent" \
  -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" -H "Content-Type: application/json" \
  -d '{"marketing": "declined", "prechecked": false}'

marketing は opted_in または declined です。prechecked はフォーム読み込み時にチェックボックスがすでにオンだったことを示し、double_opt_in は confirmed または pending です(確認リンクが使われると自動で確定します)。変更点だけを指定してください。GET /consent で読み返せます。EU と EEA、英国、米国、カナダ、オーストラリア、ニュージーランド、スイス、日本、韓国、シンガポール、香港に対応しており、各判定には公式の出典と確認日が示されます。各ルールは国別のマーケティングメールのルールをご覧ください。これはテストの補助であり、法的助言ではありません。

メールの送信と構成の確認

Section titled “メールの送信と構成の確認”

GET /v1/addresses/{address}/checks は 1 通のメールにチェックを実行します。対象は、カウントと同じフィルター(since、service、type、subtype)に一致する最新のメール、または email_id で指定したメールです。待機はしないので、先にメールを待ってください。各チェックは合格、失敗、警告、スキップのいずれかになり、1 行の理由が付きます。失敗がなければ passed は true です。

チェック 失敗または警告になる条件
spf, dkim, dmarc 送信サーバーがそのドメインからの送信を許可されていない、メールに署名がない、または From ドメインの DMARC ポリシーに不合格。受信トレイがスパムに振り分けたり拒否したりする可能性があります。これらは受信サーバー自身の判定です
local_links リンクが直接、または Supabase の redirect_to のようなリダイレクトの後で、localhost やプライベートアドレスに向かう。開発環境として指定したホスト(プロジェクト設定、または POST /v1/project/dev-hosts)へのリンクは合格です
plain_http 公開サイトへのリンクが https ではない
expected_host expect_host=staging.example.com を指定した場合:サインイン、確認、リセット、招待のリンクが本番環境など別の場所に行き着く。アプリを開くリンク(myapp://…)にはサイトがないため比較しません。指定しない場合はスキップ
expiry サインインのコードやリンクがいつ無効になるかをメールに記載していない(警告。ニュースレターのリンクなど他のリンクではスキップ)
coupon_expiry Labs。 メールにクーポンがあるのに、「10 月 31 日まで有効」や「7 日間有効」のような終了時期を記載していない(警告)。主なコードだけでなく、含まれるすべてのクーポンが対象です。クーポンがない場合はスキップ
plain_text プレーンテキスト版がない(警告)
size HTML が 102 KB を超えており、Gmail で切り詰められる(警告)
images_only ほぼ画像だけで、画像をオフにするとほとんど何も伝わらない
layout スマートフォンに収まらない可能性がある:モバイル用スタイルなしで 640 px より広く固定された部分(@media)、代替テキストのない画像(画像オフで空白)、11 px 未満の文字。レンダリングせず HTML だけで判定する警告です
expected_text expect_text を指定した場合(最大 10 語句まで繰り返し可):件名または本文に、ユーザーの名前や製品名などのいずれかがない。大文字小文字、曲線引用符、空白は区別しません。理由には欠けている語句だけを示します。指定しない場合はスキップ
expected_attachment expect_attachment=.pdf を指定した場合(複数指定は繰り返し):いずれかが添付されていない。指定しない場合、または添付ファイルの記録前に届いたメールではスキップ
arrival_time since と expect_within=5m(または秒数を表す 90s、2h)を指定した場合:since からそれより遅れて届いた。たとえば 14 分かかったウェルカムクーポンなど。指定しない場合はスキップ
list_unsubscribe Labs。 マーケティングメールのみ:List-Unsubscribe ヘッダーがない(失敗)、またはメールアドレスか通常の http のものしかない(警告)。このヘッダーがあると受信トレイ独自の購読解除ボタンが表示され、Gmail と Yahoo は大量送信者にこれを求めています
one_click_unsubscribe Labs。 マーケティングメールのみ:https アドレスを含む List-Unsubscribe-Post: List-Unsubscribe=One-Click ヘッダーがない、または検証済みの DKIM 署名が両方の List-Unsubscribe ヘッダーを含んでいない(RFC 8058 で必須で、満たさないと受信トレイはワンクリックを提供しません)。そのため受信トレイのボタンで 1 回で購読を解除できない(警告)
unsubscribe_link Labs。 マーケティングメールのみ:メール本文に購読解除やメール設定のリンクがない
after_unsubscribe Labs。 マーケティングメールのみ:アドレスがその送信者の購読を解除した後に届いた(「購読解除の監視」を参照)。購読解除として記録されていない場合はスキップ
offer_reuse Labs。 すでに別の形のアドレス(name+promo1@…、大文字)にクーポンを送った送信者からのクーポン:アプリが 1 人を複数人として扱っています。クーポンのないメールではスキップ
coupon_result Labs。 結果が記録された後の、チェックアウトでのクーポンの扱い:終了日の後、再利用されたオファー、1 回限りなのに 2 回、のいずれかで受け付けた(失敗)。エラー、または有効期間内の初回使用での拒否(警告)。結果がない場合はスキップ
marketing_consent Labs。 事前の同意が必要な地域(EU と EEA、英国、カナダ、オーストラリア、ニュージーランド、スイス、日本、韓国)で、拒否したアカウントへのマーケティングメール。米国、または同意が記録されていない場合はスキップ
prechecked_consent Labs。 同意が事前にチェックされたボックスによるもの(EU と EEA、英国)
double_opt_in Labs。 アドレスが購読を確定する前のマーケティング:ドイツでは警告、プロジェクトがダブルオプトインを必須にしている場合は失敗
unsubscribe_deadline Labs。 購読解除後のマーケティング:許容期間内なら警告(米国、カナダ、シンガポール、香港は 10 営業日、オーストラリアとニュージーランドは 5 営業日、EU、英国、スイス、日本、韓国は速やかに)、それ以降は失敗
postal_address Labs。 マーケティングメールに郵送先住所が見つからない(米国、カナダ。警告)
sender_identity Labs。 From 行に送信者名がない(警告)
minor_marketing Labs。 英国で 13 歳未満、EU と EEA で 16 歳未満のペルソナへのマーケティング(警告)
misleading_subject Labs。 米国、カナダ、香港:返信や転送のように始まる件名(Re:、Fwd:)、またはクーポンがさらに数日有効なのに本日終了と書いた件名(警告。米国のペルソナにはワシントン州とカリフォルニア州の法律が適用されます)
ad_label Labs。 シンガポール:拒否したアカウントへのマーケティングで、件名が <ADV> で始まっていない(警告)
harmful_attachment Labs。 添付ファイルが Gmail がブロックするファイル形式(.exe、.js、.iso など)、または文書に見せかけた名前のプログラム(.pdf.exe):失敗。マクロを含みうる Office ファイル、HTML や SVG のページ、アーカイブは警告。理由には拡張子だけを示し、ファイルは示しません。添付ファイルがない場合はスキップ
spam_risk Labs。 スパムフィルターが重視する指標(markers、それぞれの点数付き)を合計した 10 点満点のスパムスコア(score):5 点以上で失敗(受信トレイが拒否またはスパムに振り分ける可能性が高い)、1.5 点以上で警告。重大な要因は 5 または 6 点:reject または quarantine ポリシーでの DMARC 不合格、SPF と DKIM のどちらも不合格、ブロックされる添付ファイル。次に 2〜3 点:DMARC ポリシーなし、DKIM なし、ほぼ画像だけ、IP アドレス直接へのリンク、短縮 URL、List-Unsubscribe ヘッダーのないマーケティング。次に最大 1.5 点:SPF 不合格、危険な添付ファイル、署名のないワンクリック購読解除、Re: で始まるマーケティングの件名、大文字ばかりまたは !!! を含む件名、典型的なスパム語句、別サイトを示すリンクテキスト、プレーンテキストなし。これは推定です。受信トレイは送信者の評判も考慮しますが、それは受信トレイ側にしか見えません
preheader Labs。 マーケティングメールのみ:HTML の冒頭に非表示のプレビューテキストがないため、受信トレイには代わりに最初の言葉(多くは「ブラウザで表示」)が表示される(警告)
language expect_language=de(または pt-BR)を指定した場合:別の言語で書かれている。判定に十分な文字がない場合は警告。対応言語は英語、ドイツ語、フランス語、スペイン語、イタリア語、オランダ語、ポルトガル語、スウェーデン語、ポーランド語、トルコ語、フィンランド語、ロシア語、ウクライナ語、日本語、中国語、韓国語、アラビア語、ヘブライ語、ギリシャ語、タイ語、ヒンディー語です。指定しない場合はスキップ

Labs の付いたチェックは、キーの作成者が Labs 機能をオンにするまで除外されます。クーポンとマーケティングのチェックには Marketing and offer emails、harmful_attachment と spam_risk には Spam score and attachment checks が必要です。

curl "https://api.proxymail.qa/v1/addresses/k7f2x9ab12cd@mailclub.dev/checks?type=link&expect_host=staging.example.com" \
  -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY"
{
  "address": "k7f2x9ab12cd@mailclub.dev",
  "email": { "id": "…", "received_at": "2026-10-17T10:00:01Z", "service": "Supabase", "service_domain": "supabase.io", "type": "link", "subtype": "verify" },
  "passed": false,
  "failed": ["local_links"],
  "warnings": ["expiry"],
  "checks": [
    { "check": "spf", "status": "pass", "detail": "The sending server is allowed to send for supabase.io." },
    { "check": "local_links", "status": "fail", "detail": "A link goes to localhost:3000, which only opens on the computer running that server." }
  ]
}

サインインメールと領収書、および種類が追加される前のメールは、4 つのマーケティングチェックをスキップします。最新のメールへのチェックがニュースレターに当たり list_unsubscribe で失敗することがあるため、type、subtype、category を渡して目的のメールをチェックしてください。

ローカライズされたメールでは、各ロケールの文面をチェックしてください:?type=code&expect_language=fr&expect_text=Bonjour%20Maya。

応答にはメールの内容やリンクは含まれません。理由に示すのはせいぜいドメイン、リンクのホスト、またはご自身の語句だけなので、エージェントは信頼できないメール本文を読まずに対応できます。Node.js クライアントには checkEmail が、Python ヘルパーには check_email があります。

並列テスト用のアカウントプール

Section titled “並列テスト用のアカウントプール”

テスト用アカウントを既知の状態に保ち、各テストに 1 つずつ貸し出します。アカウントに状態のタグ(verified、premium、trial)を付け、1 つをチェックアウトします。すべてのフィルターに一致し、誰もチェックアウトしていないアカウントが、最も長く使われていないものから順に渡され、minutes 分間確保されます(指定しなければ 10 分、最大 60 分)。並列テストが同じアカウントを受け取ることはありません。

curl -s -X POST https://api.proxymail.qa/v1/addresses/checkout -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" \
  -H "Content-Type: application/json" -d '{"tags":["verified","premium"],"country":"DE","minutes":5}'
# { "address": "…", "persona": {…}, "tags": ["premium", "verified"], "checkout": { "token": "…", "until": "…" } }

そのアカウントでサインインし(パスワードを読めるキーなら保存済みのパスワードを使います)、テストを実行してから、トークンを付けて返却します。返却時にテストが残した状態を記録できるので、プールの情報は正確に保たれます:

curl -s -X POST "https://api.proxymail.qa/v1/addresses/$ADDRESS/return" -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" \
  -H "Content-Type: application/json" -d "{\"token\":\"$TOKEN\",\"add_tags\":[\"cancelled\"],\"remove_tags\":[\"premium\"]}"

Node.js クライアント と Python ヘルパー では、テストのフックからアカウントの作成、確認、リセットもできます。これにより、テストは必要な状態のアカウントを受け取れます。

返却されないチェックアウトは、時間切れになると自動で解放されます。そのため、クラッシュしたテストがアカウントを長く確保し続けることはありません。extend で時間を延長できます。一致するアカウントがすべてチェックアウト中の場合は 409 が返り、最初に空く時刻が示されます。一致するものがない場合は 404 です。アプリには誰がいつまでアカウントを使っているかが表示され、プロジェクトのメンバーなら誰でも解放できます。

実行:プルリクエスト向けのレポート

Section titled “実行:プルリクエスト向けのレポート”

実行は CI のジョブやエージェントのセッションをまとめ、各呼び出しで確認した内容を証拠として残します。実行を開始し、各呼び出しの Proxy-Mail-QA-Run ヘッダーでその id を送ってください:

RUN=$(curl -s -X POST https://api.proxymail.qa/v1/runs -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" \
  -H "Content-Type: application/json" -d '{"name":"Sign-up tests","source":"ci"}' | jq -r .id)
curl -s "https://api.proxymail.qa/v1/addresses/$ADDRESS/code?since=$SUBMITTED" \
  -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY" -H "Proxy-Mail-QA-Run: $RUN"
curl -s -X POST "https://api.proxymail.qa/v1/runs/$RUN/finish" -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY"
curl -s "https://api.proxymail.qa/v1/runs/$RUN?format=markdown" -H "Authorization: Bearer $PROXYMAIL_QA_API_KEY"

GET /v1/runs/{id} は、同じ名前で直近に完了した 10 回の実行とも比較します(JSON の comparison。Markdown レポートの上部近くにある一覧です)。メールが大幅に遅い、メールの数が違う、新しいテスト失敗や断続的なテスト失敗、新たに失敗したチェック、新しい送信者やリンク先サイトなどを示します。メールをチェックした場合、deliverability は、拒否されるか迷惑メールに振り分けられる可能性が高いメール(likely_spam)、迷惑メールに振り分けられる可能性があるメール(may_spam)、受信トレイがブロックする添付ファイルを含むメールの数を示します。各メールは最新のチェックで 1 回だけ数えます。Markdown レポートでも、見出しの下の行に同じ内容が表示されます。これは各メールの spam_risk チェックに基づく推定なので、Labs でスパムスコアと添付ファイルのチェックを有効にする必要があります。

各呼び出しは、確認した内容を追加します。作成したアドレス(フォームの値を含む)やプールからチェックアウトしたアドレス、届いたメール(コード、またはリンクのサイトとパス。トークンらしきものは隠し、since から何秒後に届いたかも記録)、件数、メールのチェック、配信停止・オファー・クーポンのチェック、届かなかったメールや届くべきでないのに届いたメールです。完了時、これらのいずれかが失敗した場合、メモで失敗にした場合、または {"failed": true} を送った場合を除き、実行は成功になります。レポートは Markdown で、プルリクエストのコメントやジョブのサマリーに使えます。実行はアプリでプロジェクトの全員が 90 日間閲覧できます。

呼び出しがどのテストに属するかを示すには、テスト名をパーセントエンコードして Proxy-Mail-QA-Test で送ります(例:sign-up%20%E2%80%BA%20sends%20one%20code)。レポートでは、呼び出しで確認した内容の横にテスト名が表示されます。テストランナーのレポーターは結果を POST /v1/runs/{id}/tests に送ります。失敗したテストや不安定なテストはそれぞれ {"name", "status": "failed", "duration_ms", "error"} として送り(失敗したテストがあると実行は失敗になります)、最後にレポートの上部用に {"totals": {"passed", "failed", "skipped", "flaky"}} を送ります。

証拠の記録によって呼び出しが失敗することはありません。呼び出しを追加できない場合(実行が完了している、またはこのキーのプロジェクトの実行ではない場合)でも呼び出しは動作し、Proxy-Mail-QA-Run-Warning ヘッダーで理由が示されます。待機が空で返ったときに再試行するクライアントは、最後以外の試行で Proxy-Mail-QA-Run-Retry: true を送ります。これにより、最後の「何も届かなかった」だけが記録されます。GitHub Actions では、Proxy Mail QA アクション がこれをすべて行います。

何も届かないとき

Section titled “何も届かないとき”

404 では、わかる範囲で理由も示します。hint は、そのアドレス宛てで拒否したもの(大きすぎる、または上限超過)を示します。一度も何も届いていない場合は、最も可能性の高い原因を示します。refused は since 以降に拒否したものを一覧にします。blocked は、届く前に Cloudflare のメールサーバーが拒否したメール(SPF、DKIM、DMARC の不合格による拒否、破棄、未配信)を、送信者のドメインと SPF、DKIM、DMARC の結果とともに一覧にします。help は テストメールが届かない場合 へのリンクです。MCP ツールは found: false に対して同じ message、refused、help を返します。待たずにいつでもアドレスを確認するには、GET /v1/addresses/{address}/delivery を呼び出します。これまでに受信したメール、記録に残っているすべての拒否、hint が返ります。アプリは任意のアドレスにメールを送れる必要があります。サンドボックスモードやテストモードのメールプロバイダーは、確認済みのアドレスにしか送信しません。

エラー

Section titled “エラー”

エラーは {"error": "not_found", "message": "…"} として、対応するステータスで返ります。400、401、402(プランのない組織)、403(権限がない、または Labs の機能が無効)、404、409(none チェック中にメールが届いた)、429 です。リクエストの上限は 上限と安全性 を参照してください。500 が返る場合や、全員のリクエストがタイムアウトする場合は、当社側の障害の可能性があります。ステータスページ を確認してください。

このページについて質問がありますか？

質問はどの言語でもかまいません。ドキュメントからすぐに回答を得ることも、Proxy Mail QA チームに質問を送ることもできます。チームからの返信は英語です。

ドキュメントに質問