GET /mail/v2/categories_{id}

Return a single category by its ID, scoped to your partner. Useful for confirming a category's name and description before referencing it in a send.

Endpoint and headers

GET https://email.useinsider.com/mail/v2/categories/{id}

Request parameter

Below is the parameter required for this request.

Sample codes

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 reads one category and prints its ID, name, and description.

1. Set your API key in the INSIDER_API_KEY environment variable.

2. Copy the sample for your language into a file named get_category.py or get_category.mjs.

3. Run the file with a category ID. The sample prints a line such as 3 order_confirmation Post-purchase confirmations.

Python

Requires Python 3.8 or later and the requests package (pip install requests). Run python get_category.py 3.

"""Read one analytics category with GET /mail/v2/categories/{id}.

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 sys
import time

import requests

URL = "https://email.useinsider.com/mail/v2/categories/{id}"
# OAuth 2.0: call https://gw.useinsider.com/api/em/v2/tx/categories/{id} 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)


category_id = sys.argv[1]

response = call("GET", URL.format(id=category_id))
if response.status_code == 200:
    category = response.json()
    print(category["id"], category["name"], category.get("description", ""))
elif response.status_code == 404:
    print("No category with this ID exists for your account.")
else:
    print(f"Request failed ({response.status_code}): {response.text[:300]}")

Node.js

Requires Node.js 18 or later. No packages are needed. Run node get_category.mjs 3.

// Read one analytics category with GET /mail/v2/categories/{id}.
// 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/{id}";
// OAuth 2.0: call https://gw.useinsider.com/api/em/v2/tx/categories/{id} 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 categoryId = process.argv[2];

const response = await call("GET", URL.replace("{id}", categoryId));
if (response.status === 200) {
  const category = await response.json();
  console.log(category.id, category.name, category.description ?? "");
} else if (response.status === 404) {
  console.log("No category with this ID exists for your account.");
} else {
  console.error(`Request failed (${response.status}): ${(await response.text()).slice(0, 300)}`);
}

Sample response

Below is a sample response for this request.

{
  "id": 3,
  "name": "order_confirmation",
  "description": "Post-purchase confirmations",
  "created_at": "2026-06-29T10:00:00Z"
}

Keep in mind

• A non-positive ID returns 400 invalid_id.

• An ID that does not exist for the partner returns 404 not_found.

For all error codes, refer to the Error Codes.