---
title: Labels and filing rules API | SendHQ Docs
description: Organize sent and received mail into folders automatically or by hand.
canonical: https://sendhq.cc/docs/api-reference/labels
last-updated: 2026-09-07
---
# Labels and filing rules

Organize sent and received mail into folders automatically or by hand.

POST `/emails/:id/labels`

API key

## Add or remove labels on an email

Add and remove labels by name or lbl\_ ID. Unknown names in \`add\` are created unless \`create\` is false. An email may carry at most 10 labels.

```shell
curl https://sendhq.cc/api/v1/emails/id_value/labels \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add":["Billing"],"remove":["Support"]}'
```

```json
{
  "id": "em_…",
  "labels": [
    {
      "id": "lbl_…",
      "name": "Billing",
      "color": "#188038"
    }
  ]
}
```

GET `/labels`

API key

## List labels with message counts and filing rules

List labels with message counts and filing rules

```shell
curl https://sendhq.cc/api/v1/labels \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
```

```json
{
  "data": [],
  "count": 0,
  "mailbox": {
    "inboxUnread": 0,
    "updatesUnread": 0,
    "spamTotal": 0,
    "importantUnread": 0,
    "resortPending": 0
  }
}
```

POST `/labels`

API key

## Create a label, optionally with auto-filing rules

Create a folder-style label. Set \`skip_inbox: true\` to make it a bucket: received mail that gets this label (from a rule, from a reply to a conversation sent with the label, or added by hand) is archived so it appears only in the label, never the Inbox. Optional \`rules\` file new sent or received mail automatically: every condition set on a rule must match (inbox_id, direction, and case-insensitive from/to/subject substrings). Set \`apply_to_existing\` to file retained mail too.

```shell
curl https://sendhq.cc/api/v1/labels \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Agent/Orders","color":"#188038","skip_inbox":true,"rules":[{"inbox_id":"inb_…"}],"apply_to_existing":true}'
```

```json
{
  "id": "lbl_…",
  "name": "Agent/Orders",
  "color": "#188038",
  "skipInbox": true,
  "totalCount": 0,
  "unreadCount": 0,
  "rules": []
}
```

GET `/labels/:id`

API key

## Retrieve a label by ID or name

Retrieve a label by ID or name

```shell
curl https://sendhq.cc/api/v1/labels/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
```

```json
{
  "id": "lbl_…",
  "name": "Billing",
  "color": "#188038",
  "skipInbox": false,
  "totalCount": 0,
  "unreadCount": 0,
  "rules": []
}
```

PATCH `/labels/:id`

API key

## Rename, recolor, or turn a label into a bucket

Change \`name\`, \`color\`, or \`skip_inbox\`. Turning \`skip_inbox\` on also archives received mail already in the label unless \`apply_to_existing\` is false.

```shell
curl https://sendhq.cc/api/v1/labels/id_value \
  -X PATCH \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Finance/Billing","color":"#1a73e8","skip_inbox":true}'
```

```json
{
  "id": "lbl_…",
  "name": "Finance/Billing",
  "color": "#1a73e8",
  "skipInbox": true
}
```

DELETE `/labels/:id`

API key

## Delete a label without deleting its email

Delete a label without deleting its email

```shell
curl https://sendhq.cc/api/v1/labels/id_value \
  -X DELETE \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
```

```json
{
  "ok": true
}
```

POST `/labels/:id/rules`

API key

## Add an auto-filing rule to a label

Add an auto-filing rule to a label

```shell
curl https://sendhq.cc/api/v1/labels/id_value/rules \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direction":"in","from":"@stripe.com","subject":"invoice","skip_inbox":true,"apply_to_existing":false}'
```

```json
{
  "id": "lrule_…",
  "labelId": "lbl_…",
  "direction": "in",
  "inboxId": null,
  "from": "@stripe.com",
  "to": null,
  "subject": "invoice",
  "skipInbox": true
}
```

DELETE `/labels/:id/rules/:rule_id`

API key

## Delete an auto-filing rule

Delete an auto-filing rule

```shell
curl https://sendhq.cc/api/v1/labels/id_value/rules/rule_id_value \
  -X DELETE \
  -H "Authorization: Bearer $SENDHQ_API_KEY"
```

```json
{
  "ok": true
}
```