Send a broadcast

POST/api/v2/lists/:id/broadcast

Creates a campaign and queues it straight away; returns 202.

Needs an API key with the newsletter scope. Scopes

Parameters

Path

idstringrequired

The list id.

Body

subjectstringrequired

Subject line.

body_htmlstringrequired

HTML body.

body_textstring

Plain-text body. Generated from the HTML when omitted.

preheaderstring

Preview text shown after the subject in most inboxes.

from_namestring

Sender name. Defaults to the list's.

from_addressstring

Sender address. Defaults to the list's; required if the list has none.

Notes

Each subscriber gets their own copy with an unsubscribe link and header, open tracking and tracked links.
In the body, the merge variables {{name}}, {{first_name}}, {{first_name|fallback}}, {{email}} and {{unsubscribe_url}} are filled in per recipient (the subject is sent as written).
from_address and from_name default to the list's.

curl -X POST "https://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/broadcast" \
  -H "Authorization: Bearer $KOLTRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "What shipped in October",
  "body_html": "<p>Hi {{first_name|there}},</p><p>This month we shipped…</p>",
  "body_text": "Hi {{first_name|there}}, this month we shipped…",
  "preheader": "Faster search and a new inbox"
}'

const res = await fetch("https://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/broadcast", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOLTRIX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "subject": "What shipped in October",
    "body_html": "<p>Hi {{first_name|there}},</p><p>This month we shipped…</p>",
    "body_text": "Hi {{first_name|there}}, this month we shipped…",
    "preheader": "Faster search and a new inbox"
  }),
});

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/broadcast",
    headers={
        "Authorization": f"Bearer {os.environ['KOLTRIX_API_KEY']}",
    },
    json={
        "subject": "What shipped in October",
        "body_html": "<p>Hi {{first_name|there}},</p><p>This month we shipped…</p>",
        "body_text": "Hi {{first_name|there}}, this month we shipped…",
        "preheader": "Faster search and a new inbox"
    },
)
print(res.status_code, res.json())

package main

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

func main() {
	body := strings.NewReader(`{
  "subject": "What shipped in October",
  "body_html": "<p>Hi {{first_name|there}},</p><p>This month we shipped…</p>",
  "body_text": "Hi {{first_name|there}}, this month we shipped…",
  "preheader": "Faster search and a new inbox"
}`)
	req, _ := http.NewRequest("POST", "https://api.koltrix.com/api/v2/lists/0b3c6d2e-91f4-4a7b-8c5d-2e3f4a5b6c7d/broadcast", 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/broadcast");
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([
        "subject" => "What shipped in October",
        "body_html" => "<p>Hi {{first_name|there}},</p><p>This month we shipped…</p>",
        "body_text" => "Hi {{first_name|there}}, this month we shipped…",
        "preheader" => "Faster search and a new inbox",
    ]),
]);

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

Accepted and queued.

{
  "campaign_id": "1d2c3b4a-5f6e-4d7c-8b9a-0f1e2d3c4b5a",
  "status": "queued",
  "message": "Broadcast enqueued — recipients will be fanned out by the worker."
}

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

{
  "error": "subject and body_html required"
}

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

subjectstringrequired

body_htmlstringrequired

body_textstring

preheaderstring

from_namestring

from_addressstring

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/broadcast

Output

What comes back

The response appears here.
Press Send request.