NetSendo REST API reference

Overview

The API is part of every NetSendo installation, SILVER and GOLD alike. It runs on your own server under https://your-domain.com/api/v1, speaks JSON, and acts on the account that owns the API key. The MCP server and the n8n node use the same endpoints. The few calls that drive GOLD features, such as A/B tests, answer 402 without an active GOLD licence.

Send Authorization: Bearer with your key on every request, Content-Type: application/json with a body, and Accept: application/json so that validation errors come back as JSON.

Check your key

GET /api/v1/account returns the account behind the key and the NetSendo version. Integrations use it to test a connection.

curl https://your-domain.com/api/v1/account \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Accept: application/json"

# 200 OK
{
  "data": {
    "id": 1,
    "name": "Anna Admin",
    "email": "admin@example.com",
    "version": "2.7.0"
  }
}

Authentication and API keys

Create keys in the NetSendo panel under Settings → API Keys. Give each key a name, pick its scopes and, if you want, an expiry date. The key is shown once, when you create it; NetSendo stores only its SHA-256 hash and records when it was last used.

Keys look like ns_live_ followed by 32 random characters. Pass the key in the Authorization header as a Bearer token. Query-string keys are not accepted.

Authorization: Bearer ns_live_YOUR_KEY

Mark a key as MCP Key to use it with Claude, Cursor or VS Code; the panel's MCP connection test uses that key. See the MCP server documentation for connecting AI assistants.

When authentication fails

The API answers 401 with one of these messages:

• Missing or invalid Authorization header. Use: Bearer <api_key>
• Invalid API key format. Key should start with ns_live_
• Invalid API key
• API key has expired

Scopes

Each key carries a set of scopes. An endpoint that needs a scope the key lacks answers 403 Forbidden.

• A write scope includes the read scope of the same resource: a key with lists:write can also call endpoints that need lists:read.
• A key created without any scope selected receives all 16 scopes.
• Endpoints marked any valid key in the tables below check only that the key is valid and not expired. They include listing and reading subscribers, lists, tags, custom fields, campaigns, funnels, A/B tests and webhooks. Every endpoint returns only the data of the key's own account.

Rate limits

The API allows 3,000 requests per minute per API key. Routes without a key (the list subscription endpoints and the signed export download) are counted per IP address with the same limit.

Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit the API answers 429 Too Many Requests with a Retry-After header in seconds.

For large jobs use the batch endpoints instead of many single calls: up to 1,000 subscribers per POST /subscribers/batch, 5,000 rows per import and 5,000 contacts per membership operation.

Errors

Errors are JSON objects with a short error label and a readable message:

{
  "error": "Forbidden",
  "message": "API key does not have subscribers:write permission"
}

Validation errors use the standard Laravel format, a message plus an errors object with one array of messages per field. Send Accept: application/json; without it a failed validation may answer with a redirect instead of JSON.

{
  "message": "The email field must be a valid email address.",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

Since NetSendo 2.4.0 the calls that drive GOLD features answer 402 Payment Required without an active GOLD licence (no key, SILVER, or GOLD past its expiry). The body says which feature was refused; message is in the default language of the instance (APP_LOCALE):

{
  "error": "Payment Required",
  "code": "gold_required",
  "message": "“A/B tests” requires the GOLD licence. Upgrade on the Licence page to use it.",
  "feature": "ab_tests",
  "required_plan": "GOLD",
  "upgrade_url": "https://your-domain.com/license"
}

Pagination

List endpoints return pages of 25 items by default (50 for tags). Change the size with per_page and move with page. The response has the items in data, page links in links and counts such as current_page, per_page and total in meta. The inline list export pages with a cursor instead: pass limit (at most 5,000) and, while has_more is true, the returned next_cursor.

Endpoints

All paths below are relative to your instance, for example https://your-domain.com/api/v1/subscribers. Replace the parts in braces with IDs from your account. Rows marked GOLD need an active GOLD licence and answer 402 without one; group descriptions name the calls that need GOLD only for some values.

• Account and connection test
• Subscribers
• Contact lists
• Import and export
• List hygiene
• List membership (bulk)
• Activity and engagement
• Suppression list
• Tags and custom fields
• Email sending
• SMS sending
• Campaigns (messages)
• A/B tests
• Funnels
• Automation rules
• Webhooks
• Templates and saved blocks
• System emails and system pages
• Subscription forms
• Notifications
• Integration helpers
• NetSendo Brain
• List subscription endpoints

Examples

curl -X POST https://your-domain.com/api/v1/subscribers \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "anna@example.com",
    "contact_list_id": 5,
    "first_name": "Anna",
    "tags": [1, 3],
    "custom_fields": { "city": "Berlin" }
  }'

