Developer API - Nudgen

Overview

The Nudgen Developer API gives scripts, internal tools, and AI agents a predictable REST interface for your workspace. Use a Personal Access Token (PAT) to manage workspace resources. Use a Team trigger API key only to trigger a Lifetime campaign from your backend.

Why this matters

You can automate marketing and event-driven retention workflows without sharing a dashboard session. PATs keep workspace management revocable, while a narrow Team trigger key lets a production service send an event-triggered nudge without broad workspace access.

Base URL

Set the app URL for your environment once and use it in every example. Production commonly uses https://app.nudgen.net; local development commonly uses http://localhost:3000.

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

Authentication

Personal Access Token

Create a PAT in Settings → API Keys. Use it for contacts, campaign management, brand settings, and AI generation.

Authorization: Bearer $NUDGEN_PAT

PATs are shown only once. Store them securely and revoke any old or exposed token from Settings → API Keys.

Team trigger API key

A Team trigger API key starts with ndg_team_ and has the narrow campaigns:trigger scope. It can trigger Lifetime campaigns only; a PAT cannot trigger them. Only workspace owners and admins can create, rotate, or revoke these keys. By default, a key expires after 90 days. Set expiresInDays to null to create a non-expiring key.

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}'

The 201 response contains the plaintext key exactly once. Save it in a server-side secret manager. Later responses expose only keyPrefix.

Method	Endpoint	Description
`POST`	`/api/v1/settings/team-api-keys`	Create a Team trigger API key.
`GET`	`/api/v1/settings/team-api-keys`	List Team trigger API keys.
`POST`	`/api/v1/settings/team-api-keys/:id`	Rotate an active, unexpired key.
`DELETE`	`/api/v1/settings/team-api-keys/:id`	Revoke a key.

REST endpoints

Identity and workspace

Method	Endpoint	Description
`GET`	`/api/v1/user/me`	Get the authenticated user.
`GET`	`/api/v1/teams`	List workspaces available to the token owner.

Contacts

Method	Endpoint	Description
`GET`	`/api/v1/contacts`	List contacts with `page`, `limit`, `search`, `tags`, and `status` filters.
`POST`	`/api/v1/contacts/add`	Create a contact.
`GET`	`/api/v1/contacts/:id`	Get a contact.
`PATCH`	`/api/v1/contacts/:id`	Update a contact.
`DELETE`	`/api/v1/contacts/:id`	Delete a contact.

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"]}'

One-shot and drip campaigns

Method	Endpoint	Description
`GET`	`/api/v1/campaigns`	List campaigns in the active workspace.
`POST`	`/api/v1/campaigns`	Create a campaign draft or scheduled campaign.
`GET`	`/api/v1/campaigns/:id`	Get campaign details.
`PUT`	`/api/v1/campaigns/:id`	Update an existing campaign.
`POST`	`/api/v1/campaigns/:id/launch`	Launch now or schedule a one-shot or drip campaign.
`GET`	`/api/v1/campaigns/:id/stats`	Get delivery, open, click, bounce, and complaint stats.
`GET`	`/api/v1/campaigns/:id/progress`	Get campaign sending progress.
`GET`	`/api/v1/campaigns/:id/recipients`	List campaign recipients.
`POST`	`/api/v1/campaigns/test-send`	Send a test email without dashboard send stats.

Launching a campaign schedules real email. Use /api/v1/campaigns/test-send for inbox previews.

Lifetime campaigns

Lifetime campaigns are event-triggered: each accepted trigger creates at most one execution and sends one nudge to the supplied contact. See Use Lifetime campaigns for the dashboard workflow and variable-contract guidance.

Create a Lifetime campaign

Create Lifetime campaigns as draft. Do not send sendNow: true, status: "active", or status: "scheduled"; activate the campaign with its lifecycle endpoint instead.

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 defines up to 100 data.* variables. It must include every data.* token used in the subject or HTML. Defaults must match the declared type, and a variable used in an HTML href must have type url. When you generate email content, save the matching generatedVariableManifest. Nudgen blocks activation if it differs from the current manifest or if required declared parameters are absent from the email.

Change the lifecycle

