Developer API

Overview

The Nudgen Developer API gives scripts, internal tools, and AI agents a predictable REST interface for working with your Nudgen workspace.

PAT auth

Authenticate REST requests with a Personal Access Token.

Campaign operations

Create campaigns, schedule launches, and read delivery stats.

Agent-ready

Give Codex, Claude Code, Cursor, and custom agents structured access.

Why this matters

A PAT lets you automate real marketing workflows without sharing your dashboard session. You can create contacts, draft campaign copy, create campaigns, and schedule sends from trusted developer tools while keeping token access revocable.

Authentication

Create a Personal Access Token from Settings -> API Keys in the Nudgen dashboard. Store it securely and pass it with every request:

Authorization: Bearer <your-pat>

Example:

curl https://nudgen.net/api/v1/user/me \
  -H "Authorization: Bearer <your-pat>"

PATs are shown only once. Revoke old or exposed tokens from Settings -> API Keys.

Base URL

https://nudgen.net

Interactive API playground

Use the API Playground tab next to Guides for a Swagger-style playground. Each endpoint is generated from openapi.json, includes request and response schemas, and can prefill examples for cURL, JavaScript, and Python. Paste your PAT into the playground’s bearer token field before sending requests. Playground calls hit the live Nudgen API, so use test contacts and drafts unless you intend to create or launch real campaigns.

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.

Create a contact:

curl -X POST https://nudgen.net/api/v1/contacts/add \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "nathan@example.com",
    "name": "Nathan Nguyen",
    "tags": ["api-test"]
  }'

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 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 creating dashboard send stats.

Create a draft campaign:

curl -X POST https://nudgen.net/api/v1/campaigns \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API launch test",
    "goal": "Invite contacts to try Nudgen.",
    "subject": "Try Nudgen",
    "html": "<p>Ready to launch smarter email?</p>",
    "link": "https://nudgen.net",
    "audienceType": "manual",
    "audienceContactIds": ["contact_id"]
  }'

Schedule an existing campaign:

curl -X POST https://nudgen.net/api/v1/campaigns/campaign_id/launch \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "sendNow": false,
    "scheduledAt": "2026-05-21T06:46:52.128Z"
  }'

Send immediately by setting sendNow to true, or by creating a campaign with sendNow: true.

Launching a campaign schedules real email. Use /api/v1/campaigns/test-send for inbox previews that should not appear as launched campaigns in dashboard stats.

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.

curl -X POST https://nudgen.net/api/v1/ai/generate \
  -H "Authorization: Bearer <your-pat>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignGoal": "Write a short retention email inviting users to try Nudgen.",
    "link": "https://nudgen.net",
    "personalizationMode": "off"
  }'

MCP server

Use Nudgen MCP when your agent supports Model Context Protocol tools. MCP uses the same Personal Access Token as the REST API, 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.

Responses and errors

Successful responses return JSON. Validation errors return 400, expired or missing tokens return 401, insufficient plan access returns 403, missing resources return 404, and rate limits return 429. All data is scoped to the token owner’s active workspace.

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

Overview

PAT auth

Campaign operations

Agent-ready

Why this matters

Authentication

Base URL

Interactive API playground

REST endpoints

Identity and workspace

Contacts

Campaigns

Brand settings

AI draft generation

MCP server

MCP server setup

Responses and errors

​Overview

PAT auth

Campaign operations

Agent-ready

​Why this matters

​Authentication

​Base URL

​Interactive API playground

​REST endpoints

​Identity and workspace

​Contacts

​Campaigns

​Brand settings

​AI draft generation

​MCP server

MCP server setup

​Responses and errors

Overview

Why this matters

Authentication

Base URL

Interactive API playground

REST endpoints

Identity and workspace

Contacts

Campaigns

Brand settings

AI draft generation

MCP server

Responses and errors