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.

Endpoints

Method	Path	Description
`GET`	`/api/labels`	List all labels (built-in + custom)
`POST`	`/api/labels`	Create a custom label
`DELETE`	`/api/labels?id=:id`	Delete a custom label

List labels

GET /api/labels

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

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

const res = await fetch("https://api.misar.io/mail/api/labels", {
  credentials: "include",
});
const { labels } = await res.json();

Response

{
  "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-purple-500","builtIn": false }
  ]
}

Create a custom label

POST /api/labels

Field	Type	Required	Description
`name`	string	Yes	1–50 characters. Must be unique for this account.
`color`	string	No	Tailwind background class. Defaults to `bg-gray-500`.

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

const res = await fetch("https://api.misar.io/mail/api/labels", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Suppliers", color: "bg-orange-500" }),
});
const { label } = await res.json();

Response

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

Error — duplicate name

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

Returns HTTP 409 Conflict.

Delete a custom label

DELETE /api/labels?id=:id

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

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

await fetch("https://api.misar.io/mail/api/labels?id=lbl_01hvabc", {
  method: "DELETE",
  credentials: "include",
});

Response

{ "success": true }

Error — built-in label

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

Returns HTTP 403 Forbidden.

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