Method	Endpoint	Authentication	Description
`PATCH`	`/api/v1/campaigns/:campaignId/lifecycle`	PAT	Change a Lifetime campaign to `active`, `paused`, or `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"}'

Valid transitions are draft → active → paused → active and active|paused → archived. Pausing or archiving cancels executions that are still pending or queued and releases their quota reservations. An execution already being processed may still send.

Trigger a nudge

Method	Endpoint	Authentication	Description
`POST`	`/api/v1/campaigns/:campaignId/triggers`	Team trigger API key	Create one event execution and queue a nudge.

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

Field	Type	Required	Limits and behavior
`eventId`	string	Yes	1–128 characters. Unique idempotency key within the campaign; reuse it for retries.
`eventName`	string	No	1–100 characters, for example `order.created`.
`occurredAt`	ISO 8601 datetime	No	Time of the source event.
`contact.email`	email	Yes	Lowercased. Nudgen creates or updates the contact by email.
`contact.externalId`	string	No	1–200 characters and cannot belong to another contact email in the workspace.
`contact.name`	string	No	Up to 200 characters.
`contact.phone`	string	No	Up to 50 characters.
`contact.metadata`	object	No	Additional contact profile data.
`data`	object	Yes	Must match `variableManifest`; maximum 32 KiB.

The whole request body is limited to 64 KiB, JSON nesting to eight levels, and unsafe keys such as __proto__, constructor, and prototype are rejected. A new trigger returns 201 with { "execution": { "id": "...", "status": "queued" }, "duplicate": false }. Reusing an eventId returns the existing execution with 200 and duplicate: true.

List executions

Method	Endpoint	Authentication	Description
`GET`	`/api/v1/campaigns/:campaignId/executions`	PAT	List Lifetime campaign executions.

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

Use limit from 1–100 (default 25), cursor for the next page, status to filter by execution status, and search to match an email or external ID. The response includes executions and nextCursor.

Errors, retries, and rate limits

Lifetime triggers allow 600 requests per minute for each Team trigger API key. Responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset. A 429 response also includes Retry-After.

Status	Meaning	What to do
`200`	Duplicate `eventId`	Use the returned execution; do not send again.
`201`	New execution queued	Wait for the worker to process it.
`400`	Invalid JSON, body, or basic field	Correct the payload; do not retry unchanged.
`401`	Missing, invalid, revoked, expired, or wrongly scoped key	Rotate or correct the key configuration.
`402` / `403`	Quota or subscription prevents writes	Resolve the quota or subscription issue. Quota errors include `code`, `required`, `available`, and `checkoutUrl`.
`404`	Campaign is missing or outside the key’s workspace	Check the campaign ID and key.
`409`	Campaign is not active/not Lifetime, or contact identity conflicts	Activate the campaign or correct the contact identity.
`413`	Request exceeds 64 KiB	Reduce the payload size.
`415`	Missing `Content-Type: application/json`	Add the required header.
`422`	`data` does not match the variable manifest	Correct the data; inspect `details` for paths and error codes.
`429`	Rate limit exceeded	Wait for `Retry-After`, then retry with the same `eventId`.
`503`	Execution could not be enqueued	Retry with backoff and the same `eventId`.

For 429, 503, and network errors, retry with exponential backoff and the same eventId. The queue job is deterministic for an execution, so retries do not create duplicate email.

Sending domains

Owners and admins on an active paid plan can manage one custom sending domain per workspace. The API reference includes list, add, edit, verify, choose default sender, remove, and resume-sending endpoints under /api/v1/settings/sending-domains. Every request requires a teamId query parameter that matches the PAT owner’s active workspace. Adding a domain does not verify it; publish the DNS records returned by the list endpoint and call the verification endpoint before selecting it as the default sender.

Brand settings

Method	Endpoint	Description
`GET`	`/api/v1/settings/brand`	Read brand name, website, sender email, logo, and design settings.
`PATCH`	`/api/v1/settings/brand`	Update brand settings.

AI draft generation

Method	Endpoint	Description
`POST`	`/api/v1/ai/generate`	Generate an email subject and HTML draft from campaign context.

MCP server

Use Nudgen MCP when your agent supports Model Context Protocol tools. MCP uses OAuth sign-in tied to a selected workspace; PATs remain for the REST API. MCP campaign creation saves a draft, and each launch requires separate browser approval.

MCP server setup

Install Nudgen MCP in Claude Code, Cursor, Windsurf, Codex CLI, or a generic MCP client.

Map Leads API

Use a PAT for the active workspace. New searches consume the daily search quota; pagination and enrichment retries do not. Quota resets at midnight UTC. An explicit larger radius starts a new search. Provider failures release a reserved search; cancelling an accepted search does not. API and MCP searches default to 5 km and accept an explicit integer radiusKm from 1 to 100. They do not show the dashboard confirmation dialog. Keep the same search inputs when passing nextPageToken as pageToken; a page can contain no matching leads and still have another page. Contact enrichment may finish after businesses first appear. enrichmentPending marks unfinished website research. Review businessSummary and businessSources when available; imported business context can support personalized campaign introductions. A missing email can mean research is still pending.

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}'

If enrichmentRetryToken is present, call POST /api/v1/map-leads/enrichment-retry with token to retry pending website research. It requires PAT, is bound to the connected workspace, expires after 15 minutes, and can be used once. Merge returned leads by placeId before importing. Set Accept: application/x-ndjson on search or enrichment retry for incremental results. Each line is JSON: type is progress, complete, or error. Merge leads in data.leads by placeId. Use the final complete.data as the authoritative result; errors use error. Without this header, the response is ordinary JSON. POST /place resolves a location suggestion, not a business contact record. GET /geolocate returns a fixed Ho Chi Minh City fallback; it does not determine your location.

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\"}"

​Overview

​Why this matters

​Base URL

​Authentication

​Personal Access Token

​Team trigger API key

​REST endpoints

​Identity and workspace

​Contacts

​One-shot and drip campaigns

​Lifetime campaigns

​Create a Lifetime campaign

​Change the lifecycle

​Trigger a nudge

​List executions

​Errors, retries, and rate limits

​Sending domains

​Brand settings

​AI draft generation

​MCP server

MCP server setup

​Map Leads API

Overview

Why this matters

Base URL

Authentication

Personal Access Token

Team trigger API key

REST endpoints

Identity and workspace

Contacts

One-shot and drip campaigns

Lifetime campaigns

Create a Lifetime campaign

Change the lifecycle

Trigger a nudge

List executions

Errors, retries, and rate limits

Sending domains

Brand settings

AI draft generation

MCP server

Map Leads API