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

# List entity mail

> Retrieve all lockbox mail for an entity.

Returns a list of all mail items received at the entity's lockbox. Each item includes a `file_id` for the scanned PDF and an `amount` representing the total value of any checks found in that piece of mail. If the mail contained checks, they are listed in the `checks` array.

## Path parameters

<ParamField path="entity_id" type="string" required>
  The ID of the entity. You can find entity IDs using the [List
  entities](/api-reference/list-entities) endpoint.
</ParamField>

## Query parameters

<ParamField query="limit" type="integer" default="10">
  Maximum number of mail items to return per page. Default is 10, maximum is
  100\.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor for retrieving the next page of results. Returned as
  `cursor` in the response. See [pagination](/api-reference/pagination) for
  details.
</ParamField>

<ParamField query="received.on_or_after" type="string">
  Filter to mail received at or after this timestamp. [ISO
  8601](/api-reference/timestamps) format.
</ParamField>

<ParamField query="received.on_or_before" type="string">
  Filter to mail received at or before this timestamp. [ISO
  8601](/api-reference/timestamps) format.
</ParamField>

## Response

<ResponseField name="has_next" type="boolean">
  Whether more mail items exist beyond this page. Use the `cursor` field to
  retrieve the next page.
</ResponseField>

<ResponseField name="cursor" type="string | null">
  Cursor to retrieve the next page of results. Null if this is the last page.
  Pass this value as the `cursor` query parameter in a subsequent request. See
  [pagination](/api-reference/pagination) for details.
</ResponseField>

<ResponseField name="data" type="object[]">
  The list of mail objects.

  <Expandable title="Mail object">
    <ResponseField name="id" type="string">
      Unique identifier for the lockbox mail item.
    </ResponseField>

    <ResponseField name="entity_id" type="string">
      The ID of the entity whose lockbox received this mail.
    </ResponseField>

    <ResponseField name="file_id" type="string | null">
      The ID of the scanned PDF, prefixed with `file_`. Use the [Get
      PDF](/api-reference/get-pdf) endpoint to download it. Null if the mail
      item has not been scanned yet.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      The total value of all checks in this piece of mail, in cents. Zero if no
      checks were found.
    </ResponseField>

    <ResponseField name="checks" type="object[]">
      The checks found in this piece of mail. Empty array if no checks were
      found.

      <Expandable title="Check object">
        <ResponseField name="id" type="string">
          Unique identifier for the check, prefixed with `check_deposit_`.
        </ResponseField>

        <ResponseField name="amount" type="integer">
          The amount of the check in cents.
        </ResponseField>

        <ResponseField name="transaction_id" type="string | null">
          The ID for the transaction created by the check deposit. Null if the
          check is pending manual intervention.
        </ResponseField>

        <ResponseField name="status" type="string">
          The processing status of the check. One of `pending`, `submitted`, `returned`, or `rejected`.

          **Pending** means Lemma has not attempted to deposit the check yet.

          **Submitted** means the check has been submitted for deposit. There will be a hold on the funds for a few days.

          **Returned** checks are unlikely to happen to healthcare practices receiving funds from payers. Nevertheless, here are a few common reasons checks are returned:

          * Insufficient funds
          * Stop payment instructions
          * The check was drawn from a closed bank account
          * The check was not authorized

          We'll reach out if a check is returned to share additional details.

          **Rejected** checks are rare. We reject checks if it's impossible to deposit the check after a manual review. For example, a payer could've sent you another entity's check. You can use the [Get PDF](/api-reference/get-pdf) endpoint to see for yourself why the check was unrelated to your account.
        </ResponseField>

        <ResponseField name="hold" type="object | null">
          Fund hold details. Present when deposited funds are held before becoming available. Null if there is no hold.

          <Expandable title="Hold object">
            <ResponseField name="status" type="string">
              The hold status. One of `held` or `complete`.
            </ResponseField>

            <ResponseField name="automatically_releases_at" type="string">
              [ISO 8601](/api-reference/timestamps) timestamp of when the hold will automatically release.
            </ResponseField>

            <ResponseField name="released_at" type="string | null">
              [ISO 8601](/api-reference/timestamps) timestamp of when the hold was released. Null if the hold has not been released yet.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="micr" type="object | null">
          Fields read from the check's [MICR line](https://en.wikipedia.org/wiki/Magnetic_ink_character_recognition). Null when we have not submitted the check for deposit.

          <Expandable title="MICR object">
            <ResponseField name="routing_number" type="string">
              The routing number printed on the check.
            </ResponseField>

            <ResponseField name="account_number" type="string">
              The account number printed on the check.
            </ResponseField>

            <ResponseField name="auxiliary_on_us" type="string | null">
              An additional identifier from the MICR line. Business checks typically encode the check number here rather than in `serial_number`.
            </ResponseField>

            <ResponseField name="serial_number" type="string | null">
              The check number. For business checks, this may be null — look at `auxiliary_on_us` instead.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="received_at" type="string">
      [ISO 8601](/api-reference/timestamps) timestamp of when the mail was
      received at the lockbox.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "inbound_mail_item_Kv7nWp3hTx9cBd5m",
        "entity_id": "entity_k7mXp2vR9nTfBw4s",
        "file_id": "file_Xt7nRv3hBw9pKm4s",
        "amount": 372500,
        "checks": [
          {
            "id": "check_deposit_Tm6bXn9hRw3pFk7c",
            "amount": 100000,
            "transaction_id": "transaction_Ab5cDx3nKv8bTh2d",
            "status": "submitted",
            "hold": {
              "status": "held",
              "automatically_releases_at": "2026-03-19T14:00:00Z",
              "released_at": null
            },
            "micr": {
              "routing_number": "021000021",
              "account_number": "9876543210",
              "auxiliary_on_us": null,
              "serial_number": "00012345"
            }
          },
          {
            "id": "check_deposit_Jd4xVs8mBn2wYh5t",
            "amount": 2000,
            "transaction_id": null,
            "status": "rejected",
            "hold": null,
            "micr": null
          }
        ],
        "received_at": "2026-03-14T14:00:00Z"
      },
      {
        "id": "inbound_mail_item_Rs4bFj8wNm2yHt6x",
        "entity_id": "entity_k7mXp2vR9nTfBw4s",
        "file_id": "file_Hd5cWm8nTx2vFk7b",
        "amount": 0,
        "checks": [],
        "received_at": "2026-03-13T10:45:00Z"
      }
    ],
    "has_next": false,
    "cursor": null
  }
  ```
</ResponseExample>