List Inbox Pieces

GET

/inboxes/{inbox_id}/pieces

Lists the pieces in an inbox. Supports sorting, filtering, and paging.

Filters

The filters query parameter accepts a comma-separated list of key:value pairs that narrow results.

Allowed filter keys: in, to, from, received_after, received_before, at, carrier, class, contains.

• received_after / received_before — Filter by received date. Value must be a valid UTC datetime.
• to — Filter by recipient name (prefix match).
• from — Filter by sender name (prefix match).
• in — Filter by location. Use all_items to include all.
• carrier / class — Filter by shipping carrier and service class. When class is provided, carrier must also be provided.
• contains — Search within piece content.
• at — Filter by facility location.

Multiple filters can be combined in a single filters value.

Examples

Retrieve pieces received after a specific date: ?filters=received_after:2024-01-15T00:00:00Z Retrieve pieces addressed to a specific recipient: ?filters=to:John Smith

Authorizations

Send your API key in the x-api-key header. See Authentication.

Parameters

Path Parameters

inbox_id

required

string

Query Parameters

page

integer

The desired page from the result set. Defaults to 1.

per_page

integer

The number of items per page. Defaults to 95, which is also the maximum. Larger values return 95 items per page.

sort_by

string

The field to sort the result set by. Allowed values: id, received_at, sender.name, recipient.name. Defaults to id.

sort_direction

integer

The direction to sort the result set by. 0 for ascending, 1 for descending. Defaults to ascending (0).

recipient_ids

string

Only return pieces assigned to the given recipients. Comma-separated list of recipient IDs.

folder_id

string

Only return pieces in the given folder.

attributes

string

Only return pieces that have the given attributes. Allowed values: archived, trashed, payment-detected, pending, scanned, shipped, stored, unscanned.

filters

string

Additional filter parameters as comma-separated key:value pairs. Allowed keys: in, to, from, received_after, received_before, at, carrier, class, contains.

payload_type

integer

Specifies the payload components to return. This is a flags parameter — values can be combined by addition. 0: All, 1: Piece data only, 2: Count only, 4: Media only. Defaults to 0.

tag_id

string

Limits results to items with the specified tags. Comma-separated list of tag IDs. Possible values are provided by the listInboxTags operation.

Responses

200

Success

object

total

Total number of items across all pages.

integer

15

per_page

Number of items per page.

integer

100

current_page

The current page number (1-based).

integer

1

last_page

The last available page number.

integer

1

from

The index of the first item on this page (1-based).

integer

1

to

The index of the last item on this page (1-based).

integer

15

data

Array<object>

object

id

integer

14460059

created_at

string format: date-time

updated_at

string format: date-time

inbox_id

integer

97599

barcode

string

0000000101 0016615290

license_plate

integer

433808312186

recipient

object

id

integer

122028

name

string

Bruce Wayne

inbox_id

integer | null

97599

type

string

mailbox_folder_id

integer

0

tags

Array<string>

[
  "unscanned",
  "read",
  "inbox",
  "stored"
]

attributes

Array<string>

[
  "unscanned",
  "read",
  "inbox",
  "stored"
]

sender

One of:

object

object

name

string

address

string

null

null

received_at

string format: date-time

date_arrived_in_mailbox

string format: date-time

weight_in_ounces

number

0.16

facility_name

string

page_count_estimate

integer

2

page_count_actual

integer | null

height_in_inches

number

3.9

depth_in_inches

number

0.1

length_in_inches

number

8.88

carrier

object

name

string

Unknown

class

string

Unknown

media

Array

object

id

string

1_1_2_0_0

url

string

content_type

string

image/jpg

tags

Array<string>

[
  "color",
  "large",
  "enclosure",
  "front"
]

url_valid_until

string format: date-time

file_size_in_bytes

integer

piece_id

integer | null

14460059

scan_id

integer | null

page_count

integer | null

1

sequence_number

integer | null

ocr_data

string

envelope_ocr_data

string

piece_type

string

mail

piece_sub_type

string

letter

insights

Array<object>

object

type

string

confidence

number

user_defined_tags

Array<object>

object

id

integer

3001

created_at

string format: date-time

updated_at

string format: date-time

label

string

Urgent

parent_tag_id

integer | null

piece_counts

integer | null

12

matched_by

Array<string>

operation_action

string | null

end_user_operation_status

string | null

storage_fee_amount_in_cents

integer

can_delete_scan_only

boolean

available_actions

Array<string>

name

string

detected_checks_count

integer | null

recipient_type

string

Example

{
  "current_page": 1,
  "data": [
    {
      "created_at": "2018-07-23T21:25:52Z",
      "id": 14460059,
      "updated_at": "2018-07-23T21:25:52Z",
      "attributes": [
        "unscanned",
        "read",
        "inbox",
        "stored"
      ],
      "barcode": "0000000101 0016615290",
      "carrier": {
        "class": "Unknown",
        "name": "Unknown"
      },
      "depth_in_inches": 0.1,
      "end_user_operation_status": null,
      "height_in_inches": 3.9,
      "inbox_id": 97599,
      "insights": [],
      "length_in_inches": 8.88,
      "license_plate": 433808312186,
      "mailbox_folder_id": 0,
      "media": [
        {
          "content_type": "image/jpg",
          "id": "1_1_2_0_3",
          "tags": [
            "color",
            "medium",
            "enclosure",
            "front"
          ],
          "url": "https://media.earthclassmail.com/...",
          "url_valid_until": "2018-09-12T20:46:01Z",
          "page_count": 1,
          "piece_id": 14460059
        }
      ],
      "operation_action": null,
      "page_count_actual": null,
      "page_count_estimate": 2,
      "piece_sub_type": "letter",
      "piece_type": "mail",
      "received_at": "2018-07-23T21:25:52Z",
      "recipient": {
        "id": 122028,
        "inbox_id": 97599,
        "name": "Bruce Wayne"
      },
      "sender": null,
      "tags": [
        "unscanned",
        "read",
        "inbox",
        "stored"
      ],
      "user_defined_tags": [],
      "weight_in_ounces": 0.16
    }
  ],
  "from": 1,
  "last_page": 15,
  "per_page": 1,
  "to": 1,
  "total": 15
}

401

The x-api-key header is missing or the key is not valid, or the caller can’t access an ID in the request. IDs that don’t exist return the same response as IDs the caller can’t access.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

401

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

Returned only with 422 responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

object

key

additional properties

Array<string>

Examples

{
  "error": {
    "code": 401,
    "message": "The request does not include a valid access token. Please provide a valid access token.",
    "type": "Authorization"
  }
}

{
  "error": {
    "code": 401,
    "message": "x-api-key: x-api-key is invalid",
    "type": "REST"
  }
}

{
  "error": {
    "code": 401,
    "message": "User does not have access to requested resource.",
    "type": "Authorization"
  }
}