---
title: "List Mail Items"
method: GET
path: "/v1/mail_items"
tags: ["mailItems"]
---

# List Mail Items

`GET /v1/mail_items`

List mail items for your account.

A Mail Item is a unit of physical mail received at a Lockbox. It has its own lifecycle
and is the operational unit reviewers act on. Each Mail Item may produce zero or more
Donations and zero or one Deposit.

## Query parameters

- `limit` integer
- `page_token` string
- `lockbox_id` string
- `status.in` MailItemStatus[]
- `created_at.after` string, date-time
- `created_at.before` string, date-time

## Response `200`

The response for MailItems.list

- object
  - `results` MailItem[]
    - `id` string, required — The unique identifier for the mail item.
    - `lockbox_id` string — The unique identifier for the lockbox that received the mail item.
    - `status` 'processing' | 'needs_review' | 'processed' | 'rejected', required — The processing status of a Mail Item. - `processing`: The mail item is being scanned and parsed. - `needs_review`: Extraction completed but produced ambiguous results that require human review. - `processed`: The mail item has been successfully parsed and classified, and is ready for any downstream automations or workflows to run on it. - `rejected`: The mail item will not produce a Donation (e.g., return-to-sender, illegible, unrelated correspondence).
    - `received_at` string, date-time, required — The date and time when the mail item was physically received at the lockbox.
    - `scans` MailItemScan[], required — The scans taken of the mail item, newest first. A mail item typically has one scan; a second scan appears after an admin requests a rescan of the physical mail.
      - `file_id` string, required — The unique identifier for the scanned document file. Fetch contents via the File API.
      - `created_at` string, date-time, required — The date and time when the scan was taken.
    - `created_at` string, date-time, required — The date and time when the mail item record was created.
    - `updated_at` string, date-time, required — The date and time when the mail item record was last updated.
  - `next_page_token` string — A cursor token to use to retrieve the next page of results by making another API call to the same endpoint with the same parameters (only changing the pageToken). If specified, then more results exist on the server that were not returned, otherwise no more results exist on the server.

## Other responses

- `400` — The request is invalid or contains invalid parameters
- `401` — Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.
- `403` — Access denied
- `500` — Internal Server Error

---

[API](https://skmtc.net/chariot-giving/apis/specs.md) · [All operations](https://skmtc.net/chariot-giving/apis/specs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/chariot-giving/specs/revisions/8446023e02fb/schema)