Categories group transactional emails for analytics, so you can report on sends by type (order confirmation, password reset, and so on). Register a category once, then reference it by its integer ID in the category field of a send.
Endpoint and headers
POST https://email.useinsider.com/mail/v2/categories
Header | Value | Purpose |
|---|---|---|
X-INS-AUTH-KEY | API token, format INS.{id}.{secret} | Authentication |
Content-Type | application/json | Request format |
Body parameters
Below are the body parameters for this request.
Parameter | Description | Data type | Required |
|---|---|---|---|
name | Lowercase, matching ^[a-z0-9][a-z0-9_-]{0,63}$. Unique per partner. Immutable. | String | Yes |
description | Free-form, up to 255 characters. Immutable. | String | No |
Body example
Below is a sample body for this request
{
"name": "order_confirmation",
"description": "Post-purchase confirmations"
}Sample response
A successful create returns 201 with the new category and its ID.
{
"id": 3,
"name": "order_confirmation",
"description": "Post-purchase confirmations",
"created_at": "2026-06-29T10:00:00Z"
}Keep in mind
Categories are append-only. Once an ID is issued, it is referenced by historical logs and analytics, so the name and description cannot be changed, and it cannot be deleted. To retire a category, simply stop using it.
A partner can hold up to 100 categories.
For the reporting view, refer to Transactional Email Analytics. For error codes such as category_exists and category_limit_reached, refer to the Error Codes.