Table of Contents

List Mail Pieces

This endpoint is used to search for mail pieces.

Definition

Route: /mailpieces/search
Method: GET
OperationId: ListMailPieces

Permissions

The user must be a member of one of the following groups to search mail pieces:

  • mailpieces:manager
  • mailpieces:viewer

Request

Headers

Name Description Notes
accept The expected format of the response application/json
osg-client-id The unique identifier assigned to your organization Required
client_customer_id The unique identifier assigned to your client
correlation_id The unique identifier for correlation

Query Parameters

Name Type Required Description
child_client_id string No Filters results to a specific child client.
job_id string No Filters results to a specific job.
imb string No Filters by Intelligent Mail Barcode.
impb string No Filters by Intelligent Mail Package Barcode.
mail_class string No Filters by mail class.
status string No Filters by current status.
start_date string No The start of the date range (ISO 8601 date-time).
end_date string No The end of the date range (ISO 8601 date-time).
sort_by string No The field to sort by.
sort_order string No The sort direction (e.g. asc or desc).
page_number int No The page to retrieve. Defaults to 1.
page_size int No The number of records per page. Defaults to 10.

Responses

Headers

Key Value Type Description
content-type application/json string

Success

Status Description Body
200 The request was successful. JSON object

Response Body

Field Type Nullable Description
result object No The standard result envelope. See Result.
page_number int No The current page number.
page_size int No The number of records per page.
total_pages int No The total number of pages available.
total_records int No The total number of matching records.
mail_pieces array of object No The matching mail piece summaries. See Mail Piece Summary.

Mail Piece Summary

Field Type Nullable Description
client_id string No The client the mail piece belongs to.
job_id string No The job the mail piece was produced under.
mail_piece_id string No The unique identifier of the mail piece.
mail_class string Yes The mail class of the piece.
created_date string No The date the mail piece was created.
mailed_date string Yes The date the mail piece was mailed, when available.
imb string Yes The Intelligent Mail Barcode, when available.
impb string Yes The Intelligent Mail Package Barcode, when available.
tracking_number string Yes The carrier tracking number, when available.
account_number string Yes The account number associated with the piece. 
{
  "result": {
    "is_success": true,
    "errors": [],
    "message": null,
    "sent_on_utc": "2025-01-01T12:00:00Z",
    "trace_id": "...",
    "correlation_id": "..."
  },
  "page_number": 1,
  "page_size": 10,
  "total_pages": 3,
  "total_records": 24,
  "mail_pieces": [
    {
      "client_id": "123456789",
      "job_id": "JOB-42",
      "mail_piece_id": "MP-0001",
      "mail_class": "First-Class",
      "created_date": "2025-01-01T08:00:00Z",
      "mailed_date": "2025-01-02T08:00:00Z",
      "imb": "...",
      "impb": null,
      "tracking_number": "9400100000000000000000",
      "account_number": "ACCT-777"
    }
  ]
}

Failures

Status Description Body
400 The request was invalid. See Validation Errors. JSON error
401 The request was not authorized. None
403 The request was not allowed. None
500 An unexpected error occurred. JSON error

Validation Errors

A 400 is returned when the request fails validation. Common causes:

Condition Message
page_size exceeds the maximum of 100. Page size cannot be larger than 100.
page_size is not greater than 0. Page size must be greater than 0.
page_number is not greater than 0. Page number must be greater than 0.
end_date is earlier than start_date. End date cannot be before start date.
The upstream batch limit was exceeded. Exceeded the OSG Mail API batch limit.

Copyright © 2025 Output Services Group, Inc. All Rights Reserved.