Inbox List

Search and paginate inbound parcels received by a mailbox.

Endpoint

POST /v2/parcels/inbox-list

Request Body

Field	Type	Required	Constraints	Description
mailboxId	int	No		Filter by mailbox ID; defaults to authenticated user's mailbox
ecGridIdFrom	int	No		Filter by sender ECGrid ID
ecGridIdTo	int	No		Filter by recipient ECGrid ID
status	ParcelStatus	No		Filter by parcel status
beginDate	datetime	No	ISO 8601	Return parcels created on or after this date
endDate	datetime	No	ISO 8601	Return parcels created on or before this date
pageNo	int	No	Default: 1	Page number for paginated results
recordsPerPage	int	No	Default: 25	Number of records per page

{
  "mailboxId": 1001,
  "status": "InBoxReady",
  "beginDate": "2026-05-01T00:00:00Z",
  "endDate": "2026-05-07T23:59:59Z",
  "pageNo": 1,
  "recordsPerPage": 25
}

Response

Returns a paginated array of ParcelIDInfo objects matching the filter criteria.

{
  "success": true,
  "data": [
    {
      "parcelId": 987654321,
      "mailboxId": 1001,
      "networkId": 42,
      "fileName": "invoice_batch_20260507.edi",
      "bytes": 14872,
      "status": "InBoxReady",
      "ecGridIdFrom": 112233,
      "ecGridIdTo": 445566,
      "created": "2026-05-07T08:00:00Z",
      "modified": "2026-05-07T08:05:00Z"
    }
  ]
}

ENUMs

ParcelStatus

See ParcelStatus in Appendix — ENUMs for the full list of parcel status values.

Code Examples

cURL

curl -X POST "https://rest.ecgrid.io/v2/parcels/inbox-list" \
  -H "X-API-Key: $ECGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mailboxId": 1001, "status": "InBoxReady", "beginDate": "2026-05-01T00:00:00Z", "endDate": "2026-05-07T23:59:59Z", "pageNo": 1, "recordsPerPage": 25 }'

C#

// .NET 10 — retrieve the first page of unread inbound parcels for a mailbox
using System.Net.Http.Json;

var listRequest = new
{
    mailboxId = 1001,
    status = "InBoxReady",
    pageNo = 1,
    recordsPerPage = 25
};

var response = await http.PostAsJsonAsync(
    "https://rest.ecgrid.io/v2/parcels/inbox-list",
    listRequest);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadFromJsonAsync<ApiResponse<List<ParcelIdInfo>>>();
Console.WriteLine($"Found {result!.Data.Count} inbound parcel(s).");

Java

import java.net.URI;
import java.net.http.*;

String apiKey = System.getenv("ECGRID_API_KEY");

String body = "{ \"mailboxId\": 1001, \"status\": \"InBoxReady\", \"beginDate\": \"2026-05-01T00:00:00Z\", \"endDate\": \"2026-05-07T23:59:59Z\", \"pageNo\": 1, \"recordsPerPage\": 25 }";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://rest.ecgrid.io/v2/parcels/inbox-list"))
    .header("X-API-Key", apiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Node.js

const apiKey = process.env.ECGRID_API_KEY;
const url = 'https://rest.ecgrid.io/v2/parcels/inbox-list';

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ "mailboxId": 1001, "status": "InBoxReady", "beginDate": "2026-05-01T00:00:00Z", "endDate": "2026-05-07T23:59:59Z", "pageNo": 1, "recordsPerPage": 25 }),
});

const data = await response.json();
console.log(data);

Python

import os, requests

api_key = os.environ["ECGRID_API_KEY"]
headers = {"X-API-Key": api_key}
url = "https://rest.ecgrid.io/v2/parcels/inbox-list"

response = requests.post(
    url,
    json={ "mailboxId": 1001, "status": "InBoxReady", "beginDate": "2026-05-01T00:00:00Z", "endDate": "2026-05-07T23:59:59Z", "pageNo": 1, "recordsPerPage": 25 },
    headers=headers,
)

response.raise_for_status()
print(response.json())

See Also

• Pending Inbox List — faster check for parcels with InBoxReady status only
• Download Parcel — download a parcel returned from this list
• Outbox List — search outbound parcels