curl -X POST https://win.oneshotagent.com/v1/tools/physical-mail/send \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -H "x-agent-proof: <base64 signed proof, scope=submit>" \
  -H "Idempotency-Key: thank-you-2026-q3-jane-doe" \
  -d '{
    "quote_id": "00000000-0000-4000-8000-000000000000",
    "approval_id": "00000000-0000-4000-8000-000000000000",
    "memo": "Q3 customer thank-you letter"
  }'

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

const order = await agent.physicalMail.send({
  quote_id: approval.quote_id,
  approval_id: approval.approval_id,
  idempotencyKey: savedKey, // saved before this call
  maxCost: Number(quote.total_usdc),
  memo: "Q3 customer thank-you letter",
});

order = client.physical_mail.send(
    quote_id=approval["quote_id"],
    approval_id=approval["approval_id"],
    idempotency_key=saved_key,
    max_cost=float(quote["total_usdc"]),
    memo="Q3 customer thank-you letter",
)

{
  "order_id": "00000000-0000-4000-8000-000000000000",
  "quote_id": "00000000-0000-4000-8000-000000000000",
  "order_status": "pending",
  "payment_status": "pending",
  "fulfillment_status": "pending",
  "receipt_id": "rcpt_...",
  "signed_receipt": null,
  "total_usdc": "<the quote's total_usdc>",
  "idempotency_key": "thank-you-2026-q3-jane-doe",
  "events": [],
  "cancellation_requested": false,
  "cancellation_error": null,
  "cancel_before": null,
  "refunded_at": null,
  "delivery_proves_readership": false
}

{
  "error": "insufficient_credits",
  "required_usdc": "<the quote's total_usdc>",
  "credits_balance": "<your credits balance>",
  "shortfall_usdc": "<required_usdc minus credits_balance>",
  "quote_id": "00000000-0000-4000-8000-000000000000"
}

{
  "error": "approval_required",
  "status": "pending_approval",
  "message": "This physical_mail call needs a human approval (rule <rule id>). It was not run or charged. Retry the same call with X-Approval-Id once approved.",
  "approval_id": "<policy approval id>",
  "approval": { "...": "the pending approval" }
}

{
  "error": "approval_required_or_expired"
}