---
title: "Add labels to an inbox message"
method: POST
path: "/email_inboxes/{inbox_id}/messages/{message_id}/labels"
tags: ["Email Inboxes"]
---

# Add labels to an inbox message

`POST /email_inboxes/{inbox_id}/messages/{message_id}/labels`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/email_inboxes/{inbox_id}/messages/{message_id}/labels`
- Auth: HTTP bearer

Adds one or more mutable labels to a message. Labels carry agent
workflow state such as `spam`, `needs_review`, or `processed`.

Labels are **not** the same as the send-time `tags` on outbound
messages: `tags` are immutable and propagate to Email Detail Records
and Mission Control for billing attribution, while labels are mailbox
state that never reaches the reporting contract.

The operation is an idempotent set union — adding a label the message
already carries is a no-op and still returns 200. Labels are
case-sensitive, and message labels are independent of thread labels.

## Path parameters

- `inbox_id` string, uuid, required
- `message_id` string, uuid, required

## Request body

- LabelMutationRequest: Labels to add or remove. Both operations are idempotent set operations, so a retried request converges instead of failing.
  - `labels` string[], required: One or more labels. Each label is a freeform, case-sensitive string of at most 255 characters; a message or thread may carry at most 50 labels. The `telnyx:` prefix is a reserved system namespace and is rejected on customer writes.

## Response `200`

The updated message, including its current label set.

- InboundMessageResponse
  - `data` InboundMessage, required
    - `id` string, uuid, required
    - `record_type` 'email_message', required
    - `direction` 'inbound', required
    - `status` 'received', required: Received for inbound messages; the current send status for outbound messages.
    - `inbox_id` string, uuid, required
    - `thread_id` string, uuid, required
    - `message_id` string, nullable, required: RFC Message-ID header. Null is possible for legacy outbound messages.
    - `in_reply_to` string, nullable, required
    - `references` string[], required: Ordered RFC Message-ID values from the References header.
    - `from` InboundEmailAddress, required
      - `email` string, email, required
      - `name` string
    - `to` InboundEmailAddress[], required
      - `email` string, email, required
      - `name` string
    - `cc` InboundEmailAddress[], required
      - `email` string, email, required
      - `name` string
    - `bcc` InboundEmailAddress[], required
      - `email` string, email, required
      - `name` string
    - `reply_to` InboundEmailAddress[], required
      - `email` string, email, required
      - `name` string
    - `subject` string, nullable, required
    - `text_body_url` string, uri, nullable, required: URL for an offloaded plain-text body. Null means the body is not offloaded to a URL; an inline plain-text body may still exist but is not returned on list reads. `reply_text` and `has_quoted_text` are persisted during ingest before any body offload.
    - `html_body_url` string, uri, nullable, required: URL for an offloaded HTML body. Null means the body is not offloaded to a URL; an inline HTML body may still exist but is not returned on list reads. Reply extraction uses only the plain-text body during ingest.
    - `reply_text` string, nullable, required: Conservatively extracted new-reply content persisted from the plain-text body during ingest. Null means no plain-text extraction input was available or extraction was skipped or failed; HTML bodies are not parsed.
    - `has_quoted_text` boolean, required: Whether conservative plain-text extraction detected a quoted tail. False does not prove that the source contains no quoted content.
    - `headers` object, required
    - `inline_files` object[], required
    - `attachments` object[], required
    - `labels` string[], required: Mutable message labels used for agent workflow state (for example `spam`, `needs_review`, `processed`). Distinct from the immutable send-time `tags` on outbound messages: labels are never propagated to Email Detail Records or Mission Control reporting. Always empty for outbound messages. Labels on a message are independent of the labels on its thread.
    - `read_at` string, date-time, nullable, required: Time the inbound message was marked read. Null means unread.
    - `received_at` string, date-time, nullable, required: Receipt time for inbound messages; null for outbound messages.
    - `sent_at` string, date-time, nullable, required: Creation/send-acceptance time for outbound messages; null for inbound messages.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `401`: Not authorized (10006).
- `404`: Resource not found (10001).
- `422`: Validation Failed (10015) or changeset validation error.
- `503`: Inbound label storage is temporarily unavailable.

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-09-22** `9621f6123ebc`: 8 warning
  - added the new `10011` enum value to the `errors/items/code` response property for the response status `401`
  - added the new `10011` enum value to the `errors/items/code` response property for the response status `404`
  - added the new `10011` enum value to the `errors/items/code` response property for the response status `422`
  - added the new `10011` enum value to the `errors/items/code` response property for the response status `503`
  - …4 more
- **2026-07-28** `b1bf96d8391e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/email_inboxes/:inbox_id/messages/:message_id/labels/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)