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

# List Letters

> List all letters for your account.

# List Letters

Retrieve all letters belonging to your account, ordered by most recently updated first.

## Response

<ResponseField name="letters" type="array">
  An array of letter objects.

  <Expandable title="letter object">
    <ResponseField name="id" type="string">
      The unique letter ID.
    </ResponseField>

    <ResponseField name="status" type="string">
      The letter status. One of: `draft`, `processing`, `sent`, `delivered`, `failed`.
    </ResponseField>

    <ResponseField name="recipient" type="string">
      The recipient name, if provided.
    </ResponseField>

    <ResponseField name="address" type="object">
      The structured address object.
    </ResponseField>

    <ResponseField name="content" type="string">
      The letter body text.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl https://thepostalcompany.com/api/v1/letters \
    -H "Authorization: Bearer tpc_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://thepostalcompany.com/api/v1/letters", {
    headers: { "Authorization": "Bearer tpc_your_api_key" },
  });

  const { letters } = await response.json();
  console.log(`You have ${letters.length} letters`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "letters": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "sent",
        "recipient": "Jane Doe",
        "address": {
          "street": "Keizersgracht",
          "number": "123",
          "postalcode": "1015 CJ",
          "city": "Amsterdam",
          "country": "NL"
        },
        "content": "Dear Jane,\n\nHello!\n\nBest regards",
        "created_at": "2026-04-14T10:00:00.000Z",
        "updated_at": "2026-04-14T10:00:05.000Z"
      }
    ]
  }
  ```
</ResponseExample>

## Error codes

| Status | Description                          |
| ------ | ------------------------------------ |
| `401`  | Missing, invalid, or revoked API key |