SDK / API ReferenceMessages
Update Labels
PATCH /v0/messages/:messageId
Scope: mail:manage
Add or remove labels on a message.
Request
import { Loomal } from "@loomal/sdk";
const loomal = new Loomal({ apiKey: process.env.LOOMAL_API_KEY! });
const message = await loomal.mail.updateLabels("<abc123@gmail.com>", {
addLabels: ["read", "processed"],
removeLabels: ["unread"],
});import os
from loomal import Loomal
loomal = Loomal(api_key=os.environ["LOOMAL_API_KEY"])
message = loomal.mail.update_labels(
"<abc123@gmail.com>",
add_labels=["read", "processed"],
remove_labels=["unread"],
)loomal mail labels '<abc123@gmail.com>' \
--add read,processed \
--remove unreadAt least one of --add or --remove must be provided.
mail.update_labels(message_id, add_labels?, remove_labels?)Available through @loomal/mcp — see MCP setup.
curl -X PATCH https://api.loomal.ai/v0/messages/%3Cabc123%40gmail.com%3E \
-H "Authorization: Bearer loid-your-api-key" \
-H "Content-Type: application/json" \
-d '{"addLabels":["read","processed"],"removeLabels":["unread"]}'Body
{
"addLabels": ["read", "processed"],
"removeLabels": ["unread"]
}| Field | Type | Description |
|---|---|---|
addLabels | string[] | Labels to add |
removeLabels | string[] | Labels to remove |
Both fields are optional but at least one should be provided.
Response — 200 OK
{
"messageId": "<abc123@gmail.com>",
"threadId": "thd_a3f91b00c4e2d7e8",
"inboxId": "agent-x8k2m@mailgent.dev",
"from": ["sender@example.com"],
"to": ["agent-x8k2m@mailgent.dev"],
"cc": [],
"subject": "Question about pricing",
"text": "Hi, I had a question...",
"extractedText": "Hi, I had a question...",
"labels": ["received", "read", "processed"],
"createdAt": "2026-03-28T12:00:00.000Z"
}Common Patterns
# Mark as read
{"addLabels": ["read"], "removeLabels": ["unread"]}
# Flag as important
{"addLabels": ["important"]}
# Archive
{"addLabels": ["archived"]}
# Mark as processed by agent
{"addLabels": ["processed"], "removeLabels": ["unread"]}