APIキーとウェブフック

Mail Mergeは開発者とノーコードビルダー向けのREST APIと送信ウェブフックを提供しています。APIキーを使用すれば、スクリプトはウェブアプリと同じことができます。アカウントの読み取り、テンプレートと連絡先の一覧表示、キャンペーンの送信、受信者の追跡ができます。ウェブフックを使用すれば、キャンペーンが完了したり、受信者がメールを開いたり、クリックしたり、返信したり、バウンスしたり、登録解除したりした瞬間に、Mail Mergeがエンドポイントを呼び出すため、CRM、スプレッドシート、またはSlackチャネルがポーリングなしで同期を保つことができます。

どちらもウェブアプリの設定 → 開発者にあり、Professionalプランの一部です(料金を参照)。コードを書く代わりにAIアシスタントからMail Mergeと通信したい場合は、代わりにMCPサーバーを使用してください。すべてのプランでツールとして同じ機能を公開しています。

APIキー

キーの作成

1. 設定 → 開発者 → APIキーを開き、キーを作成をクリックします。
2. 使用場所に基づいて名前を付けます(Zapier、CRM同期など)。後で正しいものを取り消すことができます。
3. キーをコピーします。1回だけ表示されます。Mail Mergeはハッシュのみを保持します。紛失した場合は、取り消して新しいキーを作成してください。

アカウントごとに最大10個のキーを持つことができます。キーを取り消すと、そのキーで作成されたすべてのリクエストが直ちに失敗します。行はリストから消えます。

認証

すべてのリクエストでキーをBearer トークンとして送信し、カード上に表示されたベースURLに対して送信します。

curl https://merge.email/api/v1/me \
  -H "Authorization: Bearer mm_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

キーはそれを作成したアカウントとして機能します。サインインセッションと同じです。同じGoogleグラント、同じ日次クォータ、同じプラン制限があります。別の「APIユーザー」はありません。

エンドポイント

APIはウェブアプリが使用するのと同じ/v1サーフェスであるため、画面で実行できることはすべてその背後にエンドポイントがあります。統合が最も多く使用するもの:

呼び出し	機能
GET /v1/me	アカウント: プラン、日次クォータ(最大、使用済み、残り)、タイムゾーン、テンプレートメタデータ。
GET /v1/templates · GET /v1/templates/{templateId}	保存されたテンプレート。本文はテンプレートごとに読み込まれます。
GET /v1/contacts · POST /v1/contacts	アドレス帳(limit / cursor → nextCursorでページネーション)。
POST /v1/campaigns	Google Sheetからキャンペーンを送信、スケジュール、またはオートパイロットします。本文はキャンペーンビルダーが投稿するのと同じです。シート、受信者列、{{マージタグ}}を含む件名と本文、送信オプション。
GET /v1/campaigns · GET /v1/campaigns/{campaignId}/recipients	キャンペーンと各受信者のステータス(送信済み、読み取り、クリック、返信、バウンス、登録解除)。
POST /v1/campaigns/{campaignId}/status	実行中のキャンペーンを一時停止、再開、または停止します。
POST /v1/recipients/verify	メール検証ツール。

リクエストとレスポンスの本文はJSONです。完全な型付きサーフェスはサーバーからOpenAPIドキュメントとして生成されます。クライアントジェネレータのスキーマが必要な場合はお問い合わせください。

エラーとレート制限

失敗は1つのエンベロープを持つ実際のHTTPステータスです。

{ "error": { "code": "professional_plan_required", "message": "API access is a Professional plan feature" } }

ステータス	code	意味
401		不明または取り消されたキー、またはアカウントのGoogle アクセスの再接続が必要です。
403	professional_plan_required	キーのアカウントはProfessionalプランではなくなりました。ダウングレード時にキーは削除されません。プランが復帰すると再び機能します。
429	rate_limited	1つのキーで1分あたり600リクエスト以上。1分待ってから再試行してください。
400 / 404 / 409	bad_request、not_found、conflictなど	リクエスト自体。修正する内容を説明するメッセージ付き。

レート制限は各APIサーバーインスタンスのキーごとにカウントされるため、実効上限は「約1分あたり600」です。これに達することを前提に設計しないでください。

ウェブフック

エンドポイントの追加

