---
title: Labels and buckets | SendHQ Docs
description: File sent and received mail into labels automatically, and give an agent a bucket its conversations never leave.
canonical: https://sendhq.cc/docs/labels
last-updated: 2026-09-07
---
# Labels and buckets

File sent and received mail into labels automatically, and give an agent a bucket its conversations never leave.

## Labels

A label works like a Gmail folder. A message can carry up to 10 labels, and a workspace can have 200. Create one with `POST /labels`, list them with message and unread counts with `GET /labels`, and read one with `GET /emails?label=Billing`. Labels can be referenced by name or `lbl_` ID everywhere.

## Send into a label

```json
{
  "from": "Orders <orders@example.com>",
  "to": [
    "customer@example.net"
  ],
  "subject": "Order 1042",
  "text": "Reply with a delivery window.",
  "labels": [
    "Agent/Orders"
  ]
}
```

Unknown label names are created. Every later message in the conversation, including the customer's replies, inherits the conversation's labels.

## Buckets

Create a label with `"skip_inbox": true` to make it a bucket. Received mail that gets a bucket label, from a filing rule, a reply to a labelled conversation, or `POST /emails/:id/labels`, is archived so it appears only in the label and never in the Inbox. Sent mail never appears in the Inbox. Together, an agent's task conversations stay in one place in both directions.

```json
{
  "name": "Agent/Orders",
  "skip_inbox": true,
  "rules": [
    {
      "inbox_id": "inb_…"
    }
  ],
  "apply_to_existing": true
}
```

## Filing rules

Rules file new mail automatically. Every condition set on a rule must match: `inbox_id` (the receiving address), `direction` (`in` or `out`), and case-insensitive substrings of `from`, `to` (To and Cc), and `subject`. A rule's own `skip_inbox` archives only the received mail it matches. Add rules with `POST /labels/:id/rules`; `apply_to_existing` files retained mail too.

## Work a bucket

Poll `GET /emails?label=Agent%2FOrders&direction=in&unread=true`, read the conversation with `GET /threads/:id`, reply with `reply_to_email_id`, then mark handled with `PATCH /emails/:id` `{"read": true}`. Move a message in or out with `POST /emails/:id/labels` `{"add": [...], "remove": [...]}`. The MCP server exposes the same operations as `create_label`, `create_label_rule`, `label_email`, and `list_emails`.