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

# List Domains

> Retrieve all sending domains registered with your account. Returns domains with their current status, verification state, and timestamps.

Returns all sending domains configured for your team, including their verification status and DNS record information.


## OpenAPI

````yaml GET /domains
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:
  /domains:
    get:
      tags:
        - Domains
      summary: List Domains
      description: >-
        Retrieve all sending domains registered with your account. Returns
        domains with their current status, verification state, and timestamps.
      operationId: listDomains
      responses:
        '200':
          description: List of domains retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDomainsResponse'
              example:
                message: Domains retrieved successfully.
                data:
                  domains:
                    - domain: example.com
                      status: approved
                      status_label: Approved
                      can_send: true
                      cname_status: valid
                      dkim_status: valid
                      created_at: '2024-01-15T10:30:00+00:00'
                      updated_at: '2024-01-16T14:45:00+00:00'
                    - domain: pending.example.com
                      status: pending
                      status_label: Pending Review
                      can_send: false
                      cname_status: null
                      dkim_status: null
                      created_at: '2024-01-17T09:00:00+00:00'
                      updated_at: '2024-01-17T09:00:00+00:00'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          description: Server error - Failed to retrieve domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Failed to retrieve domains. Please try again later.
                error_code: send_error
      security:
        - bearerAuth: []
components:
  schemas:
    ListDomainsResponse:
      type: object
      description: Response containing a list of domains
      required:
        - message
        - data
      properties:
        message:
          type: string
          description: Human-readable response message
          example: Domains retrieved successfully.
        data:
          type: object
          required:
            - domains
          properties:
            domains:
              type: array
              description: List of domains
              items:
                $ref: '#/components/schemas/DomainListItemView'
    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'
    DomainListItemView:
      type: object
      description: View of a domain in the list response
      required:
        - domain
        - status
        - status_label
        - can_send
        - created_at
        - updated_at
      properties:
        domain:
          type: string
          description: The domain name
          example: example.com
        status:
          type: string
          enum:
            - pending
            - approved
            - blocked
          description: Current status of the domain
          example: approved
        status_label:
          type: string
          description: Human-readable status label
          example: Approved
        can_send:
          type: boolean
          description: Whether the domain can be used for sending emails
          example: true
        cname_status:
          type:
            - string
            - 'null'
          description: CNAME verification status
          example: valid
        dkim_status:
          type:
            - string
            - 'null'
          description: DKIM verification status
          example: valid
        created_at:
          type: string
          format: date-time
          description: When the domain was created
          example: '2024-01-15T10:30:00+00:00'
        updated_at:
          type: string
          format: date-time
          description: When the domain was last updated
          example: '2024-01-16T14:45:00+00:00'
    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
  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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````