1. 設定 → 開発者 → ウェブフックを開き、ウェブフックを追加をクリックします。
2. HTTPS URL(プレーンhttp://は拒否されます)を入力し、受信するイベントをチェックします。
3. 新しい行のテスト送信をクリックします。Mail Mergeがpingを投稿し、トーストがエンドポイントの応答を表示します。

各エンドポイントは独自の署名シークレット(whsec_…)を取得します。行にコピーボタン付きで表示されます。アカウントごとに最大5つのエンドポイントを持つことができます。

イベント

イベント	発生時期	data
campaign.completed	キャンペーンの最後のメールが処理されました。	campaignId、name、status: "completed"、sentCount、campaignSize
campaign.paused · campaign.resumed · campaign.stopped	キャンペーンを一時停止、再開、または停止しました。	campaignId、name、status(paused / active / stopped)、sentCount
email.opened	受信者がメールを開きました(キャンペーンごとに初回のみ)。	campaignId、recipient、at
email.clicked	受信者が追跡されたリンクをクリックしました(すべてのクリック)。	campaignId、recipient、at、url
email.replied	送信されたスレッドで返信が検出されました。	campaignId、recipient、at
email.bounced	バウンスが検出されました。	campaignId、recipient、at
recipient.unsubscribed	受信者が登録解除リンクを使用しました(キャンペーンごとに初回のみ)。	campaignId、recipient、at、method

開封とクリックはキャンペーンの追跡が必要です。返信とバウンスは送信されたすべてのキャンペーン後の返信スキャンから来ます。

配信

Mail Mergeは登録されたエンドポイントごとにイベントごとに1つのPOSTを送信します。JSONボディ付き:

{
  "id": "6f1c2d3e-…",
  "event": "email.opened",
  "createdAt": "2026-10-15T14:03:21.512Z",
  "data": { "campaignId": "…", "recipient": "ada@example.com", "at": "2026-10-15T14:03:21.498Z" }
}

と3つのヘッダー:

ヘッダー	値
X-MailMerge-Event	イベント名。本文のeventと同じです。
X-MailMerge-Delivery	配信ID。本文のidと同じです。重複を無視するために使用します。
X-MailMerge-Signature	sha256=の後に、エンドポイントのシークレットをキーとした生のボディのHMAC-SHA256の16進数が続きます。

5秒以内に任意の2xxで応答してください。ネットワークエラーまたは5xxの場合、Mail Mergeは2秒後に1回再試行します。4xxはあなたの判定として受け取られ、再試行されません。同じ配信IDが再試行時に送信されます。連続して20回の配信失敗後、エンドポイントは無効化され、行にそう表示されます。エンドポイントを修正してから削除して再度追加してください。成功した配信はカウンターをリセットします。

イベントは少なくとも1回配信され、順序は保証されません。特に開封はバースト(トラッキングピクセルをレンダリングするすべてのメールクライアント)で到着するため、X-MailMerge-Deliveryまたは(event、campaignId、recipient)でハンドラーをべき等にしてください。

署名の検証

ペイロードを信頼する前に常に検証してください。生のリクエストボディ(JSONパース前の正確なバイト)でHMACを計算し、定時間で比較します。

// Node.js (Express with `express.raw({ type: "application/json" })`)
import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyMailMergeSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? "")
  return a.length === b.length && timingSafeEqual(a, b)
}

app.post("/mailmerge", (req, res) => {
  if (!verifyMailMergeSignature(req.body, req.get("X-MailMerge-Signature"), process.env.MAILMERGE_WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  const payload = JSON.parse(req.body)
  // … handle payload.event / payload.data
  res.status(204).end()
})

# Python
import hashlib, hmac

def verify_mailmerge_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Zapier、Make、n8n

コード不要です。Catch Hook(Zapier Webhooks by Zapier)、Custom webhook(Make)、またはWebhookトリガーノード(n8n)を作成し、提供されたURLをエンドポイントとして貼り付け、イベントをチェックして、テスト送信をクリックするとツールがペイロードをサンプリングできます。dataフィールドは次のステップにマップする変数になります(シートに行を追加、CRM連絡先を更新、Slackに投稿)。これらのツールは署名を標準では検証しません。提供されるURLは推測不可能であり、それが依存する保護です。

次のステップ

• AIエージェント(MCP)。アシスタントがスクリプトの代わりにMail Mergeを駆動する場合。
• キャンペーン。受信者エンドポイントのステータスの意味。
• 料金。Professionalプランに含まれるもの。