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

# Show a segment

> Retrieve a single segment. Requires the `audience:read` scope.

Retrieve a single segment. Requires the `audience:read` scope.


## OpenAPI

````yaml GET /audience/segments/{segmentId}
openapi: 3.1.0
info:
  title: Lettr API
  version: 1.0.0
  description: >-
    Lettr Email API - Send transactional emails with tracking, attachments, and
    personalization.
  contact:
    name: Lettr Support
    url: https://lettr.com
  license:
    name: Proprietary
    url: https://lettr.com/terms
servers:
  - url: https://app.lettr.com/api
    description: Production
security: []
tags:
  - name: Emails
    description: Email sending operations
  - name: Templates
    description: Email template management operations
  - name: Domains
    description: Domain management operations
  - name: Webhooks
    description: Webhook management operations
  - name: Audience
    description: 'Audience management: lists, contacts, topics, properties, and segments'
  - name: Campaigns
    description: >-
      Campaign operations: listing, stats, engagement events, and
      dispatch/scheduling
paths:
  /audience/segments/{segmentId}:
    get:
      tags:
        - Audience
      summary: Show a segment
      description: Retrieve a single segment. Requires the `audience:read` scope.
      operationId: showAudienceSegment
      parameters:
        - name: segmentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Segment ID
      responses:
        '200':
          description: Segment retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowAudienceSegmentResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Segment not found.
                error_code: not_found
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    ShowAudienceSegmentResponse:
      type: object
      required:
        - message
        - data
      properties:
        message:
          type: string
          example: Segment retrieved successfully.
        data:
          $ref: '#/components/schemas/AudienceSegmentView'
    ErrorResponse:
      type: object
      required:
        - message
        - error_code
      description: Error response for non-validation errors (400, 409, 500, 502).
      properties:
        message:
          type: string
          description: Human-readable error message
          example: The sender domain could not be determined from the email address.
        error_code:
          $ref: '#/components/schemas/ErrorCode'
    AudienceSegmentView:
      type: object
      required:
        - id
        - name
        - list_id
        - list_name
        - condition_groups
        - cached_contacts_count
        - created_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Engaged subscribers
        list_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Restrict segment to a single list (null = all lists)
        list_name:
          type:
            - string
            - 'null'
        condition_groups:
          type: array
          items:
            $ref: '#/components/schemas/SegmentConditionGroup'
        cached_contacts_count:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Last computed contacts count (may be stale)
        created_at:
          type: string
          format: date-time
    UnauthorizedResponse:
      type: object
      required:
        - message
      description: Error response for authentication failures (401).
      properties:
        message:
          type: string
          description: Human-readable error message
          example: API key is required.
    ErrorCode:
      type: string
      description: >-
        Error codes returned by the API.


        | Code | HTTP Status | Description |

        |------|-------------|-------------|

        | `validation_error` | 422 | Request validation failed. Check the
        `errors` object for field-specific messages. |

        | `invalid_domain` | 400 | The sender domain could not be determined
        from the email address. |

        | `unconfigured_domain` | 400 | The sender domain is not configured or
        approved for sending. |

        | `send_error` | 400, 500 | General error during email send preparation
        or domain registration. |

        | `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g.,
        sandbox key without associated user, upstream error). |

        | `transmission_failed` | 502 | Email transmission to the upstream
        provider failed. |

        | `resource_already_exists` | 409 | The resource (e.g., domain) already
        exists. |

        | `not_found` | 404 | The specified resource was not found. |

        | `template_not_found` | 404 | The specified template, project, or
        template version was not found. |

        | `insufficient_scope` | 403 | The API key does not have the required
        scope for this endpoint. |

        | `schedule_cancellation_failed` | 409, 500 | Could not cancel the
        scheduled transmission (already sent or upstream error). |

        | `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your
        plan to continue sending. |

        | `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again
        tomorrow. |

        | `campaign_not_sendable` | 422 | The campaign cannot be sent in its
        current state (not a draft, or missing subject/sender/content). |

        | `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it
        cannot be unscheduled. |
      enum:
        - validation_error
        - invalid_domain
        - unconfigured_domain
        - send_error
        - retrieval_error
        - transmission_failed
        - resource_already_exists
        - not_found
        - template_not_found
        - insufficient_scope
        - schedule_cancellation_failed
        - quota_exceeded
        - daily_quota_exceeded
        - campaign_not_sendable
        - campaign_not_scheduled
      example: invalid_domain
    SegmentConditionGroup:
      type: object
      description: >-
        Group of conditions joined by OR. Multiple groups in a segment are
        joined by AND.
      required:
        - conditions
      properties:
        conditions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/SegmentCondition'
    SegmentCondition:
      type: object
      required:
        - field
        - operator
      properties:
        field:
          type: string
          maxLength: 255
          description: >-
            Field name to match against (e.g., `email`, `status`, a property
            name)
          example: email
        operator:
          $ref: '#/components/schemas/SegmentOperator'
        value:
          type:
            - string
            - 'null'
          maxLength: 1000
          description: >-
            Value to compare against. Required for all operators except
            `is_true` and `is_false`, which evaluate the field's truthiness and
            accept no value (may be omitted or `null`).
          example: '@example.com'
    SegmentOperator:
      type: string
      enum:
        - contains
        - not_contains
        - equals
        - not_equals
        - starts_with
        - not_starts_with
        - ends_with
        - not_ends_with
        - is_true
        - is_false
        - greater_than
        - greater_than_or_equal
        - less_than
        - less_than_or_equal
        - before
        - after
      description: Segment condition operator
      example: equals
  responses:
    UnauthorizedError:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'
          examples:
            missing_key:
              summary: Missing API key
              value:
                message: API key is required.
            invalid_key:
              summary: Invalid API key
              value:
                message: Invalid API key.
    ForbiddenError:
      description: Forbidden - API key does not have the required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: >-
              Your API key does not have the required permissions for this
              action.
            error_code: insufficient_scope
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: An unexpected error occurred. Please try again later.
            error_code: send_error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````