Labels are tags you apply to emails in the MisarMail inbox to keep your dashboard organized. MisarMail ships with four built-in labels and lets you create unlimited custom labels.

Labels apply to inbox emails only — they are not related to contacts, campaigns, or segments.

Authentication

All label endpoints use session (cookie-based) authentication. They are intended for dashboard use and do not accept API keys.

Built-in labels

These labels exist for every account and cannot be deleted.

ID	Name	Color
`personal`	Personal	`bg-blue-500`
`work`	Work	`bg-green-500`
`important`	Important	`bg-red-500`
`newsletters`	Newsletters	`bg-green-500`

Built-in labels are returned with "builtIn": true in every list response.

List labels

GET/mail/api/labels

Returns built-in and custom labels merged into a single array.

Response fields

labelsArray<Label>

Built-in and custom labels. Each label includes id, name, color, and builtIn.

curl https://api.misar.io/mail/api/labels \
  -H "Cookie: session=..."

{
  "labels": [
    { "id": "personal",     "name": "Personal",     "color": "bg-blue-500",  "builtIn": true },
    { "id": "work",         "name": "Work",          "color": "bg-green-500", "builtIn": true },
    { "id": "important",    "name": "Important",     "color": "bg-red-500",   "builtIn": true },
    { "id": "newsletters",  "name": "Newsletters",   "color": "bg-green-500", "builtIn": true },
    { "id": "lbl_01hvabc",  "name": "Suppliers",     "color": "bg-orange-500","builtIn": false },
    { "id": "lbl_01hvdef",  "name": "Support queue", "color": "bg-primary","builtIn": false }
  ]
}

Create a custom label

POST/mail/api/labels

Create a custom label for your account.

Request body

namestringbodyrequired

1–50 characters. Must be unique for this account.

colorstringbodydefault: bg-gray-500

Tailwind background class.

Response fields

labelobject

The created label, including id, name, color, and created_at.

curl -X POST https://api.misar.io/mail/api/labels \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Suppliers", "color": "bg-orange-500" }'

{
  "label": {
    "id": "lbl_01hvabc",
    "name": "Suppliers",
    "color": "bg-orange-500",
    "created_at": "2026-05-27T10:00:00Z"
  }
}

{ "error": "Label already exists" }

Delete a custom label

DELETE/mail/api/labels

Pass the label id as a query parameter. Only custom labels stored on your account are deleted; passing a built-in ID (personal, work, important, newsletters) matches no row and is a harmless no-op that still returns { "success": true }.

Query parameters

idstringqueryrequired

ID of the custom label to delete.

Response fields

successboolean

true when the label was deleted.

curl -X DELETE "https://api.misar.io/mail/api/labels?id=lbl_01hvabc" \
  -H "Cookie: session=..."

{ "success": true }

{ "error": "id is required" }

Deleting a label removes it from all emails it was applied to. This action is immediate and cannot be undone.

Status codes

Code	Meaning
`200`	Label listed or deleted
`201`	Custom label created
`400`	Validation failed, or `id` missing on delete
`401`	Not authenticated
`409`	A label with that name already exists