Dokumentacja REST API NetSendo

Przegląd

API jest częścią każdej instalacji NetSendo, zarówno SILVER, jak i GOLD. Działa na Twoim własnym serwerze pod adresem https://your-domain.com/api/v1, posługuje się formatem JSON i działa na koncie, do którego należy klucz API. Serwer MCP i node n8n korzystają z tych samych endpointów. Nieliczne wywołania obsługujące funkcje GOLD, na przykład testy A/B, bez aktywnej licencji GOLD zwracają 402.

W każdym żądaniu wysyłaj Authorization: Bearer ze swoim kluczem i Accept: application/json, żeby błędy walidacji wracały jako JSON, a w żądaniach z treścią także Content-Type: application/json.

Sprawdź swój klucz

GET /api/v1/account zwraca konto powiązane z kluczem i wersję NetSendo. Integracje używają go do testu połączenia.

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

Uwierzytelnianie i klucze API

Klucze tworzysz w panelu NetSendo w sekcji Ustawienia → Klucze API. Nadaj każdemu kluczowi nazwę, wybierz jego zakresy i, jeśli chcesz, datę wygaśnięcia. Klucz jest pokazywany tylko raz, przy tworzeniu; NetSendo przechowuje wyłącznie jego skrót SHA-256 i zapisuje, kiedy był ostatnio użyty.

Klucz zaczyna się od ns_live_, po którym następują 32 losowe znaki. Przekazuj go w nagłówku Authorization jako token Bearer. Klucze w parametrach adresu URL nie są przyjmowane.

Authorization: Bearer ns_live_YOUR_KEY

Zaznacz przy kluczu opcję Klucz MCP, aby mógł go używać wbudowany test połączenia MCP. Podłączanie asystentów AI opisuje dokumentacja serwera MCP.

Gdy uwierzytelnianie się nie powiedzie

API odpowiada kodem 401 z jednym z tych komunikatów:

• 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

Zakresy

Każdy klucz ma zestaw zakresów. Endpoint, który wymaga zakresu, jakiego klucz nie ma, odpowiada 403 Forbidden.

• Zakres zapisu obejmuje zakres odczytu tego samego zasobu: klucz z lists:write może też wywoływać endpointy wymagające lists:read.
• Klucz utworzony bez zaznaczenia żadnego zakresu otrzymuje wszystkie 16 zakresów.
• Endpointy oznaczone w tabelach poniżej jako dowolny ważny klucz sprawdzają tylko, czy klucz jest ważny i nie wygasł. Należą do nich listowanie i odczyt subskrybentów, list, tagów, pól własnych, kampanii, lejków, testów A/B i webhooków. Każdy endpoint zwraca wyłącznie dane konta, do którego należy klucz.

Limity żądań

API przyjmuje 3000 żądań na minutę na klucz API. Trasy bez klucza (endpointy zapisu na listę i pobieranie eksportu przez podpisany link) są liczone według adresu IP z tym samym limitem.

Odpowiedzi zawierają nagłówki X-RateLimit-Limit i X-RateLimit-Remaining. Po przekroczeniu limitu API odpowiada 429 Too Many Requests z nagłówkiem Retry-After podającym czas w sekundach.

Przy dużych zadaniach używaj endpointów zbiorczych zamiast wielu pojedynczych wywołań: do 1000 subskrybentów na jedno wywołanie POST /subscribers/batch, 5000 wierszy na import i 5000 kontaktów na operację na członkostwie.

Błędy

Błędy to obiekty JSON z krótką etykietą error i czytelnym komunikatem message:

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

Błędy walidacji mają standardowy format Laravela: message oraz obiekt errors z tablicą komunikatów dla każdego pola. Wysyłaj Accept: application/json; bez tego nagłówka nieudana walidacja może zwrócić przekierowanie zamiast JSON-a.

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

Od NetSendo 2.4.0 wywołania obsługujące funkcje GOLD bez aktywnej licencji GOLD (brak klucza, SILVER albo GOLD po terminie) zwracają 402 Payment Required. Odpowiedź mówi, której funkcji odmówiono; message jest w domyślnym języku instancji (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"
}

Paginacja

Endpointy zwracające zbiory elementów domyślnie dzielą je na strony po 25 (tagi: po 50). Rozmiar strony zmienisz parametrem per_page, a stronę wybierzesz parametrem page. Odpowiedź zawiera elementy w data, linki do stron w links i liczniki, takie jak current_page, per_page i total, w meta. Eksport listy zwracany wprost w odpowiedzi stronicuje za to kursorem: przekaż limit (maksymalnie 5000) i, dopóki has_more ma wartość true, zwrócony next_cursor.

Endpointy

Wszystkie ścieżki poniżej są względne wobec Twojej instancji, na przykład https://your-domain.com/api/v1/subscribers. Części w nawiasach klamrowych zastąp identyfikatorami ze swojego konta. Wiersze oznaczone GOLD wymagają aktywnej licencji GOLD i bez niej zwracają 402; opisy grup wymieniają wywołania, które wymagają GOLD tylko dla niektórych wartości.

• Konto i test połączenia
• Subskrybenci
• Listy kontaktów
• Import i eksport
• Higiena listy
• Członkostwo na listach (zbiorczo)
• Aktywność i zaangażowanie
• Lista blokad
• Tagi i pola własne
• Wysyłka e-maili
• Wysyłka SMS-ów
• Kampanie (messages)
• Testy A/B
• Lejki
• Reguły automatyzacji
• Webhooki
• Szablony i zapisane bloki
• Wiadomości i strony systemowe
• Formularze zapisu
• Powiadomienia
• Endpointy pomocnicze dla integracji
• NetSendo Brain
• Endpointy zapisu na listę

Przykłady

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

Specyfikacja OpenAPI w Twojej instancji

Każda instalacja NetSendo generuje też opis swojego API w formacie OpenAPI. Zaloguj się do panelu i otwórz https://your-domain.com/docs/api, aby zobaczyć interaktywną dokumentację, lub /docs/api.json, aby pobrać surową specyfikację. Oba adresy widzą tylko zalogowani użytkownicy.

Najczęściej zadawane pytania

Powiązana dokumentacja

• Webhooki: zdarzenia, payloady i weryfikacja podpisu
• Serwer MCP: to samo API dla Claude, Cursora i VS Code
• Szybki start: instalacja NetSendo w Dockerze