---
title: "List a mailbox's labels"
canonical: "https://bird.com/docs/api/reference/list-mailbox-labels"
---

# List a mailbox's labels

`GET /v1/email/mailboxes/{mailbox_id}/labels`

Returns the labels available in a mailbox. First, the built-in system
labels:

- The placements `inbox`, `archive`, `spam`, `blocked`, and `sent`.
- `trash`.
- `unread`.

Then, every custom label currently in use on its conversations and
messages. Apply and remove labels through the conversation and message
update endpoints. These actions also create and remove custom labels. A
custom label exists while at least one message or conversation uses it.

## Code samples

**TypeScript**

```ts
const labels = await bird.email.mailboxes.labels("mbx_01abc");
console.log(labels.data.map((label) => label.name));
```

Examples: [TypeScript](/docs/api/reference/list-mailbox-labels.ts.md) · [Python](/docs/api/reference/list-mailbox-labels.py.md) · [Go](/docs/api/reference/list-mailbox-labels.go.md) · [PHP](/docs/api/reference/list-mailbox-labels.php.md) · [CLI](/docs/api/reference/list-mailbox-labels.cli.md) · [MCP](/docs/api/reference/list-mailbox-labels.mcp.md) · [cURL](/docs/api/reference/list-mailbox-labels.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "name": "inbox",
      "type": "system"
    }
  ]
}
```

## Path parameters

- `mailbox_id` (string): Mailbox identifier. Starts with `mbx_`.

## Response body

- `data` (array of object, required)
- `data.name` (string, required): The label name, as it appears on conversations and messages.
- `data.type` (string, required)

  `system` labels are the built-in placements a message can be in:

  - Inbox.
  - Archive.
  - Spam.
  - Blocked.
  - Sent.
  - Trash.
  - Unread.

  `custom` labels are the workspace's own tags.

  Possible values: `system`, `custom`

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)