> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add labels to an inbox message

> 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.




## OpenAPI

````yaml /openapi/generated/email/inboxes.yml post /email_inboxes/{inbox_id}/messages/{message_id}/labels
openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: API for managing email inboxes, drafts, messages, filters, and threads.
  title: Telnyx Email Inboxes API
  version: 2.0.0
servers:
  - url: https://api.telnyx.com/v2
security:
  - bearerAuth: []
paths:
  /email_inboxes/{inbox_id}/messages/{message_id}/labels:
    post:
      tags:
        - Email Inboxes
      summary: Add labels to an inbox message
      description: |
        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.
      operationId: AddEmailInboxMessageLabels
      parameters:
        - $ref: '#/components/parameters/InboxIdPathParam'
        - $ref: '#/components/parameters/MessageIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelMutationRequest'
            example:
              labels:
                - spam
                - urgent
      responses:
        '200':
          $ref: '#/components/responses/InboundMessageLabelResponse'
        '401':
          $ref: '#/components/responses/email_UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/email_NotFoundResponse'
        '422':
          $ref: '#/components/responses/ValidationErrorResponse'
        '503':
          $ref: '#/components/responses/LabelServiceUnavailableResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Telnyx from 'telnyx';


            const client = new Telnyx({
              apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.emailInboxes.messages.labels.create('inbox_id', 'message_id',
            {
              labels: [],
            });


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from telnyx import Telnyx

            client = Telnyx(
                api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
            )
            response = client.email_inboxes.messages.labels.create(
                inbox_id="inbox_id",
                message_id="message_id",
                labels=[],
            )
            print(response.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tlabel, err := client.EmailInboxes.Messages.Labels.New(\n\t\tcontext.TODO(),\n\t\t\"inbox_id\",\n\t\t\"message_id\",\n\t\ttelnyx.EmailInboxeMessageLabelNewParams{\n\t\t\tLabels: \"labels\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", label.Data)\n}\n"
        - lang: Java
          source: >-
            package com.telnyx.sdk.example;


            import com.telnyx.sdk.client.TelnyxClient;

            import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

            import
            com.telnyx.sdk.models.emailInboxes.messages.labels.LabelCreateParams;

            import java.util.List;


            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    TelnyxClient client = TelnyxOkHttpClient.fromEnv();

                    LabelCreateParams params = LabelCreateParams.builder()
                        .labels(List.of())
                        .build();
                    var response = client.emailInboxes().messages().labels().create("inbox_id", "message_id", params);
                }
            }
        - lang: Ruby
          source: >-
            require "telnyx"


            telnyx = Telnyx::Client.new(api_key: "My API Key")


            response = telnyx.email_inboxes.messages.labels.create("inbox_id",
            "message_id", labels: [])


            puts(response)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Telnyx\Client;

            use Telnyx\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API
            Key');


            try {
              $response = $client->emailInboxes->messages->labels->create(
                'inbox_id',
                'message_id',
                labels: [],
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx email-inboxes:messages:labels create \
              --api-key 'My API Key' \
              --inbox-id inbox_id \
              --message-id message_id \
              --labels labels
components:
  parameters:
    InboxIdPathParam:
      name: inbox_id
      in: path
      required: true
      description: Email inbox UUID.
      schema:
        type: string
        format: uuid
    MessageIdPathParam:
      name: message_id
      in: path
      required: true
      description: Inbound message UUID.
      schema:
        type: string
        format: uuid
  schemas:
    LabelMutationRequest:
      type: object
      description: >-
        Labels to add or remove. Both operations are idempotent set operations,
        so a retried request converges instead of failing.
      properties:
        labels:
          type: array
          description: >-
            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.
          items:
            type: string
            minLength: 1
            maxLength: 255
          minItems: 1
          maxItems: 50
      required:
        - labels
    InboundMessageResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/InboundMessage'
      required:
        - data
    email_ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
        suppressed:
          type: array
          description: >-
            Present when every recipient is suppressed, so the request is
            rejected and no message is created.
          items:
            $ref: '#/components/schemas/SuppressedRecipient'
      required:
        - errors
    InboundMessage:
      allOf:
        - $ref: '#/components/schemas/ThreadMessage'
        - type: object
          properties:
            direction:
              type: string
              enum:
                - inbound
            status:
              type: string
              enum:
                - received
    ErrorObject:
      type: object
      properties:
        code:
          type: string
          description: >-
            Telnyx error code. Edge idempotency errors use 10027 or 10036.
            Fallback 404/500 responses from the framework may use string status
            codes ('404', '500') instead.
          enum:
            - '10001'
            - '10006'
            - '10007'
            - '10015'
            - '10016'
            - '10019'
            - recipient_suppressed
            - reputation_suspended
            - '404'
            - '500'
            - '10027'
            - '10036'
        title:
          type: string
        detail:
          description: >-
            Human-readable error detail. Changeset responses may return a
            structured object.
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        source:
          type:
            - object
            - 'null'
          additionalProperties: true
        meta:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Additional metadata. Present on 401 errors with a documentation URL.
      required:
        - code
        - title
        - detail
    SuppressedRecipient:
      type: object
      properties:
        to:
          type: string
          format: email
          description: Suppressed recipient email address.
        reason:
          type: string
          description: Suppression reason returned by the recipient suppression service.
        scope:
          type: string
          description: Scope at which the suppression applies.
        override_allowed:
          type: boolean
          description: Whether an authorized send may override this suppression.
      required:
        - to
        - reason
        - scope
        - override_allowed
    ThreadMessage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        record_type:
          type: string
          enum:
            - email_message
        direction:
          type: string
          enum:
            - inbound
            - outbound
        status:
          type: string
          description: >-
            Received for inbound messages; the current send status for outbound
            messages.
        inbox_id:
          type: string
          format: uuid
        thread_id:
          type: string
          format: uuid
        message_id:
          type:
            - string
            - 'null'
          description: >-
            RFC Message-ID header. Null is possible for legacy outbound
            messages.
        in_reply_to:
          type:
            - string
            - 'null'
        references:
          type: array
          description: Ordered RFC Message-ID values from the References header.
          items:
            type: string
        from:
          $ref: '#/components/schemas/InboundEmailAddress'
        to:
          type: array
          items:
            $ref: '#/components/schemas/InboundEmailAddress'
        cc:
          type: array
          items:
            $ref: '#/components/schemas/InboundEmailAddress'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/InboundEmailAddress'
        reply_to:
          type: array
          items:
            $ref: '#/components/schemas/InboundEmailAddress'
        subject:
          type:
            - string
            - 'null'
        text_body_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            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:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            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:
          type:
            - string
            - 'null'
          description: >-
            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:
          type: boolean
          description: >-
            Whether conservative plain-text extraction detected a quoted tail.
            False does not prove that the source contains no quoted content.
        headers:
          type: object
          additionalProperties: true
        inline_files:
          type: array
          items:
            type: object
            additionalProperties: true
        attachments:
          type: array
          items:
            type: object
            additionalProperties: true
        labels:
          type: array
          description: >-
            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.
          items:
            type: string
            maxLength: 255
          maxItems: 50
        read_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Time the inbound message was marked read. Null means unread.
        received_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Receipt time for inbound messages; null for outbound messages.
        sent_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Creation/send-acceptance time for outbound messages; null for
            inbound messages.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - record_type
        - direction
        - status
        - inbox_id
        - thread_id
        - message_id
        - in_reply_to
        - references
        - from
        - to
        - cc
        - bcc
        - reply_to
        - subject
        - text_body_url
        - html_body_url
        - reply_text
        - has_quoted_text
        - headers
        - inline_files
        - attachments
        - labels
        - read_at
        - received_at
        - sent_at
        - created_at
        - updated_at
    InboundEmailAddress:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
      required:
        - email
  responses:
    InboundMessageLabelResponse:
      description: The updated message, including its current label set.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InboundMessageResponse'
          example:
            data:
              id: 55555555-5555-5555-5555-555555555555
              record_type: email_message
              direction: inbound
              status: received
              inbox_id: 11111111-1111-1111-1111-111111111111
              thread_id: 33333333-3333-3333-3333-333333333333
              message_id: <message@example.com>
              in_reply_to: <earlier@example.com>
              references:
                - <earlier@example.com>
              from:
                email: alice@example.com
                name: Alice
              to:
                - email: agent@inbox.example.test
              cc: []
              bcc: []
              reply_to: []
              subject: Project update
              text_body_url: null
              html_body_url: null
              reply_text: Thanks, I will send it today.
              has_quoted_text: true
              headers: {}
              inline_files: []
              attachments: []
              labels:
                - spam
                - urgent
              read_at: null
              received_at: '2026-07-15T12:30:00Z'
              sent_at: null
              created_at: '2026-07-15T12:30:00Z'
              updated_at: '2026-07-15T12:30:00Z'
    email_UnauthorizedResponse:
      description: Not authorized (10006).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/email_ErrorResponse'
          example:
            errors:
              - code: '10006'
                title: Not authorized
                detail: Invalid API key
                meta:
                  url: https://developers.telnyx.com/docs/overview/errors/10006
    email_NotFoundResponse:
      description: Resource not found (10001).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/email_ErrorResponse'
          example:
            errors:
              - code: '10001'
                title: Not Found
                detail: The requested resource was not found
    ValidationErrorResponse:
      description: Validation Failed (10015) or changeset validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/email_ErrorResponse'
          example:
            errors:
              - code: '10015'
                title: Validation Failed
                detail: subject can't be blank
                source:
                  pointer: /data/attributes/subject
    LabelServiceUnavailableResponse:
      description: Inbound label storage is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/email_ErrorResponse'
          example:
            errors:
              - code: '10016'
                title: Service Unavailable
                detail: >-
                  Inbox labels are temporarily unavailable. Please try again
                  later.
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````