開発者 API - Nudgen

概要

Nudgen 開発者 API は、ワークスペース用の予測可能な REST インターフェイスをスクリプト、内部ツール、AI エージェントに提供します。パーソナルアクセストークン (PAT) を使用して、ワークスペースリソースを管理します。チームトリガー API キーは、バックエンドからライフタイムキャンペーンをトリガーする場合にのみ使用してください。

これが重要な理由

ダッシュボードセッションを共有せずに、マーケティングおよびイベント主導型の保持ワークフローを自動化できます。 PAT によりワークスペース管理は取り消し可能に保たれますが、狭いチームトリガーキーを使用すると、実稼働サービスはワークスペースに広範囲にアクセスしなくてもイベントトリガーのナッジを送信できます。

ベース URL

環境のアプリ URL を 1 回設定すると、それをすべての例で使用できます。本番環境では通常、https://app.nudgen.net を使用します。ローカル開発では通常、http://localhost:3000 を使用します。

export NUDGEN_APP_URL="https://app.nudgen.net"

認証

パーソナルアクセストークン

[設定] → [API キー] で PAT を作成します。連絡先、キャンペーン管理、ブランド設定、AI 生成に使用します。

Authorization: Bearer $NUDGEN_PAT

PAT は 1 回だけ表示されます。これらを安全に保存し、設定 → API キー から古いトークンまたは公開されたトークンを取り消します。

チームトリガー API キー

チームトリガー API キーは、ndg_team_ で始まり、campaigns:trigger という狭いスコープを持ちます。ライフタイムキャンペーンのみをトリガーできます。 PAT はキーをトリガーできません。これらのキーを作成、ローテーション、または取り消すことができるのは、ワークスペースの所有者と管理者だけです。デフォルトでは、キーは 90 日後に期限切れになります。無期限のキーを作成するには、expiresInDays を null に設定します。

curl -X POST "$NUDGEN_APP_URL/api/v1/settings/team-api-keys" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"name":"Order service production","expiresInDays":90}'

201 応答には、プレーンテキスト key が 1 回だけ含まれています。サーバー側のシークレットマネージャーに保存します。その後の応答では、keyPrefix のみが公開されます。

方法	エンドポイント	説明
`POST`	`/api/v1/settings/team-api-keys`	チームトリガーAPIキーを作成します。
`GET`	`/api/v1/settings/team-api-keys`	チームトリガー API キーをリストします。
`POST`	`/api/v1/settings/team-api-keys/:id`	有効期限が切れていないアクティブなキーをローテーションします。
`DELETE`	`/api/v1/settings/team-api-keys/:id`	キーを取り消します。

REST エンドポイント

ID とワークスペース

方法	エンドポイント	説明
`GET`	`/api/v1/user/me`	認証されたユーザーを取得します。
`GET`	`/api/v1/teams`	トークン所有者が利用できるワークスペースをリストします。

連絡先

方法	エンドポイント	説明
`GET`	`/api/v1/contacts`	`page`、`limit`、`search`、`tags`、および `status` フィルターを使用して連絡先を一覧表示します。
`POST`	`/api/v1/contacts/add`	連絡先を作成します。
`GET`	`/api/v1/contacts/:id`	連絡先を取得します。
`PATCH`	`/api/v1/contacts/:id`	連絡先を更新します。
`DELETE`	`/api/v1/contacts/:id`	連絡先を削除します。

curl -X POST "$NUDGEN_APP_URL/api/v1/contacts/add" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"email":"nathan@example.com","name":"Nathan Nguyen","tags":["api-test"]}'

ワンショットキャンペーンとドリップキャンペーン

