プラグイン不要でTypeformのメールを検証する方法

Typeformはメールアドレスを集めるのにはとても優れていますが、そのアドレスが実在するかどうかを見分けるのは不得意です。メールフィールドで確認できるのは、入力された内容がアドレスの形式になっているかどうかだけです。メールボックスが存在するか、使い捨てではないか、最初のフォローアップがハードバウンスにならないかは確認できません。このガイドでは、QualisendでTypeformのメールアドレスを検証する実用的な方法を2つ紹介します。1つは、回答が届いた瞬間に動作するWebhookによるリアルタイム検証、もう1つは、回答をCSVにエクスポートする一括検証です。どちらもネイティブのプラグインは不要です（まだ提供されていません）。Typeform標準のWebhookまたはエクスポートボタンだけで実現できます。

結論から#

答えが必要なタイミングに合わせて、方法を選んでください。

• リアルタイム：Typeformのwebhookを小さなサーバーレス関数に向けます。送信のたびにTypeformが回答を関数のエンドポイントにPOSTし、関数がメールアドレスを取り出してQualisend APIを呼び出し、判定に応じて動作します。たとえば、連絡先にタグを付ける、適切なリストに振り分ける、不正なアドレスにはウェルカムメールの送信を保留する、といった処理です。
• 一括：既存の回答をCSVにエクスポートし、Qualisendの一括検証にかけて、次の送信前に配信不能なアドレスを除外します。

Typeformのメールフィールドだけでは不十分な理由#

Typeformのemail質問タイプは、ブラウザー上で形式チェックを行います。@とドメインがあり、明らかな不正文字列がないことを確認するだけです。これは正規表現によるチェックと同じ種類のもので、同じ理由で失敗します。形式が正しくても到達できるとは限りません。jane@gmial.comは形式チェックを通過します。throwaway@mailinator.comも、昨年閉鎖したドメインの、一見それらしいアドレスも同様です。

これらは実際に送信するまで検出されず、その時点では、無効なアドレスがハードバウンスとなって、バウンス率と送信者レピュテーションを少しずつ損ないます。本格的な検証では、Typeformにはできないチェックが加わります。DNS/MXのルックアップとSMTPによるメールボックスのプローブに加えて、使い捨て、役割アドレス、キャッチオールのフラグです。この仕組みが初めての方は、メールアドレス検証で実際に何をチェックするのかをご覧ください。

Typeformのメールを検証する2つの方法#

最初に重要な制約があります。Typeformは、フォームの途中で不正なメールをブロックできません。質問の合間に外部APIを呼び出して、回答者が最後まで進むのを止める方法は公式にはサポートされていません。そのため、リアルタイム検証はインラインのゲートではなく、送信の直後にWebhookで行います。この制約が、2つの方法の前提になります。

方法1：Typeformのwebhookによるリアルタイム検証#

Typeformは、各回答を指定したURLに送信できます。フォームのConnectパネルでwebhookを追加し、エンドポイントを指定します。Typeformではwebhookは有料プランの機能のため、構築前にご利用のプランを確認してください。回答が送信されると、TypeformはJSONペイロードをPOSTします。form_response.answers配列に各回答が入っており、メールアドレスはemailタイプの回答にあります。

エンドポイントはサーバーレスの関数で、APIキーを保持し、判定結果に応じた処理を実行します。パターンはサインアップ時に検証するガイドと同じで、キーはサーバー側に置き、結果に応じて動作します。次はNext.jsのRoute Handlerとして実装した例です（正確なエンドポイントのパスとリクエスト形式は開発者向けドキュメントで確認してください）。

// app/api/typeform-webhook/route.ts
import { NextResponse } from "next/server";

// Qualisend's verify endpoint (full request and response shapes in /developers).
const QUALISEND_ENDPOINT = "https://app.qualisend.com/api/v1/verify";

