Pending Inbox List

Return all inbound parcels with InBoxReady status that have not yet been downloaded.

Endpoint

POST /v2/parcels/pending-inbox-list

Request Body

Field	Type	Required	Constraints	Description
mailboxId	int	No		Mailbox to check for pending parcels; defaults to authenticated user's mailbox

:::info Efficient Polling This endpoint is optimized for polling loops. It returns only unread parcels (InBoxReady) without requiring date range filters or pagination parameters, making it more efficient than Inbox List for routine file pickup checks. :::

{
  "mailboxId": 1001
}

Response

Returns an array of ParcelIDInfo objects where each parcel has InBoxReady status.

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

Code Examples

cURL

curl -X POST "https://rest.ecgrid.io/v2/parcels/pending-inbox-list" \
  -H "X-API-Key: $ECGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mailboxId": 1001 }'

C#

// .NET 10 — poll for pending inbound parcels and download each one
using System.Net.Http.Json;

var listRequest = new { mailboxId = 1001 };

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

var result = await response.Content.ReadFromJsonAsync<ApiResponse<List<ParcelIdInfo>>>();

foreach (var parcel in result!.Data)
{
    // Download each pending parcel
    var downloadResponse = await http.PostAsJsonAsync(
        "https://rest.ecgrid.io/v2/parcels/download",
        new { parcelId = parcel.ParcelId });
    downloadResponse.EnsureSuccessStatusCode();

    var download = await downloadResponse.Content
        .ReadFromJsonAsync<ApiResponse<ParcelDownload>>();
    var ediBytes = Convert.FromBase64String(download!.Data.Content);
    await File.WriteAllBytesAsync(download.Data.FileName, ediBytes);

    // Confirm after saving so ECGrid marks the parcel as transferred
    await http.PostAsJsonAsync(
        "https://rest.ecgrid.io/v2/parcels/confirm",
        new { parcelId = parcel.ParcelId });

    Console.WriteLine($"Processed parcel {parcel.ParcelId} — {parcel.FileName}");
}

Java

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

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

String body = "{ \"mailboxId\": 1001 }";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://rest.ecgrid.io/v2/parcels/pending-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/pending-inbox-list';

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ "mailboxId": 1001 }),
});

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/pending-inbox-list"

response = requests.post(
    url,
    json={ "mailboxId": 1001 },
    headers=headers,
)

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

See Also

• Download Parcel — download a parcel's EDI content
• Confirm Download — acknowledge delivery after saving
• Inbox List — full paginated inbox search with date and status filters