方法	エンドポイント	説明
`GET`	`/api/v1/campaigns`	アクティブなワークスペース内のキャンペーンをリストします。
`POST`	`/api/v1/campaigns`	キャンペーンの下書きまたはスケジュールされたキャンペーンを作成します。
`GET`	`/api/v1/campaigns/:id`	キャンペーンの詳細を取得します。
`PUT`	`/api/v1/campaigns/:id`	既存のキャンペーンを更新します。
`POST`	`/api/v1/campaigns/:id/launch`	今すぐ開始するか、ワンショットまたはドリップキャンペーンをスケジュールしてください。
`GET`	`/api/v1/campaigns/:id/stats`	配信、開封、クリック、バウンス、苦情の統計を取得します。
`GET`	`/api/v1/campaigns/:id/progress`	キャンペーン送信の進行状況を取得します。
`GET`	`/api/v1/campaigns/:id/recipients`	キャンペーンの受信者をリストします。
`POST`	`/api/v1/campaigns/test-send`	ダッシュボード送信統計を使用せずにテストメールを送信します。

キャンペーンを開始すると、実際のメールがスケジュールされます。受信トレイのプレビューには、/api/v1/campaigns/test-send を使用してください。

ライフタイムキャンペーン

ライフタイムキャンペーンはイベントによってトリガーされます。受け入れられたトリガーごとに最大 1 つの実行が作成され、指定された連絡先に 1 つのナッジが送信されます。ダッシュボードのワークフローと変動契約のガイダンスについては、ライフタイムキャンペーンを使用するを参照してください。

ライフタイムキャンペーンを作成する

ライフタイムキャンペーンを draft として作成します。 sendNow: true、status: "active"、または status: "scheduled" は送信しないでください。代わりに、ライフサイクルエンドポイントを使用してキャンペーンをアクティブ化します。

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "name": "Order confirmation",
  "type": "lifetime",
  "status": "draft",
  "goal": "Confirm an order and direct the customer to its details.",
  "subject": "Your order {{data.order_id}} was received",
  "html": "<p>Hello {{contact.firstName}},</p><p>Order {{data.order_id}} totals {{data.total}} VND.</p><p><a href=\"{{data.order_url}}\">View your order</a></p>",
  "link": "https://example.com/orders",
  "variableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ],
  "generatedVariableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ]
}
JSON

variableManifest は、最大 100 個の data.* 変数を定義します。件名または HTML で使用されるすべての data.* トークンを含める必要があります。デフォルトは宣言された型と一致する必要があり、HTML href で使用される変数の型は url である必要があります。電子メールコンテンツを生成するときは、一致する generatedVariableManifest を保存します。 Nudgen は、現在のマニフェストと異なる場合、または必要な宣言されたパラメータがメールにない場合、アクティベーションをブロックします。

ライフサイクルを変更する

方法	エンドポイント	認証	説明
`PATCH`	`/api/v1/campaigns/:campaignId/lifecycle`	パット	ライフタイムキャンペーンを `active`、`paused`、または `archived` に変更します。

curl -X PATCH "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/lifecycle" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"status":"active"}'

有効なトランジションは、draft → active → paused → active と active|paused → archived です。一時停止またはアーカイブすると、pending または queued のままの実行がキャンセルされ、クォータ予約が解放されます。すでに処理中の実行でも送信される可能性があります。

ナッジをトリガーする

方法	エンドポイント	認証	説明
`POST`	`/api/v1/campaigns/:campaignId/triggers`	チームトリガー API キー	1 つのイベント実行を作成し、ナッジをキューに入れます。

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/triggers" \
  -H "Authorization: Bearer $NUDGEN_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "eventId": "order_123",
  "eventName": "order.created",
  "occurredAt": "2026-08-23T10:00:00Z",
  "contact": {
    "email": "an@example.com",
    "externalId": "customer_456",
    "name": "An Nguyen",
    "phone": "+84901234567",
    "metadata": { "company": "Nudgen" }
  },
  "data": {
    "order_id": "order_123",
    "total": 490000,
    "order_url": "https://example.com/orders/order_123"
  }
}
JSON

