{"openapi":"3.1.0","info":{"title":"Postedly Send API","version":"1.0.0","description":"One document or selected product, one recipient, one approved quote. An agent that already has the file should upload its bytes directly with POST /api/documents using its existing OAuth bearer token, then use the returned document id for a quote. Do not create a separate guest session for an OAuth-connected owner. Paid sends require verified email, a current quote, explicit final approval and authoritative payment confirmation. Uploading alone never pays or sends. Availability is live; unavailable services cannot be purchased. All examples are synthetic, not live prices, credentials or fulfillment evidence. After an ambiguous checkout result, read existing orders before continuing; never blindly retry a payment or create a replacement order."},"servers":[{"url":"https://postedly.com"}],"components":{"securitySchemes":{"sessionBearer":{"type":"http","scheme":"bearer","description":"Secure guest-session token or OAuth 2.1 access token. Agents should reuse the approved OAuth connection; document upload and preview require quotes:write. Tokens belong in Authorization headers, never chat, query strings or logs."}},"schemas":{"Service":{"type":"string","enum":["fax","letter","certified","postcard","print","handwritten"]},"CatalogService":{"type":"object","required":["id","name","available","startingPriceCents","priceType"],"properties":{"id":{"$ref":"#/components/schemas/Service"},"name":{"type":"string"},"description":{"type":"string"},"provider":{"type":"string"},"requiresDocument":{"type":"boolean"},"available":{"type":"boolean"},"unavailableReason":{"type":["string","null"]},"startingPriceCents":{"type":["integer","null"],"description":"USD price before applicable tax. Only advertise for available services; obtain a quote for eligibility and final total."},"priceType":{"type":["string","null"],"enum":["fixed","from",null],"description":"fixed means one service price for eligible orders. from means a variable starting price. Standard handwritten-card fixed pricing includes US postage."},"documentRequirements":{"type":"object"}}},"LineItem":{"type":"object","required":["label","amountCents"],"properties":{"label":{"type":"string"},"amountCents":{"type":"integer","minimum":0,"description":"Amount in integer US cents; never a floating-point dollar amount."}}},"Quote":{"type":"object","required":["id","service","amountCents","currency","lineItems","expiresAt","estimatedDelivery","summary","recipient","sender","options"],"description":"Immutable quote, normally valid for 20 minutes. The document is the final proof (including any fax cover or mail layout), which may differ from the uploaded file. Review this proof and the normalized contact/options snapshot. No approval, order or payment is created. Omitted optional properties are not null.","properties":{"id":{"type":"string","format":"uuid","description":"Use as quoteId for the review link or explicitly approved checkout."},"service":{"$ref":"#/components/schemas/Service"},"amountCents":{"type":"integer","minimum":0,"description":"Amount in integer US cents; never a floating-point dollar amount."},"currency":{"type":"string","const":"USD"},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"expiresAt":{"type":"string","format":"date-time"},"estimatedDelivery":{"type":"string","description":"Provider estimate, not guaranteed arrival."},"summary":{"type":"string"},"document":{"$ref":"#/components/schemas/Document"},"recipient":{"$ref":"#/components/schemas/Contact"},"sender":{"$ref":"#/components/schemas/Contact"},"options":{"type":"object","additionalProperties":true,"description":"Saved, provider-validated options for this quote."},"handwritten":{"$ref":"#/components/schemas/HandwrittenReview"}}},"Checkout":{"type":"object","required":["url","orderId"],"description":"An approved order and hosted Stripe payment URL. Receiving this response is not payment or fulfillment confirmation. Unlike the MCP postedly_checkout tool, REST POST /api/checkout records approval and creates/reuses an order.","properties":{"url":{"type":"string","format":"uri","description":"Private hosted Stripe Checkout URL. Let the user enter payment details there, never in chat."},"orderId":{"type":"string","format":"uuid","description":"Retain for GET /api/orders/{id} even if the browser closes or payment is interrupted."}}},"ReviewLink":{"type":"object","required":["url","requiresBrowserApproval","expiresAt","instructions"],"description":"Returned by the MCP postedly_checkout tool only. Creates a private review link without recording approval, creating an order, charging or sending.","properties":{"url":{"type":"string","format":"uri","description":"Secret capability URL. Share only with the sender; do not log it or make it public."},"requiresBrowserApproval":{"const":true},"expiresAt":{"type":"string","format":"date-time"},"instructions":{"type":"string"}}},"PaymentStatus":{"type":"string","enum":["checkout_pending","authorized","paid","failed","cancelled","refund_pending","refunded"],"description":"Separate from fulfillment. authorized is a hold, used for fax before capture following confirmed transmission. paid does not mean sent or delivered. refund_pending is not a completed refund."},"FulfillmentStatus":{"type":"string","enum":["awaiting_payment","queued","submitting","submission_unknown","submitted","processing","sent","delivered","failed","cancelled"],"description":"Recorded provider progression. submission_unknown requires reconciliation, never a blind resend. Fax delivered means all approved pages were confirmed by the receiving machine, not that a person read them. Postal statuses reflect available provider milestones."},"OrderDocument":{"type":"object","required":["id","name","pages","bytes","sha256"],"description":"Stored order document metadata; this response does not include a preview URL or contentType. Mail orders may refer to the source document, while the quote contains its final print proof.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"pages":{"type":"integer","minimum":1},"bytes":{"type":"integer","minimum":1},"sha256":{"$ref":"#/components/schemas/Sha256"}}},"OrderEvent":{"type":"object","required":["id","type","message","createdAt"],"properties":{"id":{"type":"string","description":"Opaque event identifier, not necessarily a UUID."},"type":{"type":"string","description":"Extensible event type; do not treat it as a payment/fulfillment enum."},"message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Order":{"type":"object","required":["id","service","amountCents","refundedCents","currency","paymentStatus","fulfillmentStatus","createdAt","updatedAt","recipient","sender","options","timeline","canCancel"],"properties":{"id":{"type":"string","format":"uuid"},"service":{"type":"string","description":"Recorded service; historical orders can retain a service no longer offered."},"amountCents":{"type":"integer","minimum":0,"description":"Amount in integer US cents; never a floating-point dollar amount."},"refundedCents":{"type":"integer","minimum":0,"description":"Amount in integer US cents; never a floating-point dollar amount."},"currency":{"type":"string","const":"usd","description":"Order storage uses lowercase usd; quote responses use uppercase USD."},"paymentStatus":{"$ref":"#/components/schemas/PaymentStatus"},"fulfillmentStatus":{"$ref":"#/components/schemas/FulfillmentStatus"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"recipient":{"$ref":"#/components/schemas/Contact"},"sender":{"$ref":"#/components/schemas/Contact"},"options":{"type":"object","additionalProperties":true},"handwritten":{"$ref":"#/components/schemas/HandwrittenReview"},"document":{"$ref":"#/components/schemas/OrderDocument"},"checkoutUrl":{"type":["string","null"],"format":"uri","description":"Present only while paymentStatus is checkout_pending; may be null if checkout creation has not completed. Private URL, not payment evidence."},"timeline":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/OrderEvent"},"description":"Up to 200 earliest events, in ascending timestamp order."},"canCancel":{"type":"boolean","description":"True for awaiting_payment or queued. Advisory snapshot; a cancellation race may still return 409."},"evidence":{"type":"object","additionalProperties":true,"description":"Optional provider-specific evidence. Fields vary by channel; do not assume a tracking number or proof of a recipient reading the item."}}},"OrderList":{"type":"object","required":["orders"],"properties":{"orders":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Order"},"description":"HTTP returns up to 100 newest orders. MCP postedly_orders returns up to 50."}}},"DocumentService":{"type":"string","enum":["fax","letter","certified","postcard","print"]},"Sha256":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$","description":"SHA-256 of the exact raw file bytes, as 64 hexadecimal characters."},"Document":{"type":"object","required":["id","name","pages","bytes","sha256","contentType","previewUrl"],"properties":{"id":{"type":"string","format":"uuid","description":"Use this value as documentId in a quote; the person does not need to copy it."},"name":{"type":"string","maxLength":180},"pages":{"type":"integer","minimum":1,"description":"Inspected page count; images count as one. Upload PDFs allow up to 50 pages; service-specific quote limits can be lower."},"bytes":{"type":"integer","minimum":1,"maximum":10485760},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Server-computed SHA-256 of the stored raw file bytes."},"contentType":{"type":"string","enum":["application/pdf","image/jpeg","image/png"],"description":"Detected media type, not a trusted client declaration."},"previewUrl":{"type":"string","format":"uri-reference","description":"Private preview. Standard document URLs require the same owner’s bearer token; capability-scoped handoff URLs require their unexpired ticket. Resolve relative URLs against this API origin. Never make the file public to show a preview."}}},"DocumentHandoff":{"type":"object","required":["documentRequestId","service","status","expiresAt"],"properties":{"documentRequestId":{"type":"string","format":"uuid"},"service":{"$ref":"#/components/schemas/DocumentService"},"filename":{"type":["string","null"]},"status":{"type":"string","enum":["awaiting_upload","uploading","complete","expired"]},"expiresAt":{"type":"string","format":"date-time"},"document":{"$ref":"#/components/schemas/Document"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"QuoteRequest":{"type":"object","required":["service","recipient","sender"],"description":"Handwritten cards use an exact catalog card, handwriting style, message and optional closing, with complete US sender and recipient addresses. No PDF upload is required. Catalog character limits apply to the exact raw text.","allOf":[{"if":{"properties":{"service":{"const":"handwritten"}},"required":["service"]},"then":{"required":["options"],"properties":{"options":{"type":"object","required":["productId","fontLabel","message"],"additionalProperties":false,"properties":{"productId":{"type":"string","pattern":"^[1-9]\\d{0,14}$"},"fontLabel":{"type":"string","minLength":1,"maxLength":100},"message":{"type":"string","minLength":1,"maxLength":1000,"pattern":"\\S"},"wishes":{"type":"string","maxLength":200,"default":""},"quantity":{"type":"integer","const":1}},"description":"The selected card’s catalog limits are authoritative. Raw message.length plus wishes.length must fit combinedCharacterLimit, never above 1000. Plain text only; signature codes, QR codes and template substitutions are not supported."},"sender":{"type":"object","required":["name","address1","city","state","postalCode","country"],"properties":{"country":{"const":"US"}},"description":"Omit email to reuse the connected account’s verified email; unverified sessions must supply it."},"recipient":{"type":"object","required":["name","address1","city","state","postalCode","country"],"properties":{"country":{"const":"US"}}}}},"else":{"properties":{"options":{"properties":{"message":{"type":"string","maxLength":500}}}}}}],"properties":{"service":{"type":"string","enum":["fax","letter","certified","postcard","print","handwritten"]},"documentId":{"type":"string","format":"uuid","description":"The id returned by an upload owned by this same session/OAuth connection. Required for document channels; handwritten cards do not require an upload."},"recipient":{"$ref":"#/components/schemas/Contact"},"sender":{"allOf":[{"$ref":"#/components/schemas/Contact"}],"description":"Omit email to reuse the current connected account’s verified email. An unverified session must supply email and complete verification before checkout. Explicit values are never overwritten. Sender name and service-specific return/billing address remain required."},"options":{"type":"object","additionalProperties":true,"properties":{"productId":{"type":"string","description":"Exact product id returned by the current product catalog."},"fontLabel":{"type":"string","minLength":1,"maxLength":100,"description":"Handwritten cards only. Exact label from the selected card’s options.handwritingStyles; a style ID is not a substitute for this label."},"wishes":{"type":"string","maxLength":200,"default":"","description":"Handwritten cards only. Exact optional closing. Raw message.length + wishes.length must not exceed the card’s options.combinedCharacterLimit; no separator is added to this count."},"sku":{"type":"string","description":"Exact print SKU returned by the current product catalog."},"quantity":{"type":"integer","const":1,"description":"One selected item per order."},"message":{"type":"string","maxLength":1000,"description":"Exact personal message. Handwritten cards require nonempty text, at most options.maxMessageLength (never above 1000), with message plus wishes within options.combinedCharacterLimit."}}}}},"Contact":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"fax":{"type":"string"},"phone":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string","default":"US"}}},"HandwritingStyle":{"type":"object","required":["id","label","imageUrl"],"properties":{"id":{"type":"string","description":"Provider style identifier; quote input uses the exact label instead."},"label":{"type":"string"},"imageUrl":{"type":"string","format":"uri","pattern":"^https://","description":"Handwriting-style sample, not a rendering of the submitted message."}}},"HandwrittenProductOptions":{"type":"object","required":["handwritingStyles","maxMessageLength","maxWishesLength","combinedCharacterLimit"],"properties":{"handwritingStyles":{"type":"array","items":{"$ref":"#/components/schemas/HandwritingStyle"}},"maxMessageLength":{"type":"integer","minimum":1,"maximum":1000},"maxWishesLength":{"type":"integer","minimum":0,"maximum":200},"combinedCharacterLimit":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum raw message.length plus wishes.length, without trimming or an added separator."}}},"HandwrittenReview":{"type":"object","required":["cardId","cardName","cardImageUrl","fontId","fontLabel","fontImageUrl","message","wishes","sender","recipient","previewKind","stampOptionId","stampName"],"description":"Immutable quoted card, handwriting style, exact text, postal addresses and postage option. Images are design/style samples, not a rendered final-message proof.","properties":{"cardId":{"type":"string","pattern":"^[1-9]\\d{0,14}$"},"cardName":{"type":"string"},"cardImageUrl":{"type":"string","format":"uri","pattern":"^https://"},"fontId":{"type":"string"},"fontLabel":{"type":"string"},"fontImageUrl":{"type":"string","format":"uri","pattern":"^https://"},"message":{"type":"string","minLength":1,"maxLength":1000},"wishes":{"type":"string","maxLength":200},"sender":{"$ref":"#/components/schemas/Contact"},"recipient":{"$ref":"#/components/schemas/Contact"},"previewKind":{"type":"string","const":"design_and_style_samples"},"stampOptionId":{"type":"integer"},"stampName":{"type":"string"}}}}},"paths":{"/api/catalog":{"get":{"summary":"Current channel availability","operationId":"listServices","security":[],"responses":{"200":{"description":"Service list with fixed or variable pricing. Do not advertise unavailable services as purchasable.","content":{"application/json":{"schema":{"type":"object","required":["services"],"properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/CatalogService"}}}}}}}}}},"/api/session":{"post":{"summary":"Create a scoped guest session","operationId":"createGuestSession","security":[],"description":"For clients without an OAuth connection. Do not replace an existing approved OAuth connection with a new guest session.","responses":{"200":{"description":"Session token; keep secret"}}},"get":{"summary":"Current session verification status","security":[{"sessionBearer":[]}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found or belongs to another owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getSession"}},"/api/products":{"get":{"summary":"Curated provider products","security":[],"responses":{"200":{"description":"Product catalog; handwritten item options follow HandwrittenProductOptions.","content":{"application/json":{"schema":{"type":"object","required":["products"],"properties":{"products":{"type":"array","items":{"type":"object","allOf":[{"if":{"properties":{"service":{"const":"handwritten"}},"required":["service"]},"then":{"properties":{"options":{"$ref":"#/components/schemas/HandwrittenProductOptions"}}}}]}}}}}}},"400":{"description":"Unsupported product service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Product catalog unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listProducts","description":"Read-only product discovery can remain available while ordering is closed. A purchase requires both the service and product to be available. Handwritten products use numeric string IDs and expose card images plus handwriting style samples and character limits.","parameters":[{"name":"service","in":"query","required":true,"schema":{"type":"string","enum":["print","handwritten"]}}]}},"/api/documents":{"post":{"summary":"Upload a file directly from an agent or application","operationId":"uploadDocument","security":[{"sessionBearer":[]}],"description":"Preferred for an agent that has file bytes and authenticated HTTP access. Reuse its existing OAuth bearer token with quotes:write, send multipart fields file, service (optional; defaults to fax) and optional expectedSha256. Return HTTP 201 with a Document object directly: its id is the quote documentId. Validate the returned hash against the source. There is no user download/re-upload step and no arbitrary URL import. Stored upload acceptance does not guarantee a selected product or service can quote the file; quote preflight applies exact product dimensions/page limits and generates the final proof for approval. Uploading neither charges nor sends.","x-required-oauth-scopes":["quotes:write"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Actual file bytes, from 1 byte through 10 MiB (10,485,760 bytes). Not a URL, data URL, base64 string, or local path. Format is inspected from the bytes. Fax, letter, certified and postcard require valid unencrypted PDF. Print ingestion accepts PDF/JPEG/PNG, but the selected product must accept that format; the current live print products accept PDF/JPEG only.","x-maxFileBytes":10485760},"service":{"$ref":"#/components/schemas/DocumentService","default":"fax","description":"Choose the intended service explicitly. Omission preserves the fax default."},"expectedSha256":{"$ref":"#/components/schemas/Sha256","description":"Optional source checksum. A mismatch is rejected before storage."}}},"encoding":{"file":{"contentType":"application/pdf, image/jpeg, image/png"}}}}},"responses":{"201":{"description":"Validated document saved privately for the authenticated owner. This is the Document object itself, not an envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Invalid service, missing file, invalid SHA-256, hash mismatch, invalid or encrypted PDF, unsupported format, or document limits exceeded. No document is saved when validation fails.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Valid session or OAuth bearer token required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"OAuth token requires quotes:write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the bounded upload envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Upload rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Upload could not be stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/documents/{id}":{"get":{"summary":"Read the authenticated owner’s private document","security":[{"sessionBearer":[]}],"responses":{"200":{"description":"Raw private file bytes, not JSON. Authorization is required; URL possession alone is insufficient.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Document not found or belongs to another owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Document is no longer retained","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getDocument","x-required-oauth-scopes":["quotes:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/api/document-handoffs/{ticket}":{"parameters":[{"name":"ticket","in":"path","required":true,"schema":{"type":"string"},"description":"Secret, owner-bound capability returned by postedly_prepare_document; 15-minute lifetime. Do not log or expose it beyond the intended upload."}],"get":{"summary":"Read a prepared upload handoff","operationId":"getDocumentHandoff","security":[],"responses":{"200":{"description":"Handoff state; document is present after completion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentHandoff"}}}},"404":{"description":"Invalid ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Expired ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Upload bytes to a prepared single-use handoff","operationId":"uploadPreparedDocument","security":[],"description":"Use the exact uploadEndpoint returned by postedly_prepare_document. The ticket authorizes one successful file upload for its connected owner and fixed service; no separate bearer token or guest session is needed. Only file is supplied. Prefer authenticated POST /api/documents when the agent already has file bytes and authenticated HTTP access. This route enables runtime upload with a prepared ticket; the returned browser uploadUrl is a fallback when the agent cannot access the bytes. No arbitrary URL import.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Actual file bytes, from 1 byte through 10 MiB (10,485,760 bytes). Not a URL, data URL, base64 string, or local path. Format is inspected from the bytes. Fax, letter, certified and postcard require valid unencrypted PDF. Print ingestion accepts PDF/JPEG/PNG, but the selected product must accept that format; the current live print products accept PDF/JPEG only.","x-maxFileBytes":10485760}}},"encoding":{"file":{"contentType":"application/pdf, image/jpeg, image/png"}}}}},"responses":{"201":{"description":"Handoff complete with its private document metadata and SHA-256.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/DocumentHandoff"},{"type":"object","required":["document"],"properties":{"status":{"const":"complete"}}}]}}}},"400":{"description":"Invalid service, missing file, invalid SHA-256, hash mismatch, invalid or encrypted PDF, unsupported format, or document limits exceeded. No document is saved when validation fails.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Invalid ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Handoff already used or another upload claimed it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Expired ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the bounded upload envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Upload rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/quotes":{"post":{"summary":"Create an immutable, tax-inclusive quote","security":[{"sessionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"201":{"description":"Immutable quote and final proof; explicit approval is still required. Handwritten cards contain design/style samples, exact text and addresses rather than a rendered final message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"},"example":{"id":"22222222-2222-4222-8222-222222222222","service":"fax","amountCents":300,"currency":"USD","lineItems":[{"label":"Postedly fax","amountCents":300},{"label":"Sales tax","amountCents":0}],"expiresAt":"2026-09-20T18:20:00.000Z","estimatedDelivery":"Usually within minutes","summary":"fax to Example Recipient","document":{"id":"11111111-1111-4111-8111-111111111111","name":"Example.pdf","pages":1,"bytes":2048,"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","contentType":"application/pdf","previewUrl":"/api/documents/11111111-1111-4111-8111-111111111111"},"recipient":{"name":"Example Recipient","fax":"+12025550123","country":"US"},"sender":{"name":"Example Sender","email":"sender@example.com","state":"CA","postalCode":"94107","country":"US"},"options":{}}}}},"400":{"description":"Invalid input, missing document/address, unsupported destination/options, or price limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Document not found or belongs to another owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Provider or quote state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"DOCUMENT_EXPIRED: upload is no longer retained","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"File or recipient does not meet the selected service’s requirements","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Quote rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal failure; outcome unconfirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider quote, price, tax calculation or final preview failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service, tax calculation or mail capacity unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createQuote","x-required-oauth-scopes":["quotes:write"],"description":"Use for an intended physical send, not merely drafting a letter or emailing a PDF. Creates no order, approval, charge or send. The synthetic response example is not a current price or delivery promise. Always use the returned current total and expiry."}},"/api/checkout":{"post":{"summary":"Approve quote and create hosted checkout","security":[{"sessionBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quoteId","acceptedTerms","confirmedDocument"],"properties":{"quoteId":{"type":"string","format":"uuid"},"acceptedTerms":{"const":true},"confirmedDocument":{"const":true}}}}}},"responses":{"200":{"description":"Approved order ID and hosted payment URL; not confirmation of payment or sending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"},"example":{"url":"https://checkout.stripe.com/c/pay/ILLUSTRATIVE_NOT_VALID","orderId":"33333333-3333-4333-8333-333333333333"}}}},"400":{"description":"APPROVAL_REQUIRED: explicit document and terms confirmation missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"INSUFFICIENT_SCOPE or EMAIL_VERIFICATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Quote not found or belongs to another owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"QUOTE_EXPIRED, CHECKOUT_EXPIRED, CHECKOUT_CONFLICT, ORDER_CANCELLED or ORDER_ALREADY_PAID; use the existing order status or request a fresh quote only when appropriate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Order or recipient limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Order or checkout outcome unconfirmed; inspect existing orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"CHECKOUT_FAILED: hosted checkout could not be opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service, secure checkout or mail capacity unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createCheckout","x-required-oauth-scopes":["checkout:write"],"description":"Call only after the sender explicitly approves the exact final proof or item, recipient, total and terms. A verified sender email matching the connected owner is required. This REST endpoint records approval and creates/reuses the order. Agents should normally use MCP postedly_checkout instead: it returns a private browser review link where the user can approve. On an ambiguous result, read existing orders before deciding what to do; never blindly replay checkout or create a replacement quote/order."}},"/api/orders":{"get":{"summary":"List session orders","security":[{"sessionBearer":[]}],"responses":{"200":{"description":"Up to 100 newest orders for the authenticated owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"},"example":{"orders":[{"id":"33333333-3333-4333-8333-333333333333","service":"fax","amountCents":300,"refundedCents":0,"currency":"usd","paymentStatus":"authorized","fulfillmentStatus":"queued","createdAt":"2026-09-20T18:05:00.000Z","updatedAt":"2026-09-20T18:06:00.000Z","recipient":{"name":"Example Recipient","fax":"+12025550123","country":"US"},"sender":{"name":"Example Sender","email":"sender@example.com","state":"CA","postalCode":"94107","country":"US"},"options":{},"document":{"id":"11111111-1111-4111-8111-111111111111","name":"Example.pdf","pages":1,"bytes":2048,"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"timeline":[{"id":"44444444-4444-4444-8444-444444444444","type":"payment_authorized","message":"Card authorized. Capture follows successful fax transmission.","createdAt":"2026-09-20T18:06:00.000Z"}],"canCancel":true}]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Order list could not be read; do not infer no orders exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listOrders","x-required-oauth-scopes":["orders:read"]}},"/api/orders/{id}":{"get":{"summary":"Read actual payment and fulfillment status","security":[{"sessionBearer":[]}],"responses":{"200":{"description":"Owned order with separate payment and fulfillment states.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"example":{"id":"33333333-3333-4333-8333-333333333333","service":"fax","amountCents":300,"refundedCents":0,"currency":"usd","paymentStatus":"authorized","fulfillmentStatus":"queued","createdAt":"2026-09-20T18:05:00.000Z","updatedAt":"2026-09-20T18:06:00.000Z","recipient":{"name":"Example Recipient","fax":"+12025550123","country":"US"},"sender":{"name":"Example Sender","email":"sender@example.com","state":"CA","postalCode":"94107","country":"US"},"options":{},"document":{"id":"11111111-1111-4111-8111-111111111111","name":"Example.pdf","pages":1,"bytes":2048,"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"timeline":[{"id":"44444444-4444-4444-8444-444444444444","type":"payment_authorized","message":"Card authorized. Capture follows successful fax transmission.","createdAt":"2026-09-20T18:06:00.000Z"}],"canCancel":true}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found or belongs to another owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Order state could not be read; outcome remains unconfirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getOrder","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"x-required-oauth-scopes":["orders:read"],"description":"Reads recorded state and timeline; this read does not initiate a send or force provider reconciliation. Payment and fulfillment are separate. Do not infer delivery from a checkout redirect."}},"/api/orders/{id}/cancel":{"post":{"summary":"Cancel only when safely possible","security":[{"sessionBearer":[]}],"responses":{"200":{"description":"Updated order after confirmed cancellation; refund may still be pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found or belongs to another owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CANNOT_CANCEL or CANCELLATION_PENDING; reconcile existing status before further action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Cancellation outcome unconfirmed; read existing order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider or payment processor could not confirm cancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider or payment service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cancelOrder","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"x-required-oauth-scopes":["checkout:write"],"description":"Request only an intended cancellation. Provider confirmation may be required after submission. Returns the updated order; inspect paymentStatus for authorization cancellation or refund progress. A lost response must be resolved by reading this order before another mutation."}}}}