Add a subscriber

POST/api/v2/lists/:id/subscribers

Returns 201 with the subscriber.

Needs an API key with the newsletter scope. Scopes

Parameters

Path

idstringrequired

The list id.

Body

emailstringrequired

The address. Stored lower-cased.

namestring

The person's name, used by the name merge variables in broadcasts.

tagsarray

Array of strings.

Notes

Adding an email that is already on the list updates its name instead of failing; someone who unsubscribed stays unsubscribed.
On a list that requires double opt-in the subscriber starts as pending.

curl -X POST "https://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/subscribers" \
  -H "Authorization: Bearer $KOLTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "tags": [
    "beta"
  ]
}'

const res = await fetch("https://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/subscribers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOLTRIX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "[email protected]",
    "name": "Ada Lovelace",
    "tags": [
      "beta"
    ]
  }),
});

console.log(res.status, await res.json());

import os, requests

res = requests.post(
    "https://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/subscribers",
    headers={
        "Authorization": f"Bearer {os.environ['KOLTRIX_API_KEY']}",
    },
    json={
        "email": "[email protected]",
        "name": "Ada Lovelace",
        "tags": [
            "beta"
        ]
    },
)
print(res.status_code, res.json())

package main

import (
	"strings"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := strings.NewReader(`{
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "tags": [
    "beta"
  ]
}`)
	req, _ := http.NewRequest("POST", "https://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/subscribers", body)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KOLTRIX_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}

<?php

$ch = curl_init("https://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/subscribers");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("KOLTRIX_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "email" => "[email protected]",
        "name" => "Ada Lovelace",
        "tags" => [
            "beta",
        ],
    ]),
]);

$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $response;

Created.

{
  "id": "9d8c7b6a-5f4e-4d3c-b2a1-0f9e8d7c6b5a",
  "list_id": "0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d",
  "email": "[email protected]",
  "name": "Ada Lovelace",
  "status": "active",
  "unsubscribe_token": "4f9a0c1d2e3b4a5f6c7d8e9f0a1b2c3d",
  "tags": [
    "beta"
  ],
  "created_at": "2026-10-02T10:14:33Z",
  "updated_at": "2026-10-02T10:14:33Z"
}

A required field is missing or invalid. The text names the problem.

{
  "error": "invalid email: …"
}

The API key is missing, malformed, unknown or revoked.

{
  "error": "invalid or revoked api key"
}

The key is valid but does not have the newsletter scope.

{
  "error": "missing permission: newsletter"
}

More than 60 requests a minute on this key. Wait Retry-After seconds. No code field.

Retry-After: 60

{
  "error": "rate limit exceeded — 60 requests per minute per API key"
}

Try it below with your own key. Every sample reads the key from KOLTRIX_API_KEY.

Try it

Send this request from your browser.

Input

What you send

API key

Stays in this browser tab (sessionStorage) and goes only to api.koltrix.com. Create one under Settings → API keys.

Requests are real and this one changes data in your workspace. Koltrix has no test mode, so use a dedicated key with only the permissions you need and revoke it when you are done.

idstringrequired

emailstringrequired

namestring

tagsarray

Request body · JSON

Valid JSON. The fields above and this editor stay in sync.

POSThttps://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/subscribers

Output

What comes back

The response appears here.
Press Send request.