フィールド	タイプ	必須	制限と動作
`eventId`	文字列	はい	1 ～ 128 文字。キャンペーン内の一意のべき等性キー。再試行時に再利用します。
`eventName`	文字列	いいえ	1 ～ 100 文字 (例: `order.created`)。
`occurredAt`	ISO 8601 日付時刻	いいえ	ソースイベントの時刻。
`contact.email`	メール	はい	小文字。 Nudgen は電子メールで連絡先を作成または更新します。
`contact.externalId`	文字列	いいえ	1 ～ 200 文字で、ワークスペース内の別の連絡先メールアドレスに属することはできません。
`contact.name`	文字列	いいえ	最大 200 文字。
`contact.phone`	文字列	いいえ	最大 50 文字。
`contact.metadata`	オブジェクト	いいえ	追加の連絡先プロファイルデータ。
`data`	オブジェクト	はい	`variableManifest` と一致する必要があります。最大 32 KiB。

リクエスト本文全体は 64 KiB に制限され、JSON ネストは 8 レベルに制限され、__proto__、constructor、prototype などの安全でないキーは拒否されます。新しいトリガーは、{ "execution": { "id": "...", "status": "queued" }, "duplicate": false } とともに 201 を返します。 eventId を再利用すると、200 および duplicate: true の既存の実行が返されます。

実行のリストを表示します

方法	エンドポイント	認証	説明
`GET`	`/api/v1/campaigns/:campaignId/executions`	パット	生涯キャンペーンの実行をリストします。

curl "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/executions?limit=25&status=sent&search=an@example.com" \
  -H "Authorization: Bearer $NUDGEN_PAT"

1 ～ 100 の limit (デフォルトは 25)、次のページには cursor、実行ステータスでフィルターするには status を使用します。 search は電子メールまたは外部 ID と一致します。応答には、executions と nextCursor が含まれます。

エラー、再試行、レート制限

ライフタイムトリガーでは、チームトリガー API キーごとに 1 分あたり 600 件のリクエストが許可されます。応答には、x-ratelimit-limit、x-ratelimit-remaining、および x-ratelimit-reset が含まれます。 429 応答には、Retry-After も含まれます。

ステータス	意味	どうすればいいですか
`200`	`eventId` を複製する	返された実行を使用します。再度送信しないでください。
`201`	新しい実行がキューに入れられました	ワーカーが処理するまで待ちます。
`400`	無効な JSON、本文、または基本フィールド	ペイロードを修正してください。変更せずに再試行しないでください。
`401`	キーが見つからない、無効である、取り消されている、有効期限が切れている、またはスコープが間違っている	キー構成を変更または修正します。
`402` / `403`	クォータまたはサブスクリプションにより書き込みが禁止される	クォータまたはサブスクリプションの問題を解決します。クォータエラーには、`code`、`required`、`available`、および `checkoutUrl` が含まれます。
`404`	キャンペーンが見つからないか、キーのワークスペースの外にあります。キャンペーンIDとキーを確認してください。
`409`	キャンペーンがアクティブではない/有効期間ではない、または連絡先 ID の競合	キャンペーンをアクティブ化するか、連絡先の ID を修正します。
`413`	リクエストが 64 KiB を超えています	ペイロードサイズを減らします。
`415`	`Content-Type: application/json` が見つかりません	必要なヘッダーを追加します。
`422`	`data` は変数マニフェストと一致しません。データを修正します。 `details` のパスとエラーコードを調べてください。
`429`	レート制限を超えました	`Retry-After` を待ってから、同じ `eventId` で再試行します。
`503`	実行をキューに入れることができませんでした。バックオフと同じ `eventId` を使用して再試行します。

429、503、およびネットワークエラーの場合は、指数バックオフと同じ eventId を使用して再試行してください。キュージョブの実行は決定的であるため、再試行によって重複した電子メールが作成されることはありません。

ブランド設定

方法	エンドポイント	説明
`GET`	`/api/v1/settings/brand`	ブランド名、Web サイト、送信者の電子メール、ロゴ、デザイン設定を読み取ります。
`PATCH`	`/api/v1/settings/brand`	ブランド設定を更新します。

AI ドラフト生成

方法	エンドポイント	説明
`POST`	`/api/v1/ai/generate`	キャンペーンコンテキストから電子メールの件名と HTML ドラフトを生成します。

