curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/quotes/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 quote = await agent.physicalMail.getQuote("00000000-0000-4000-8000-000000000000");
console.log(quote.status, quote.total_usdc);
quote = client.physical_mail.get_quote("00000000-0000-4000-8000-000000000000")
print(quote["status"], quote["total_usdc"])
{
"quote_id": "00000000-0000-4000-8000-000000000000",
"input": {
"to": { "name": "Jane Doe", "address_line1": "185 BERRY ST", "address_city": "SAN FRANCISCO", "address_state": "CA", "address_zip": "94107", "address_country": "US" },
"from": { "name": "Acme Inc", "address_line1": "1 MAIN ST", "address_city": "AUSTIN", "address_state": "TX", "address_zip": "78701", "address_country": "US" },
"artwork": { "kind": "letter", "file": "00000000-0000-4000-8000-000000000000", "color": false, "double_sided": false }
},
"input_hash": "<64 hex characters>",
"status": "ready",
"preview": {
"url": "https://.../proof.pdf",
"thumbnails": [{ "small": "https://.../small.png", "medium": "https://.../medium.png", "large": "https://.../large.png" }]
},
"total_usdc": "<decimal string>",
"service_fee_usdc": "<the part of total_usdc that is the fee>",
"expires_at": "2026-10-29T12:30:00.000Z",
"approval_id": null,
"delivery_proves_readership": false
}
{
"error": "quote_not_found"
}
{
"error": "proof_render_failed"
}
Physical Mail
Get a quote
Read a mail quote: its status, proof, price and approval
GET
/
v1
/
tools
/
physical-mail
/
quotes
/
{id}
curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/quotes/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 quote = await agent.physicalMail.getQuote("00000000-0000-4000-8000-000000000000");
console.log(quote.status, quote.total_usdc);
quote = client.physical_mail.get_quote("00000000-0000-4000-8000-000000000000")
print(quote["status"], quote["total_usdc"])
{
"quote_id": "00000000-0000-4000-8000-000000000000",
"input": {
"to": { "name": "Jane Doe", "address_line1": "185 BERRY ST", "address_city": "SAN FRANCISCO", "address_state": "CA", "address_zip": "94107", "address_country": "US" },
"from": { "name": "Acme Inc", "address_line1": "1 MAIN ST", "address_city": "AUSTIN", "address_state": "TX", "address_zip": "78701", "address_country": "US" },
"artwork": { "kind": "letter", "file": "00000000-0000-4000-8000-000000000000", "color": false, "double_sided": false }
},
"input_hash": "<64 hex characters>",
"status": "ready",
"preview": {
"url": "https://.../proof.pdf",
"thumbnails": [{ "small": "https://.../small.png", "medium": "https://.../medium.png", "large": "https://.../large.png" }]
},
"total_usdc": "<decimal string>",
"service_fee_usdc": "<the part of total_usdc that is the fee>",
"expires_at": "2026-10-29T12:30:00.000Z",
"approval_id": null,
"delivery_proves_readership": false
}
{
"error": "quote_not_found"
}
{
"error": "proof_render_failed"
}
Overview
Returns a quote created by Preview. Poll it whilestatus is rendering. Once ready, it carries the proof URL, input_hash and total_usdc that Approve repeats. Free.
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
string
required
Quote ID from the preview
Response
string
Quote ID
object
The
to, from and artwork the quote was made for, with both addresses standardisedstring
Hash of
input, 64 hex characters. Approve repeats it.string
rendering or readyobject
url of the rendered proof (null while rendering) and thumbnailsstring | null
The part of
total_usdc that is the service fee. Null until ready.string
ISO timestamp. The quote cannot be approved or sent after it.
string | null
Set once the quote has been approved
boolean
Always
false. Delivery events are postal observations, never evidence the mail was read.curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/quotes/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 quote = await agent.physicalMail.getQuote("00000000-0000-4000-8000-000000000000");
console.log(quote.status, quote.total_usdc);
quote = client.physical_mail.get_quote("00000000-0000-4000-8000-000000000000")
print(quote["status"], quote["total_usdc"])
{
"quote_id": "00000000-0000-4000-8000-000000000000",
"input": {
"to": { "name": "Jane Doe", "address_line1": "185 BERRY ST", "address_city": "SAN FRANCISCO", "address_state": "CA", "address_zip": "94107", "address_country": "US" },
"from": { "name": "Acme Inc", "address_line1": "1 MAIN ST", "address_city": "AUSTIN", "address_state": "TX", "address_zip": "78701", "address_country": "US" },
"artwork": { "kind": "letter", "file": "00000000-0000-4000-8000-000000000000", "color": false, "double_sided": false }
},
"input_hash": "<64 hex characters>",
"status": "ready",
"preview": {
"url": "https://.../proof.pdf",
"thumbnails": [{ "small": "https://.../small.png", "medium": "https://.../medium.png", "large": "https://.../large.png" }]
},
"total_usdc": "<decimal string>",
"service_fee_usdc": "<the part of total_usdc that is the fee>",
"expires_at": "2026-10-29T12:30:00.000Z",
"approval_id": null,
"delivery_proves_readership": false
}
{
"error": "quote_not_found"
}
{
"error": "proof_render_failed"
}
Notes
- Returns only your agent’s quotes.
422 proof_render_failedis final for that quote: fix the artwork and preview again.422 unsupported_letter_lengthmeans the PDF is not 1 to 60 pages.