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

# List recipients for an email message

> Lists per-recipient delivery states for a single message with cursor pagination.
Each recipient has an independent status, billable flag, and lifecycle timestamps.
BCC recipient addresses are redacted (returned as null) to protect BCC privacy.
Default page size is 25, maximum is 100.




## OpenAPI

````yaml /openapi/source/external/email/email.json get /email_messages/{email_id}/recipients
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_messages/{email_id}/recipients:
    get:
      tags:
        - Email Messages
      summary: List recipients for an email message
      description: >
        Lists per-recipient delivery states for a single message with cursor
        pagination.

        Each recipient has an independent status, billable flag, and lifecycle
        timestamps.

        BCC recipient addresses are redacted (returned as null) to protect BCC
        privacy.

        Default page size is 25, maximum is 100.
      operationId: ListEmailMessageRecipients
      parameters:
        - name: email_id
          in: path
          required: true
          description: Email message UUID.
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageCursor'
        - name: status
          in: query
          description: Filter recipients by status.
          required: false
          schema:
            type: string
            enum:
              - queued
              - sending
              - sent
              - deferred
              - delivered
              - bounced
              - failed
              - gw_reject
              - cancelled
        - name: kind
          in: query
          description: Filter recipients by address kind.
          required: false
          schema:
            type: string
            enum:
              - to
              - cc
              - bcc
      responses:
        '200':
          description: Paginated list of recipients.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailRecipientListResponse'
              example:
                data:
                  - record_type: email_recipient
                    id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    message_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    address: example@telnyx.com
                    kind: to
                    status: queued
                    billable: false
                    sent_at: '2024-01-23T18:10:02.574Z'
                    delivered_at: '2024-01-23T18:10:02.574Z'
                    failed_at: '2024-01-23T18:10:02.574Z'
                    smtp_code: 0
                    smtp_response: string
                meta:
                  page_size: 1
                  page_cursor: string
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
      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
            });


            // Automatically fetches more pages as needed.

            for await (const response of client.emailMessages.recipients.list())
            {
              console.log(response);
            }
        - 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
            )
            page = client.email_messages.recipients.list(
                "email_id",
            )
            print(page.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\trecipients, err := client.EmailMessages.Recipients.List(\n\t\tcontext.TODO(),\n\t\t\"email_id\",\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", recipients.Data)\n}\n"
        - lang: Java
          source: |-
            package com.telnyx.sdk.example;

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

            public final class Main {
                private Main() {}

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

                    var page = client.emailMessages().recipients().list("email_id");
                }
            }
        - lang: Ruby
          source: |-
            require "telnyx"

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

            page = telnyx.email_messages.recipients.list("email_id")

            puts(page)
        - 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 {
              $page = $client->emailMessages->recipients->list(
                'email_id',
              );

              var_dump($page);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx email-messages:recipients list \
              --api-key 'My API Key' \
              --email-id email_id
components:
  parameters:
    PageSize:
      name: page_size
      in: query
      description: >-
        Number of results to return. Defaults to 25; maximum is 100. Invalid
        values are clamped to the valid range.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    PageCursor:
      name: page_cursor
      in: query
      description: Opaque URL-safe Base64 cursor returned by a previous list response.
      required: false
      schema:
        type: string
      example: eyJpbnNlcnRlZF9hdCI6IjIwMjQtMDEtMDEifQ
  schemas:
    EmailRecipientListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmailRecipient'
        meta:
          type: object
          properties:
            page_size:
              type: integer
              minimum: 1
              maximum: 100
            page_cursor:
              type: string
              nullable: true
              description: Cursor for the next page. Absent when there are no more results.
          required:
            - page_size
      required:
        - data
        - meta
    EmailRecipient:
      type: object
      properties:
        record_type:
          type: string
          enum:
            - email_recipient
        id:
          type: string
          format: uuid
          description: Recipient UUID.
        message_id:
          type: string
          format: uuid
          description: Parent email message UUID.
        address:
          type: string
          format: email
          nullable: true
          description: >-
            Recipient email address. Null for BCC recipients (redacted for
            privacy).
        kind:
          type: string
          enum:
            - to
            - cc
            - bcc
        status:
          type: string
          enum:
            - queued
            - sending
            - sent
            - deferred
            - delivered
            - bounced
            - failed
            - gw_reject
            - cancelled
          description: Current per-recipient delivery status.
        billable:
          type: boolean
          description: >-
            Whether this recipient's delivery is billable (set on queue
            acceptance).
        sent_at:
          type: string
          format: date-time
          nullable: true
        delivered_at:
          type: string
          format: date-time
          nullable: true
        failed_at:
          type: string
          format: date-time
          nullable: true
        smtp_code:
          type: integer
          nullable: true
          description: SMTP response code when available (e.g. 550 for bounces).
        smtp_response:
          type: string
          nullable: true
          description: SMTP response message when available.
      required:
        - record_type
        - id
        - message_id
        - address
        - kind
        - status
        - billable
    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
    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
  responses:
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Telnyx API key supplied as `Authorization: Bearer <token>`. In
        production, auth may be validated by the API gateway and forwarded via
        Telnyx auth headers.

````