Developer API

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.

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 the same PAT as workspace management APIs, but exposes Nudgen as agent-callable tools instead of conventional HTTP endpoints.

MCP server setup

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

Getting started

Contacts

Campaigns

Brand

Dashboard

Settings

Billing

Affiliate

Agents

Lead Email Finder (Extension)

Signature Generator

Spam Checker

Email Deliverability Audit

Concepts

Troubleshooting & FAQ

Security & privacy

Legal

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

Brand settings

AI draft generation

MCP server

MCP server setup

​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

​Brand settings

​AI draft generation

​MCP server

MCP server setup

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

Brand settings

AI draft generation

MCP server