SDK / API ReferenceThreads
Update Thread Labels
PATCH /v0/threads/:threadId
Scope: mail:manage
Add or remove labels on a thread. Thread labels are separate from message labels — use them for user-applied tags like starred, important, archived, or any custom label.
Request
Thread-level label updates require the REST endpoint. The SDKs only support per-message labels via loomal.mail.updateLabels(messageId, ...) — see Update Labels.
curl -X PATCH https://api.loomal.ai/v0/threads/thd_a3f91b00c4e2d7e8 \
-H "Authorization: Bearer loid-your-api-key" \
-H "Content-Type: application/json" \
-d '{"addLabels":["starred","follow-up"],"removeLabels":["snoozed"]}'Body
{
"addLabels": ["starred", "follow-up"],
"removeLabels": ["snoozed"]
}| Field | Type | Description |
|---|---|---|
addLabels | string[] | Labels to add to the thread |
removeLabels | string[] | Labels to remove from the thread |
At least one of addLabels or removeLabels must be provided.
Response — 200 OK
{
"threadId": "thd_a3f91b00c4e2d7e8",
"inboxId": "agent-x8k2m@mailgent.dev",
"subject": "Question about pricing",
"labels": ["starred", "follow-up"],
"createdAt": "2026-03-28T10:00:00.000Z",
"updatedAt": "2026-04-06T14:00:00.000Z"
}Errors
| Status | Code | Description |
|---|---|---|
400 | bad_request | No labels provided, or invalid body |
404 | not_found | Thread not found |
Common Patterns
# Star a thread
{"addLabels": ["starred"]}
# Unstar
{"removeLabels": ["starred"]}
# Mark important
{"addLabels": ["important"]}
# Add a custom label
{"addLabels": ["customer-feedback"]}
# Replace one label with another
{"addLabels": ["archived"], "removeLabels": ["inbox"]}