Labels

Labels are string tags you can attach to messages and threads. They provide a flexible way to categorize, filter, and track the status of email conversations. Unlike folders, a message or thread can have multiple labels simultaneously.

Key properties

Labels are plain strings (e.g., "urgent", "needs-review", "customer-vip")
Labels are automatically normalized to lowercase
Both messages and threads can have labels (independently)
Labels are stored as arrays with GIN indexing for efficient filtering

Adding labels

// Add labels to a message
await client.messages.addLabels('msg_def456', {
  labels: ['support-ticket', 'priority-high', 'billing'],
});

// Add labels to a thread
await client.threads.addLabels('thr_ghi789', {
  labels: ['escalated', 'awaiting-response'],
});

# Add labels to a message
client.messages.add_labels(
    message_id="msg_def456",
    labels=["support-ticket", "priority-high", "billing"],
)

# Add labels to a thread
client.threads.add_labels(
    thread_id="thr_ghi789",
    labels=["escalated", "awaiting-response"],
)

# Add labels to a message
curl -X POST https://api.agent-post.dev/api/v1/messages/msg_def456/labels \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["support-ticket", "priority-high", "billing"]}'

# Add labels to a thread
curl -X POST https://api.agent-post.dev/api/v1/threads/thr_ghi789/labels \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["escalated", "awaiting-response"]}'

Removing labels

await client.messages.removeLabels('msg_def456', {
  labels: ['priority-high'],
});

client.messages.remove_labels(
    message_id="msg_def456",
    labels=["priority-high"],
)

curl -X DELETE https://api.agent-post.dev/api/v1/messages/msg_def456/labels \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["priority-high"]}'

Filtering by label

List messages or threads that have a specific label:

// Find all messages labeled "needs-review"
const messages = await client.messages.list('inb_abc123', {
  label: 'needs-review',
});

// Find escalated threads
const threads = await client.threads.list('inb_abc123', {
  label: 'escalated',
});

messages = client.messages.list(
    inbox_id="inb_abc123",
    label="needs-review",
)

threads = client.threads.list(
    inbox_id="inb_abc123",
    label="escalated",
)

# Filter messages by label
curl "https://api.agent-post.dev/api/v1/inboxes/inb_abc123/messages?label=needs-review" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

# Filter threads by label
curl "https://api.agent-post.dev/api/v1/inboxes/inb_abc123/threads?label=escalated" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Batch label operations

Apply labels to multiple messages at once:

await client.labels.batch({
  target_type: 'message',
  target_ids: ['msg_aaa111', 'msg_bbb222', 'msg_ccc333'],
  add_labels: ['processed', 'q1-2026'],
  remove_labels: ['needs-review'],
});

client.labels.batch(
    target_type="message",
    target_ids=["msg_aaa111", "msg_bbb222", "msg_ccc333"],
    add_labels=["processed", "q1-2026"],
    remove_labels=["needs-review"],
)

curl -X POST https://api.agent-post.dev/api/v1/labels/batch \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type": "message",
    "target_ids": ["msg_aaa111", "msg_bbb222", "msg_ccc333"],
    "add_labels": ["processed", "q1-2026"],
    "remove_labels": ["needs-review"]
  }'

Label discovery

Discover all labels currently in use across your organization:

const labels = await client.labels.list();
// Returns all unique labels across messages and threads
console.log(labels);
// => ["billing", "escalated", "needs-review", "priority-high", "processed", "support-ticket"]

labels = client.labels.list()
print(labels)
# => ["billing", "escalated", "needs-review", "priority-high", "processed", "support-ticket"]

curl "https://api.agent-post.dev/api/v1/labels" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Auto-disappearing labels

The label discovery endpoint dynamically scans messages and threads for unique labels. If you remove a label from all messages and threads, it automatically disappears from the discovery results. There is no separate label management -- labels exist only as data on messages and threads.

Message labels vs thread labels

Labels on messages and threads are independent:

Adding a label to a message does not add it to the message's thread
Adding a label to a thread does not add it to the thread's messages
You can use different labeling strategies for each (e.g., status labels on threads, content labels on messages)

Common patterns

Status tracking:

new --> in-progress --> resolved --> archived

Priority classification:

priority-low, priority-medium, priority-high, priority-urgent

Agent workflow:

needs-classification --> classified --> needs-response --> responded

Tips

All labels are normalized to lowercase. "URGENT" and "urgent" are the same label.
Use consistent naming conventions (kebab-case recommended: needs-review, not NeedsReview)
Labels are stored with PostgreSQL GIN indexes, so filtering by label is efficient even with large datasets
There is no limit on the number of labels per message or thread
Labels are free-form strings -- define your own taxonomy to fit your workflow

Labels

On this page