NetSendo REST-API-Referenz

Überblick

Die API ist Teil jeder NetSendo-Installation, bei SILVER wie bei GOLD. Sie läuft auf deinem eigenen Server unter https://your-domain.com/api/v1, spricht JSON und arbeitet mit dem Konto, dem der API-Schlüssel gehört. Der MCP-Server und der n8n-Node nutzen dieselben Endpunkte. Die wenigen Aufrufe für GOLD-Funktionen, etwa A/B-Tests, antworten ohne aktive GOLD-Lizenz mit 402.

Sende bei jeder Anfrage Authorization: Bearer mit deinem Schlüssel und Accept: application/json, damit Validierungsfehler als JSON zurückkommen, bei Anfragen mit Body außerdem Content-Type: application/json.

Schlüssel prüfen

GET /api/v1/account liefert das Konto hinter dem Schlüssel und die NetSendo-Version. Integrationen nutzen den Endpunkt für den Verbindungstest.

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

Authentifizierung und API-Schlüssel

Schlüssel erstellst du im NetSendo-Panel unter Einstellungen → API-Schlüssel. Gib jedem Schlüssel einen Namen, wähle seine Scopes und bei Bedarf ein Ablaufdatum. Der Schlüssel wird nur einmal angezeigt, beim Erstellen; NetSendo speichert nur seinen SHA-256-Hash und hält fest, wann er zuletzt verwendet wurde.

Schlüssel bestehen aus ns_live_, gefolgt von 32 zufälligen Zeichen. Übergib den Schlüssel im Header Authorization als Bearer-Token. Schlüssel im Query-String werden nicht akzeptiert.

Authorization: Bearer ns_live_YOUR_KEY

Aktiviere beim Schlüssel die Option MCP-Schlüssel, damit der integrierte MCP-Verbindungstest ihn verwenden kann. Wie du KI-Assistenten anbindest, steht in der Dokumentation zum MCP-Server.

Wenn die Authentifizierung fehlschlägt

Die API antwortet mit 401 und einer dieser Meldungen:

• 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

Jeder Schlüssel hat eine Reihe von Scopes. Ein Endpunkt, der einen Scope verlangt, den der Schlüssel nicht hat, antwortet mit 403 Forbidden.

• Ein Schreib-Scope umfasst den Lese-Scope derselben Ressource: Ein Schlüssel mit lists:write kann auch Endpunkte aufrufen, die lists:read verlangen.
• Ein Schlüssel, bei dessen Erstellung kein Scope ausgewählt wurde, erhält alle 16 Scopes.
• Endpunkte, die in den Tabellen unten mit jeder gültige Schlüssel markiert sind, prüfen nur, ob der Schlüssel gültig und nicht abgelaufen ist. Dazu gehört das Auflisten und Lesen von Abonnenten, Listen, Tags, benutzerdefinierten Feldern, Kampagnen, Funnels, A/B-Tests und Webhooks. Jeder Endpunkt liefert nur die Daten des Kontos, dem der Schlüssel gehört.

Rate Limits

Die API erlaubt 3.000 Anfragen pro Minute und API-Schlüssel. Routen ohne Schlüssel (die Endpunkte für die Listenanmeldung und der signierte Export-Download) werden pro IP-Adresse mit demselben Limit gezählt.

Antworten enthalten X-RateLimit-Limit und X-RateLimit-Remaining. Über dem Limit antwortet die API mit 429 Too Many Requests und dem Header Retry-After in Sekunden.

Nutze für große Aufgaben die Batch-Endpunkte statt vieler Einzelaufrufe: bis zu 1.000 Abonnenten pro POST /subscribers/batch, 5.000 Zeilen pro Import und 5.000 Kontakte pro Mitgliedschaftsoperation.

Fehler

Fehler sind JSON-Objekte mit einem kurzen Label error und einer lesbaren message:

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

Validierungsfehler nutzen das Standardformat von Laravel: eine message und ein Objekt errors mit einem Array von Meldungen pro Feld. Sende Accept: application/json; ohne diesen Header kann eine fehlgeschlagene Validierung mit einer Weiterleitung statt mit JSON antworten.

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

Seit NetSendo 2.4.0 antworten Aufrufe für GOLD-Funktionen ohne aktive GOLD-Lizenz (kein Schlüssel, SILVER oder abgelaufenes GOLD) mit 402 Payment Required. Die Antwort nennt die abgelehnte Funktion; message ist in der Standardsprache der Instanz (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

Endpunkte, die Sammlungen zurückgeben, liefern standardmäßig Seiten mit 25 Einträgen (Tags: 50). Die Größe änderst du mit per_page, die Seite mit page. Die Antwort enthält die Einträge in data, Seitenlinks in links und Zähler wie current_page, per_page und total in meta. Der direkte Listenexport paginiert stattdessen mit einem Cursor: Übergib limit (höchstens 5.000) und, solange has_more true ist, den zurückgegebenen next_cursor.

Endpunkte

Alle Pfade unten sind relativ zu deiner Instanz, zum Beispiel https://your-domain.com/api/v1/subscribers. Ersetze die Teile in geschweiften Klammern durch IDs aus deinem Konto. Mit GOLD markierte Zeilen brauchen eine aktive GOLD-Lizenz und antworten ohne sie mit 402; die Beschreibungen der Gruppen nennen die Aufrufe, die GOLD nur für bestimmte Werte brauchen.

• Konto und Verbindungstest
• Abonnenten
• Kontaktlisten
• Import und Export
• Listenhygiene
• Listenmitgliedschaft (Massenaktionen)
• Aktivität und Engagement
• Sperrliste
• Tags und benutzerdefinierte Felder
• E-Mail-Versand
• SMS-Versand
• Kampagnen (messages)
• A/B-Tests
• Funnels
• Automatisierungsregeln
• Webhooks
• Vorlagen und gespeicherte Blöcke
• System-E-Mails und Systemseiten
• Anmeldeformulare
• Benachrichtigungen
• Hilfs-Endpunkte für Integrationen
• NetSendo Brain
• Endpunkte für die Listenanmeldung

Beispiele

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-Spezifikation in deiner Instanz

Jede NetSendo-Installation erzeugt außerdem eine OpenAPI-Beschreibung ihrer API. Melde dich im Panel an und öffne https://your-domain.com/docs/api für die interaktive Referenz oder /docs/api.json für die reine Spezifikation. Beide sind nur für angemeldete Benutzer sichtbar.

Häufige Fragen

Weitere Dokumentation

• Webhooks: Ereignisse, Payloads und Signaturprüfung
• MCP-Server: dieselbe API für Claude, Cursor und VS Code
• Schnellstart: NetSendo mit Docker installieren