List letters
lob_letters_listRead-onlyIdempotent
List and filter letters on your Lob account by date, mail type, color, or metadata. Retrieve total counts without pagination using include and limit.
Instructions
List letters on your Lob account. For 'how many letters?' counts, pass include: ['total_count'] with limit: 1 — never paginate to count. Filter by date_created (e.g. { gt: '<iso>' } for 'last N days'), send_date, mail_type, color, scheduled, or metadata. Default sort is most-recent first.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many results to return (default 10, max 100). | |
| before | No | Cursor for the previous page. | |
| after | No | Cursor for the next page. | |
| include | No | Response add-ons. Pass ['total_count'] alongside any filters and limit:1 to answer 'how many?' questions in a single call — far cheaper than paginating to count. Not accepted on nested order endpoints (buckslip/card orders) or /webhooks. | |
| date_created | No | ISO8601 date filter object with gt/gte/lt/lte keys, e.g. { gt: '2026-04-23T00:00:00Z' } for 'last 7 days'. Combine with include:['total_count'] and limit:1 for date-bounded counts. | |
| metadata | No | Filter by metadata key/value pairs. | |
| mail_type | No | Mail class. Defaults to usps_first_class for most pieces. | |
| color | No | ||
| scheduled | No | ||
| send_date | No | ISO8601 date filter object with gt/gte/lt/lte keys, e.g. { gt: '2026-04-23T00:00:00Z' } for 'last 7 days'. Combine with include:['total_count'] and limit:1 for date-bounded counts. |