Return every category registered for your partner, so you can look up the integer ID to use in the category field of a send.
Endpoint and headers
Header | Value | Purpose |
|---|---|---|
X-INS-AUTH-KEY | API token, format INS.{id}.{secret} | Authentication |
This request has no body.
Code samples
This endpoint takes no request body, so the samples only set the headers and read the response.
These samples are provided as is, as a starting point for your integration. Insider One does not guarantee that they work in every environment, so test them in your own environment before you use them in production.
Each sample lists every category for your account, one per line.
Set your API key in the INSIDER_API_KEY environment variable.
Copy the sample for your language into a file named list_categories.py or list_categories.mjs.
Run the file. Each line shows a category's ID, name, and description, such as 3 order_confirmation Post-purchase confirmations.
Python
Requires Python 3.8 or later and the requests package (pip install requests). Run python list_categories.py.
"""List your analytics categories with GET /mail/v2/categories.
Sample code, provided as is. Test it in your own environment before you use it in production.
Requires Python 3.8+ and the requests package: pip install requests
"""
import os
import time
import requests
URL = "https://email.useinsider.com/mail/v2/categories"
# OAuth 2.0: call https://gw.useinsider.com/api/em/v2/tx/categories with "Authorization: Bearer {token}" instead.
HEADERS = {"X-INS-AUTH-KEY": os.environ["INSIDER_API_KEY"], "Content-Type": "application/json"}
def call(method, url, payload=None, retries=3):
"""Send the request. On 429 or 5xx, wait and retry up to `retries` times."""
for attempt in range(retries + 1):
response = requests.request(method, url, json=payload, headers=HEADERS, timeout=30)
if (response.status_code != 429 and response.status_code < 500) or attempt == retries:
return response
wait = float(response.headers.get("Retry-After", 2 ** attempt)) # 1, 2, 4 s without Retry-After
print(f"HTTP {response.status_code}: retrying in {wait:.0f}s")
time.sleep(wait)
response = call("GET", URL)
if response.status_code != 200:
raise SystemExit(f"List failed ({response.status_code}): {response.text[:300]}")
for category in response.json()["categories"]: # Ordered by ID, with no pagination
print(category["id"], category["name"], category.get("description", ""))Node.js
Requires Node.js 18 or later. No packages are needed. Run node list_categories.mjs.
// List your analytics categories with GET /mail/v2/categories.
// Sample code, provided as is. Test it in your own environment before you use it in production.
// Requires Node.js 18+ (built-in fetch). No dependencies.
const URL = "https://email.useinsider.com/mail/v2/categories";
// OAuth 2.0: call https://gw.useinsider.com/api/em/v2/tx/categories with "Authorization: Bearer {token}" instead.
const HEADERS = { "X-INS-AUTH-KEY": process.env.INSIDER_API_KEY, "Content-Type": "application/json" };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// Send the request. On 429 or 5xx, wait and retry up to `retries` times.
async function call(method, url, payload, retries = 3) {
for (let attempt = 0; ; attempt++) {
const response = await fetch(url, {
method,
headers: HEADERS,
body: payload === undefined ? undefined : JSON.stringify(payload),
signal: AbortSignal.timeout(30000),
});
if ((response.status !== 429 && response.status < 500) || attempt === retries) return response;
const wait = Number(response.headers.get("Retry-After") ?? 2 ** attempt); // 1, 2, 4 s without Retry-After
console.warn(`HTTP ${response.status}: retrying in ${wait}s`);
await sleep(wait * 1000);
}
}
const response = await call("GET", URL);
if (response.status !== 200) {
throw new Error(`List failed (${response.status}): ${(await response.text()).slice(0, 300)}`);
}
for (const category of (await response.json()).categories) { // Ordered by ID, with no pagination
console.log(category.id, category.name, category.description ?? "");
}Sample response
Below is a sample response for this request.
{
"categories": [
{
"id": 3,
"name": "order_confirmation",
"description": "Post-purchase confirmations",
"created_at": "2026-06-29T10:00:00Z"
},
{
"id": 7,
"name": "password_reset",
"description": "Account security emails",
"created_at": "2026-06-29T10:05:00Z"
}
]
}Keep in mind
Results are ordered by ID in ascending order, with no pagination.
A customer with no categories returns { "categories": [] }.
To create a category, refer to POST /mail/v2/categories. For error codes, refer to the Error Codes.