# 201 Created (200 when the address already existed)
{
  "data": {
    "id": 456,
    "email": "anna@example.com",
    "first_name": "Anna",
    "status": "active",
    "contact_list_id": 5,
    "contact_list_ids": [5],
    "source": "api",
    "tags": [{ "id": 1, "name": "VIP", ... }, { "id": 3, "name": "Newsletter", ... }],
    "custom_fields": { "email": "anna@example.com", "fname": "Anna", ..., "city": "Berlin" },
    "subscribed_at": "2026-11-07T10:30:00.000000Z",
    "created_at": "2026-11-07T10:30:00.000000Z",
    ...
  }
}

curl -X POST https://your-domain.com/api/v1/email/send \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "anna@example.com",
    "subject": "Your order is on its way",
    "content": "<p>Hi [[fname]], your order has shipped.</p>",
    "subscriber_id": 456,
    "mailbox_id": 1
  }'

# 202 Accepted
{
  "data": {
    "id": 123,
    "email": "anna@example.com",
    "subject": "Your order is on its way",
    "status": "queued",
    "mailbox": "Main mailbox",
    "scheduled_at": null
  },
  "message": "Email queued successfully"
}

# 1. Create a draft email campaign for list 5
curl -X POST https://your-domain.com/api/v1/messages \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subject": "November news",
    "channel": "email",
    "type": "broadcast",
    "content": "<h1>Hello [[fname]]</h1>",
    "contact_list_ids": [5],
    "mailbox_id": 1
  }'

# 2a. Send it now (42 = the id returned in step 1)
curl -X POST https://your-domain.com/api/v1/messages/42/send \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Accept: application/json"

# 2b. Or schedule it in a given time zone
curl -X POST https://your-domain.com/api/v1/messages/42/schedule \
  -H "Authorization: Bearer ns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "scheduled_at": "2026-11-20 09:00", "timezone": "Europe/Warsaw" }'

const res = await fetch(
  "https://your-domain.com/api/v1/subscribers?status=active&per_page=50",
  {
    headers: {
      Authorization: `Bearer ${process.env.NETSENDO_API_KEY}`,
      Accept: "application/json",
    },
  }
)

if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After") ?? 60)
  // try again after `wait` seconds
}

const { data, meta } = await res.json()
console.log(meta.total, data.map((s) => s.email))

curl -X POST https://your-domain.com/api/v1/lists/5/subscribe \
  -H "Authorization: Bearer YOUR_LIST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "email": "anna@example.com", "first_name": "Anna" }'

# 201 Created
{
  "success": true,
  "message": "Successfully subscribed",
  "subscriber_id": 456,
  "status": "new"
}

OpenAPI specification in your instance

Every NetSendo installation also generates an OpenAPI description of its API. Sign in to the panel and open https://your-domain.com/docs/api for the interactive reference, or /docs/api.json for the raw specification. Both are visible only to signed-in users.

Frequently asked questions

Related documentation

• Webhooks: events, payloads and signature verification
• MCP server: the same API for Claude, Cursor and VS Code
• Quick start: install NetSendo with Docker