> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.givechariot.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.givechariot.com/_mcp/server.

# List Mail Items

GET https://api.givechariot.com/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.

Reference: https://docs.givechariot.com/api/mail-items/list

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.givechariot.com` (Production, default)
- `https://sandboxapi.givechariot.com` (Sandbox)

## Request

### Query parameters

- `limit` (integer, optional) — Limit the size of the list that is returned. The default (and maximum) is 100 objects.
- `page_token` (string, optional) — The cursor to use for pagination. If not set, the first page of results will be returned.
- `lockbox_id` (string, optional) — The unique identifier for the lockbox to filter mail items by.
- `status.in` (list of enum, optional) — Filter Mail Items to only those with the specified status. For GET requests, this should be encoded as a comma-delimited string, such as `?status.in=needs_review,processing`.
  - Allowed values: `processing`, `needs_review`, `under_review`, `processed`, `rejected`
- `created_at.after` (datetime, optional) — Return mail items created after the given date and time.
- `created_at.before` (datetime, optional) — Return mail items created before the given date and time.

## Response

### 200

The response for MailItems.list

- `results` (list of MailItem, optional)
- `next_page_token` (string, optional) — 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.

## Errors

### 400 Bad Request Error

The request is invalid or contains invalid parameters

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 401 Unauthorized Error

Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 403 Forbidden Error

Access denied

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 500 Internal Server Error

Internal Server Error

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

## Types

### MailItem

A Mail Item represents a unit of physical mail. It has its own lifecycle and is the operational unit that reviewers act on. A Mail Item may produce zero or more Donations and zero or one Deposit, and carries the scanned artifacts (envelopes, checks, accompanying paperwork) associated with the receipt. Mail Items are created by Chariot when a lockbox provider uploads a batch of scanned mail. They are not created via the public API — to bring donation data and money in directly, use the Donations and Deposits APIs.

- `id` (string, required) — The unique identifier for the mail item.
- `status` (enum, required) — The processing status of a Mail Item. - `processing`: The mail item is being scanned and parsed. - `needs_review`: The mail item requires your review. - `under_review`: Chariot is reviewing the mail item. No action is required. - `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).
  - Allowed values: `processing`, `needs_review`, `under_review`, `processed`, `rejected`
- `received_at` (datetime, required) — The date and time when the mail item was physically received at the lockbox.
- `scans` (list of 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.
- `created_at` (datetime, required) — The date and time when the mail item record was created.
- `updated_at` (datetime, required) — The date and time when the mail item record was last updated.
- `lockbox_id` (string, optional) — The unique identifier for the lockbox that received the mail item.

### MailItemScan

A single scan of a Mail Item. Multiple entries represent rescans.

- `file_id` (string, required) — The unique identifier for the scanned document file. Fetch contents via the File API.
- `created_at` (datetime, required) — The date and time when the scan was taken.

## Examples

**Response**

```json
{
  "results": [
    {
      "id": "mail_01j8rs605a4gctmbm58d87mvsj",
      "status": "processed",
      "received_at": "2020-01-31T23:59:59Z",
      "scans": [
        {
          "file_id": "file_01j8rs605a4gctmbm58d87mvsj",
          "created_at": "2020-01-31T23:59:59Z"
        }
      ],
      "created_at": "2020-01-31T23:59:59Z",
      "updated_at": "2020-01-31T23:59:59Z",
      "lockbox_id": "lockbox_01j8rs605a4gctmbm58d87mvsj"
    }
  ],
  "next_page_token": "string"
}
```