curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/orders/00000000-0000-4000-8000-000000000000" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=read>"
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const order = await agent.physicalMail.getOrder("00000000-0000-4000-8000-000000000000");
console.log(order.order_status, order.fulfillment_status);
order = client.physical_mail.get_order("00000000-0000-4000-8000-000000000000")
print(order["order_status"], order["fulfillment_status"])
{
"order_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000",
"order_status": "accepted",
"payment_status": "settled",
"fulfillment_status": "in_transit",
"receipt_id": "rcpt_...",
"signed_receipt": { "receiptId": "rcpt_...", "signature": "<signature>" },
"total_usdc": "<the quote's total_usdc>",
"idempotency_key": "thank-you-2026-q3-jane-doe",
"events": [
{ "event_id": "evt_...", "event_type": "letter.mailed", "occurred_at": "2026-10-30T15:00:00.000Z" },
{ "event_id": "evt_...", "event_type": "letter.in_transit", "occurred_at": "2026-10-31T09:00:00.000Z" }
],
"cancellation_requested": false,
"cancellation_error": null,
"cancel_before": "2026-10-30T14:00:00.000Z",
"refunded_at": null,
"delivery_proves_readership": false
}
{
"error": "order_not_found"
}
Physical Mail
Get an order
Read a mail order: its status, payment, delivery events and signed receipt
GET
/
v1
/
tools
/
physical-mail
/
orders
/
{id}
curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/orders/00000000-0000-4000-8000-000000000000" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=read>"
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const order = await agent.physicalMail.getOrder("00000000-0000-4000-8000-000000000000");
console.log(order.order_status, order.fulfillment_status);
order = client.physical_mail.get_order("00000000-0000-4000-8000-000000000000")
print(order["order_status"], order["fulfillment_status"])
{
"order_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000",
"order_status": "accepted",
"payment_status": "settled",
"fulfillment_status": "in_transit",
"receipt_id": "rcpt_...",
"signed_receipt": { "receiptId": "rcpt_...", "signature": "<signature>" },
"total_usdc": "<the quote's total_usdc>",
"idempotency_key": "thank-you-2026-q3-jane-doe",
"events": [
{ "event_id": "evt_...", "event_type": "letter.mailed", "occurred_at": "2026-10-30T15:00:00.000Z" },
{ "event_id": "evt_...", "event_type": "letter.in_transit", "occurred_at": "2026-10-31T09:00:00.000Z" }
],
"cancellation_requested": false,
"cancellation_error": null,
"cancel_before": "2026-10-30T14:00:00.000Z",
"refunded_at": null,
"delivery_proves_readership": false
}
{
"error": "order_not_found"
}
Overview
Returns one order. Free. Delivery events are postal observations, never evidence the mail was read.Authentication
X-Agent-ID plus a signed x-agent-proof with scope: "read", or an access token. See proof authentication. 60 requests a minute per agent.
Path Parameters
Response
string
Order ID
string
The quote this order bought
string
pending, submitting, accepted, canceled, failed, or needs_reconciliation (acceptance unconfirmed)string
pending, leased, settled, failed or unknownstring
pending, accepted, mailed, in_transit, in_local_area, processed_for_delivery, delivered, returned_to_sender, canceled or render_failedstring
Receipt ID
object | null
The signed receipt. Null while
order_status is pending, submitting or needs_reconciliation; signed once it reaches accepted, canceled or failed. Independent of fulfillment_status: the receipt does not wait for delivery.string
Amount charged, as a decimal string
string
The
Idempotency-Key the send carriedarray
Postal events, oldest first. Each has
event_id, event_type and occurred_at.string | null
Why a requested cancellation did not take effect
string | null
Estimated last moment a cancellation can still take effect
string | null
When the order was refunded as credits
boolean
Always
falsecurl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/orders/00000000-0000-4000-8000-000000000000" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=read>"
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const order = await agent.physicalMail.getOrder("00000000-0000-4000-8000-000000000000");
console.log(order.order_status, order.fulfillment_status);
order = client.physical_mail.get_order("00000000-0000-4000-8000-000000000000")
print(order["order_status"], order["fulfillment_status"])
{
"order_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000",
"order_status": "accepted",
"payment_status": "settled",
"fulfillment_status": "in_transit",
"receipt_id": "rcpt_...",
"signed_receipt": { "receiptId": "rcpt_...", "signature": "<signature>" },
"total_usdc": "<the quote's total_usdc>",
"idempotency_key": "thank-you-2026-q3-jane-doe",
"events": [
{ "event_id": "evt_...", "event_type": "letter.mailed", "occurred_at": "2026-10-30T15:00:00.000Z" },
{ "event_id": "evt_...", "event_type": "letter.in_transit", "occurred_at": "2026-10-31T09:00:00.000Z" }
],
"cancellation_requested": false,
"cancellation_error": null,
"cancel_before": "2026-10-30T14:00:00.000Z",
"refunded_at": null,
"delivery_proves_readership": false
}
{
"error": "order_not_found"
}
Notes
- Returns only your agent’s orders.
- A confirmed cancellation or a failure before production refunds the full amount as credits, once. Returned mail is not refunded.