Skip to main content

​
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

MethodEndpointDescription
GET/api/v1/user/meGet the authenticated user.
GET/api/v1/teamsList workspaces available to the token owner.

​
Contacts

MethodEndpointDescription
GET/api/v1/contactsList contacts with page, limit, search, tags, and status filters.
POST/api/v1/contacts/addCreate a contact.
GET/api/v1/contacts/:idGet a contact.
PATCH/api/v1/contacts/:idUpdate a contact.
DELETE/api/v1/contacts/:idDelete 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

MethodEndpointDescription
GET/api/v1/campaignsList campaigns in the active workspace.
POST/api/v1/campaignsCreate a campaign draft or scheduled campaign.
GET/api/v1/campaigns/:idGet campaign details.
PUT/api/v1/campaigns/:idUpdate an existing campaign.
POST/api/v1/campaigns/:id/launchLaunch now or schedule a campaign.
GET/api/v1/campaigns/:id/statsGet delivery, open, click, bounce, and complaint stats.
GET/api/v1/campaigns/:id/progressGet campaign sending progress.
GET/api/v1/campaigns/:id/recipientsList campaign recipients.
POST/api/v1/campaigns/test-sendSend 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

MethodEndpointDescription
GET/api/v1/settings/brandRead brand name, website, sender email, logo, and design settings.
PATCH/api/v1/settings/brandUpdate brand settings.

​
AI draft generation

MethodEndpointDescription
POST/api/v1/ai/generateGenerate 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.