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"
  }
}

{
  "success": false,
  "error": "A label with that name already exists"
}

Delete a custom label

DELETE/mail/api/labels

Pass the label id as a query parameter. Built-in labels (builtIn: true) cannot be deleted — attempting to do so returns HTTP 403.

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 }

{
  "success": false,
  "error": "Built-in labels cannot be deleted"
}

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