curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/orders/recover?key=thank-you-2026-q3-jane-doe" \
-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.recover("thank-you-2026-q3-jane-doe");
console.log(order.order_id);
order = client.physical_mail.recover("thank-you-2026-q3-jane-doe")
print(order["order_id"])
{
"order_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000",
"order_status": "accepted",
"payment_status": "settled",
"fulfillment_status": "accepted",
"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": [],
"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
Recover an order
Find the order a send created, by its Idempotency-Key
GET
/
v1
/
tools
/
physical-mail
/
orders
/
recover
curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/orders/recover?key=thank-you-2026-q3-jane-doe" \
-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.recover("thank-you-2026-q3-jane-doe");
console.log(order.order_id);
order = client.physical_mail.recover("thank-you-2026-q3-jane-doe")
print(order["order_id"])
{
"order_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000",
"order_status": "accepted",
"payment_status": "settled",
"fulfillment_status": "accepted",
"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": [],
"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
Finds the order created by a Send that carried thisIdempotency-Key. Use it after a timeout or a lost response instead of sending again. Free.
404 order_not_found means no send with that key reached OneShot, so it is safe to send with the same key.
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.
Query Parameters
string
required
The
Idempotency-Key of the send (1 to 255 characters of [A-Za-z0-9_.:-])Response
The order. Its fields are listed on Get an order.curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/orders/recover?key=thank-you-2026-q3-jane-doe" \
-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.recover("thank-you-2026-q3-jane-doe");
console.log(order.order_id);
order = client.physical_mail.recover("thank-you-2026-q3-jane-doe")
print(order["order_id"])
{
"order_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000",
"order_status": "accepted",
"payment_status": "settled",
"fulfillment_status": "accepted",
"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": [],
"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"
}