> ## 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/source/external/email/email.json post /email_inboxes/{inbox_id}/messages/{message_id}/labels openapi: 3.0.3 info: x-latency-category: responsive x-endpoint-cost: light title: Telnyx API description: >- Programmable email: sending, templates, validation, events, agent inboxes, drafts, threads, domains & DKIM, suppressions and unsubscribe groups. version: 2.0.0 contact: name: Telnyx url: https://telnyx.com servers: - url: https://api.telnyx.com/v2 security: - BearerAuth: [] tags: - name: Email Validations description: Validate email addresses synchronously or in asynchronous batches. - name: Email Templates description: Create, list, retrieve, update, delete, and render Liquid email templates. - name: Email Messages description: >- Send and manage email messages. Legacy `/v2/emails` routes are aliases for these endpoints. - name: Email Events description: Retrieve account-level email events and event statistics. - name: Email Inboxes description: >- Create and manage agent inboxes, retrieve inbound messages and threads, and reply to or forward messages. - name: Email Drafts description: >- Create, list, retrieve, update, delete, and send unsent draft messages belonging to an agent inbox. - name: Email Threads description: >- Account-wide conversation threads across every inbox, for agents operating many inboxes at once. - name: Email Domains description: Email domain CRUD operations - name: Email Domain DNS Records description: DNS verification records for email domains - name: Email Webhooks description: Per-domain webhook endpoints with event subscriptions - name: Email Suppressions description: Recipient suppression records (`/v2/email_blocks`). - name: Email Suppression Imports description: Async CSV import of competitor suppression lists. - name: Email Unsubscribe Groups description: Named groups and group-scoped suppressions. 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/UnauthorizedResponse' '404': $ref: '#/components/responses/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: >- 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 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 additionalProperties: true nullable: true meta: type: object additionalProperties: true nullable: 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 nullable: true description: >- RFC Message-ID header. Null is possible for legacy outbound messages. in_reply_to: type: string nullable: true 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 nullable: true text_body_url: type: string format: uri nullable: true 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 format: uri nullable: true 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 nullable: true 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 format: date-time nullable: true description: Time the inbound message was marked read. Null means unread. received_at: type: string format: date-time nullable: true description: Receipt time for inbound messages; null for outbound messages. sent_at: type: string format: date-time nullable: true 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: in_reply_to: references: - 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' UnauthorizedResponse: description: Not authorized (10006). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - code: '10006' title: Not authorized detail: Invalid API key meta: url: https://developers.telnyx.com/docs/overview/errors/10006 NotFoundResponse: description: Resource not found (10001). content: application/json: schema: $ref: '#/components/schemas/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/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/ErrorResponse' example: errors: - code: '10016' title: Service Unavailable detail: >- Inbox labels are temporarily unavailable. Please try again later. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Telnyx API key supplied as `Authorization: Bearer `. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers. ````