MCP サーバー

エージェントが Model Context Protocol ツールに対応している場合は、Nudgen MCP を使用します。MCP は選択したワークスペースに紐づく OAuth 認可を使用し、新しいキャンペーンは下書きとして保存されます。チャットで送信や予約を許可すると、アシスタントが直接開始します。REST API は個人アクセストークン（PAT）を使用します。

MCP server setup

Nudgen MCP を Claude Code、Cursor、Windsurf、Codex CLI、または汎用 MCP クライアントにインストールします。

Map Leads API

有効なワークスペースのPATを使用します。新規検索は日次枠を消費しますが、追加ページと情報補完の再試行は消費しません。UTC午前0時にリセットされます。半径拡大は新規検索です。プロバイダー障害では予約枠を返却しますが、受理済み検索のキャンセルでは返却しません。 APIとMCPは既定で5 kmを使用し、整数の radiusKm 1～100を受け付けます。ダッシュボードの確認画面は表示しません。nextPageToken を pageToken に渡す際は同じ検索条件を維持してください。空のページにも次のページがある場合があります。 enrichmentPending は未完了のWebサイト調査を示します。利用可能な businessSummary と businessSources を確認してください。インポートした情報はキャンペーンの導入文の個別化に役立ちます。メールがない場合、調査が続いている可能性があります。

Method	Endpoint
`POST`	`/api/v1/map-leads/suggest`
`POST`	`/api/v1/map-leads/place`
`POST`	`/api/v1/map-leads/search`
`POST`	`/api/v1/map-leads/enrichment-retry`
`POST`	`/api/v1/map-leads/import`
`GET`	`/api/v1/map-leads/quota`
`GET`	`/api/v1/map-leads/geolocate`

curl -X POST "$NUDGEN_APP_URL/api/v1/map-leads/search" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"location":"Austin, TX","keywords":"marketing agency","radiusKm":5}'

enrichmentRetryToken がある場合、PAT 権限で POST /api/v1/map-leads/enrichment-retry に token を渡します。トークンは接続したワークスペース専用で、有効期間15分、1回限りです。インポート前に placeId で結果を統合してください。検索または再試行で Accept: application/x-ndjson を指定すると逐次結果を受信できます。各JSON行の type は progress、complete、error です。data.leads を placeId で統合し、最終的な complete.data を確定結果として使用します。エラーは error に入ります。ヘッダーなしでは通常のJSONです。POST /place は場所候補を解決し、GET /geolocate はホーチミン市の固定位置を返します。利用者の現在地は測定しません。

curl -N -X POST "$NUDGEN_APP_URL/api/v1/map-leads/search" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  --data '{"location":"Austin, TX","keywords":"marketing agency","radiusKm":5}'

curl -X POST "$NUDGEN_APP_URL/api/v1/map-leads/enrichment-retry" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data "{\"token\":\"$ENRICHMENT_RETRY_TOKEN\"}"

​概要

​これが重要な理由

​ベース URL

​認証

​パーソナル アクセス トークン

​チーム トリガー API キー

​REST エンドポイント

​ID とワークスペース

​連絡先

​ワンショット キャンペーンとドリップ キャンペーン

​ライフタイム キャンペーン

​ライフタイム キャンペーンを作成する

​ライフサイクルを変更する

​ナッジをトリガーする

​実行のリストを表示します

​エラー、再試行、レート制限

​ブランド設定

​AI ドラフト生成

​MCP サーバー

MCP server setup

​Map Leads API

概要

これが重要な理由

ベース URL

認証

パーソナルアクセストークン

チームトリガー API キー

REST エンドポイント

ID とワークスペース

連絡先

ワンショットキャンペーンとドリップキャンペーン

ライフタイムキャンペーン

ライフタイムキャンペーンを作成する

ライフサイクルを変更する

ナッジをトリガーする

実行のリストを表示します

エラー、再試行、レート制限

ブランド設定

AI ドラフト生成

MCP サーバー

Map Leads API