export async function POST(req: Request) {
  const payload = await req.json();

  // The email lives in the answer whose type is "email".
  const answers = payload.form_response?.answers ?? [];
  const email = answers.find((a) => a.type === "email")?.email;
  if (!email) return NextResponse.json({ ok: true }); // nothing to verify

  const res = await fetch(QUALISEND_ENDPOINT, {
    method: "POST",
    headers: {
      // Store YOUR_API_KEY server-side, never in the browser.
      Authorization: `Bearer ${process.env.QUALISEND_API_KEY!}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email }),
    signal: AbortSignal.timeout(4000),
  }).catch(() => null); // timeout or network error: fail open too

  if (!res?.ok) return NextResponse.json({ ok: true, degraded: true }); // fail open
  const { job_id, result } = await res.json();

  // The submit already happened — route on the verdict instead of blocking.
  if (result.status === "undeliverable" || result.sub_flags?.disposable) {
    // Skip the welcome email, tag the contact for review, keep it off the main list.
  } else if (result.smtp === "pending") {
    // The mailbox probe is still running. Queue job_id for a background job that
    // polls GET https://app.qualisend.com/api/v1/jobs/{job_id} and routes the final
    // verdict; don't wait for it here, and don't call /verify again.
  }

  return NextResponse.json({ ok: true, status: result.status });
}

このコードが堅牢である理由は3つあります。1つ目は素早く応答することです。Typeformは2xxをすぐに受け取ることを期待しているため、ハンドラーは軽量に保ち、速やかに返します。2つ目はフェイルオープンにすることです。APIがタイムアウトしたりエラーを返したりしても、リードを失わないよう受け付けて、後で再チェックします。!res?.okの分岐がok: trueを返しているのはそのためです。3つ目は、Typeformが送る署名を検証することです。これにより、第三者がエンドポイントに偽の回答をPOSTできなくなります。署名用のシークレットはConnectパネルで取得できます。

最初に返るのは、即時の判定です。result.smtpがcachedまたはskippedの場合は、すでに最終結果です。pendingの間は、SMTPによるメールボックスのプローブがまだ実行中のため、statusはunknownとなり、最終結果はGET https://app.qualisend.com/api/v1/jobs/{job_id}で取得できます。これはwebhookの内部ではなくバックグラウンドジョブからポーリングし、/verifyを再度呼び出すことは避けてください。

ペイロードにはもう1つ注意点があります。フォームにメールの質問が複数ある場合や、質問の並べ替えに強くしたい場合は、最初のtype === "email"の回答を取るのではなく、回答のfield.refで照合します。Typeformのビルダーでメールの質問に固定のrefを設定し、a.field?.ref === "your_ref"で読み取れば、検証対象のアドレスを常に正しく特定できます。

その後の処理は、判定による分岐にすぎません。deliverableはそのままCRMやメールツールに渡します。undeliverableやdisposableは、タグを付ける、ウェルカムシーケンスから外す、確認キューに入れるなど、運用に合わせて処理します。webhookは配管の役割で、振り分けは自社で決めます。

検証のロジック自体は言語に依存しません。PythonやPHPの関数で運用している場合も、同じ呼び出しが使えます。Node.jsのチュートリアルやPythonのチュートリアルのエンドポイントのコードは、そのままwebhookハンドラーに組み込めます。Typeform固有なのは、上のペイロードの解析部分だけです。

方法2：CSVエクスポートを一括検証する#

すでに回答が溜まっている場合や、webhookを構築するより定期的にクリーニングしたい場合は、バッチで処理します。TypeformでResults → Responsesを開き、データをCSV（またはXLSX）でダウンロードします。送信1件につき1行で、メールアドレスは専用の列に入っています。

次の手順で進めます。

1. CSVをアップロードして、Qualisendの一括検証で全行にフルパイプライン（MX、SMTP、使い捨て/役割アドレス/キャッチオールのフラグ）を実行します。
2. 注釈付きのファイルをダウンロードします。各アドレスに、ステータス、理由コード、0～100のスコアが付いて返されます。
3. 実際にメールを送信しているツールで配信不能なアドレスを除外し、リスクのある行は慎重に扱います。各ステータスの扱いを含む一連の流れは、メールリストのクリーニング方法で解説しています。

一括検証は溜まった分を片付けるのに適していますが、予防ではなくクリーンアップです。ここで検出できるアドレスは、たいていすでにリストに入っています。定期的な一括検証とリアルタイムのwebhookを組み合わせれば、新たな不正アドレスも届いた時点でフラグを付けられます。

判定結果に応じた対応#

どちらの方法で結果を受け取っても、構造は同じで、status、reason、score、サブフラグで構成されています。それぞれを次の動作に対応させます。

準備はできましたか？スコープ付きキーと正確なリクエスト形式は開発者向けドキュメントで入手できます。無料メールチェッカーで1件のアドレスを試すこともできます。また、すべてのプランで100クレジットを無料で利用できるので、フローを最初から最後まで試してみてください。