개발자 API

개요

Nudgen Developer API는 스크립트, 내부 도구 및 AI 에이전트에 작업공간에 대한 예측 가능한 REST 인터페이스를 제공합니다. 개인 액세스 토큰(PAT)을 사용하여 작업 공간 리소스를 관리합니다. 팀 트리거 API 키는 백엔드에서 평생 캠페인을 트리거하는 데에만 사용하세요.

이것이 중요한 이유

대시보드 세션을 공유하지 않고도 마케팅 및 이벤트 기반 유지 워크플로를 자동화할 수 있습니다. PAT는 작업공간 관리를 취소 가능하게 유지하는 반면, 좁은 팀 트리거 키를 사용하면 프로덕션 서비스가 광범위한 작업공간 액세스 없이 이벤트 트리거 넛지를 보낼 수 있습니다.

기본 URL

환경에 대한 앱 URL을 한 번 설정하고 모든 예시에서 사용하세요. 프로덕션에서는 일반적으로 https://app.nudgen.net를 사용합니다. 로컬 개발에서는 일반적으로 http://localhost:3000를 사용합니다.

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

인증

개인 액세스 토큰

설정 → API 키에서 PAT를 생성하세요. 연락처, 캠페인 관리, 브랜드 설정, AI 생성에 사용하세요.

Authorization: Bearer $NUDGEN_PAT

PAT는 한 번만 표시됩니다. 안전하게 저장하고 설정 → 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가 정확히 한 번만 포함됩니다. 서버 측 비밀 관리자에 저장하세요. 이후 응답에서는 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를 사용하세요.

평생 캠페인

평생 캠페인은 이벤트로 트리거됩니다. 허용된 각 트리거는 최대 한 번의 실행을 생성하고 제공된 연락처에 한 번의 넛지를 보냅니다. 대시보드 워크플로 및 가변 계약 지침은 평생 캠페인 사용을 참조하세요.

평생 캠페인 만들기

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 키	하나의 이벤트 실행을 생성하고 넛지를 대기열에 넣습니다.

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`와 일치해야 합니다. 최대 32KiB.

전체 요청 본문은 64KiB로 제한되고 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 키에 대해 분당 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`	캠페인이 활성 상태가 아니거나 평생이 아니거나 연락처 신원이 충돌합니다	캠페인을 활성화하거나 연락처 신원을 수정하세요.
`413`	요청이 64KiB를 초과합니다	페이로드 크기를 줄이세요.
`415`	`Content-Type: application/json` 누락	필요한 헤더를 추가합니다.
`422`	`data`가 변수 매니페스트와 일치하지 않습니다.	데이터를 수정하세요. `details`에서 경로 및 오류 코드를 검사하세요.
`429`	속도 제한이 초과되었습니다	`Retry-After`를 기다린 후 동일한 `eventId`로 다시 시도하세요.
`503`	실행을 대기열에 추가할 수 없습니다.	백오프 및 동일한 `eventId`를 사용하여 재시도하세요.

429, 503 및 네트워크 오류의 경우 지수 백오프 및 동일한 eventId를 사용하여 다시 시도하세요. 대기열 작업은 실행에 대해 결정적이므로 재시도로 인해 중복 이메일이 생성되지 않습니다.

브랜드 설정

방법	엔드포인트	설명
`GET`	`/api/v1/settings/brand`	브랜드 이름, 웹사이트, 보낸 사람 이메일, 로고, 디자인 설정을 읽어보세요.
`PATCH`	`/api/v1/settings/brand`	브랜드 설정을 업데이트하세요.

AI 초안 생성

방법	엔드포인트	설명
`POST`	`/api/v1/ai/generate`	캠페인 컨텍스트에서 이메일 제목과 HTML 초안을 생성합니다.

MCP 서버

에이전트가 Model Context Protocol 도구를 지원하는 경우 Nudgen MCP를 사용하세요. MCP는 작업공간 관리 API와 동일한 PAT를 사용하지만 기존 HTTP 엔드포인트 대신 Nudgen을 에이전트 호출 가능 도구로 노출합니다.

MCP server setup

Claude Code, Cursor, Windsurf, Codex CLI 또는 일반 MCP 클라이언트에 Nudgen MCP를 설치하세요.

시작하기

연락처

캠페인

브랜드

대시보드

설정

결제

제휴

Agents

리드 이메일 파인더 (확장 프로그램)

서명 생성기

스팸 검사기

이메일 도달성 진단

개념

문제 해결

보안 및 개인 정보

법적 고지

개요

이것이 중요한 이유

기본 URL

인증

개인 액세스 토큰

팀 트리거 API 키

REST 엔드포인트

ID 및 작업공간

연락처

원샷 및 드립 캠페인

평생 캠페인

평생 캠페인 만들기

수명 주기 변경

넛지 트리거

실행 목록

오류, 재시도 및 비율 제한

브랜드 설정

AI 초안 생성

MCP 서버

MCP server setup

​개요

​이것이 중요한 이유

​기본 URL

​인증

​개인 액세스 토큰

​팀 트리거 API 키

​REST 엔드포인트

​ID 및 작업공간

​연락처

​원샷 및 드립 캠페인

​평생 캠페인

​평생 캠페인 만들기

​수명 주기 변경

​넛지 트리거

​실행 목록

​오류, 재시도 및 비율 제한

​브랜드 설정

​AI 초안 생성

​MCP 서버

MCP server setup

개요

이것이 중요한 이유

기본 URL

인증

개인 액세스 토큰

팀 트리거 API 키

REST 엔드포인트

ID 및 작업공간

연락처

원샷 및 드립 캠페인

평생 캠페인

평생 캠페인 만들기

수명 주기 변경

넛지 트리거

실행 목록

오류, 재시도 및 비율 제한

브랜드 설정

AI 초안 생성

MCP 서버