Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in awaiting_payment and returns a checkout_url. Set certified to send it by USPS Certified Mail.
To send the same letter to several people, pass recipients (2–25 addresses) instead of to. You get back a Batch: one order per recipient and a single batch.checkout_url. POST /orders/{id}/pay with any order in the batch pays for every unpaid order in it (scope the token to batch.price).
POST
/
letters
curl --request POST \ --url https://sendmypaper.com/v1/letters \ --header 'Content-Type: application/json' \ --data '{ "to": { "name": "Pat Lee", "line1": "500 Main St", "line2": "Apt 4", "city": "Boston", "state": "MA", "zip": "02110" }, "from": { "name": "Alex Kim", "line1": "88 Pine Ave", "city": "Denver", "state": "CO", "zip": "80202" }, "content": { "body": "Dear Pat,\n\nThank you for fixing the roof so quickly.\n\nBest,\nAlex", "font": "serif" }}'
Any unique string. Retrying with the same key returns the original order instead of creating a duplicate.
Maximum string length: 120
Body
application/json
Option 1
Option 2
to
object
required
Recipient address Use recipients instead to send to several people.
Show child attributes
from
object
required
Return address. It may be outside the US: set country. For a US address (no country, or US), state and zip are required and follow the US rules; elsewhere state is the region and zip the postcode, both optional.
Show child attributes
content
object
required
Show child attributes
customer_email
string<email>
idempotency_key
string
With recipients, a retry with the same key returns the same batch.
certified
enum<string>
default:none
USPS Certified Mail. certified ($14.99): tracking number and proof of mailing and delivery. certified_return_receipt ($19.99): adds the recipient's signature. none ($4.99): regular First-Class.
Available options:
none,
certified,
certified_return_receipt
express
boolean
default:false
USPS Priority Mail (2-3 days, tracked); not with certified.
recipients
object[]
Send the same postcard or letter to several people: 2–25 addresses, used instead of to. Each recipient becomes its own order (own review, tracking and refund), grouped into a batch that is paid with one checkout link. The response is a Batch, not an Order.
Required array length: 2 - 25 elements
Show child attributes
Response
Idempotency-Key already used: the original order is returned (a Batch when the request used recipients)
Option 1
Option 2
id
string
Example:
"ord_8k2m4qz7c1x9b3vd"
object
enum<string>
Available options:
postcard,
letter
product
enum<string>
Available options:
postcard_4x6,
postcard_6x9,
postcard_6x11,
letter,
letter_certified,
letter_certified_rr
status
enum<string>
Available options:
awaiting_payment,
paid,
printing,
mailed,
cancelled,
refunded
status_detail
string
price
object
Show child attributes
to
object
A US address (recipients are always in the US, including territories and APO/FPO/DPO).
Show child attributes
from
object
Return address. It may be outside the US: set country. For a US address (no country, or US), state and zip are required and follow the US rules; elsewhere state is the region and zip the postcode, both optional.
Show child attributes
content
object
checkout_url
string | null
Where the person pays. Null once paid or closed. Never expires.
order_url
string
Human-readable status page
preview_url
string
Exact print preview
created_at
string<date-time>
paid_at
string<date-time> | null
mailed_at
string<date-time> | null
events
object[]
Show child attributes
certified
enum<string>
Letters only: the USPS extra service.
Available options:
none,
certified,
certified_return_receipt
tracking
object | null
USPS tracking once the piece is accepted (certified letters always get one).
Show child attributes
batch_id
string | null
Set when the order is part of a batch (created with recipients). Its checkout_url is then the batch's single payment link.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Sendpaper","description":"Physical mail for AI agents. Codex, Muse Code, Claude or any MCP client can send real postcards and letters; a person approves and pays, and Sendpaper prints and mails them via USPS.","colors":{"primary":"#0F7A52","light":"#4FD1A1","dark":"#0B5E3F"},"logo":{"light":"https://mintcdn.com/sendpaper/ocvZXr2TobeYH0v1/logo/light.svg?fit=max\u0026auto=format\u0026n=ocvZXr2TobeYH0v1\u0026q=85\u0026s=b4054fbffdded86698467d3db937e7a4","dark":"https://mintcdn.com/sendpaper/ocvZXr2TobeYH0v1/logo/dark.svg?fit=max\u0026auto=format\u0026n=ocvZXr2TobeYH0v1\u0026q=85\u0026s=a5aff50c4f32526efc45a4dc24037120","href":"https://sendmypaper.com"},"favicon":"https://mintcdn.com/sendpaper/WoX8ZmPCZ_v0SKEu/logo/favicon.svg?fit=max\u0026auto=format\u0026n=WoX8ZmPCZ_v0SKEu\u0026q=85\u0026s=0c24a556a95d78f73c2eb592202e970d","api":{"playground":{"display":"interactive"}},"appearance":{"default":"light"},"background":{"color":{"light":"#FFFFFF","dark":"#0B100E"}},"navbar":{"links":[{"href":"https://sendmypaper.com/#pricing","label":"Pricing"},{"href":"https://sendmypaper.com/send","label":"Send from the web"}],"primary":{"type":"button","label":"Connect your agent","href":"/quickstart"}},"footer":{"socials":{"github":"https://github.com/ryan-tish/sendpaper-plugin","website":"https://sendmypaper.com"},"links":[{"header":"Product","items":[{"label":"Home","href":"https://sendmypaper.com"},{"label":"Send mail","href":"https://sendmypaper.com/send"},{"label":"Pricing","href":"https://sendmypaper.com/"}]},{"header":"For agents","items":[{"label":"MCP endpoint","href":"/agents/other-clients"},{"label":"OpenAPI spec","href":"https://sendmypaper.com/openapi.json"},{"label":"llms.txt","href":"https://sendmypaper.com/llms.txt"}]},{"header":"Legal","items":[{"label":"Terms","href":"https://sendmypaper.com/terms"},{"label":"Privacy","href":"https://sendmypaper.com/privacy"},{"label":"Content policy","href":"https://sendmypaper.com/content-policy"}]}]},"seo":{"metatags":{"og:site_name":"Sendpaper"}},"fonts":{"heading":{"family":"Geist","weight":600},"body":{"family":"Geist","weight":400}},"icons":{"library":"lucide"},"styling":{"eyebrows":"breadcrumbs","codeblocks":"system","latex":true},"banner":{"content":"New: your agent can now pay for you. [See how agent payments work →](/guides/agent-payments)","dismissible":true,"color":{"light":"#0D1512","dark":"#12291F"}},"contextual":{"options":["copy","view","chatgpt","claude","cursor","vscode","mcp"],"display":"header"},"thumbnails":{"appearance":"light","fonts":{"family":"Geist"}},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"sendpaper","hasAudioNarration":false,"actualSubdomain":"sendpaper","customDomains":["docs.sendmypaper.com"],"gitSource":{"type":"github","owner":"ryan-tish","repo":"sendpaper","deployBranch":"main","contentDirectory":"docs","isPrivate":false,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6af73c6e3522466a5b820653","clientVersion":"0.0.4143","searchFilterCounts":[{"language":"default","tag":"Guides","count":18},{"language":"default","tag":"API reference","count":8},{"language":"default","tag":"How-to guides","count":7},{"language":"default","tag":"Endpoints","count":7},{"language":"default","tag":"Reference","count":5},{"language":"default","tag":"Connect your agent","count":4},{"language":"default","tag":"Get started","count":2},{"language":"default","tag":"Overview","count":1}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[],"page":{"pagePath":"api-reference/create-a-letter","slug":"/api-reference/create-a-letter","pageMetadata":{"title":"Create a letter","description":"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in `awaiting_payment` and returns a `checkout_url`. Set `certified` to send it by USPS Certified Mail.\n\nTo send the same letter to several people, pass `recipients` (2–25 addresses) instead of `to`. You get back a Batch: one order per recipient and a single `batch.checkout_url`. `POST /orders/{id}/pay` with any order in the batch pays for every unpaid order in it (scope the token to `batch.price`).","deprecated":null,"version":null,"openapi":"/openapi.json post /letters","href":"/api-reference/create-a-letter","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in \", _jsx(_components.code, {\n children: \"awaiting_payment\"\n }), \" and returns a \", _jsx(_components.code, {\n children: \"checkout_url\"\n }), \". Set \", _jsx(_components.code, {\n children: \"certified\"\n }), \" to send it by USPS Certified Mail.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"To send the same letter to several people, pass \", _jsx(_components.code, {\n children: \"recipients\"\n }), \" (2–25 addresses) instead of \", _jsx(_components.code, {\n children: \"to\"\n }), \". You get back a Batch: one order per recipient and a single \", _jsx(_components.code, {\n children: \"batch.checkout_url\"\n }), \". \", _jsx(_components.code, {\n children: \"POST /orders/{id}/pay\"\n }), \" with any order in the batch pays for every unpaid order in it (scope the token to \", _jsx(_components.code, {\n children: \"batch.price\"\n }), \").\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"codeStyling":"system","config":{},"pageMetadata":{"title":"Create a letter","description":"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in `awaiting_payment` and returns a `checkout_url`. Set `certified` to send it by USPS Certified Mail.\n\nTo send the same letter to several people, pass `recipients` (2–25 addresses) instead of `to`. You get back a Batch: one order per recipient and a single `batch.checkout_url`. `POST /orders/{id}/pay` with any order in the batch pays for every unpaid order in it (scope the token to `batch.price`).","deprecated":null,"version":null,"openapi":"/openapi.json post /letters","href":"/api-reference/create-a-letter","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"summary":"Create a letter","description":"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in `awaiting_payment` and returns a `checkout_url`. Set `certified` to send it by USPS Certified Mail.\n\nTo send the same letter to several people, pass `recipients` (2–25 addresses) instead of `to`. You get back a Batch: one order per recipient and a single `batch.checkout_url`. `POST /orders/{id}/pay` with any order in the batch pays for every unpaid order in it (scope the token to `batch.price`).","operationId":"createLetter","parameters":["900ee24d-4bd6-4bae-879b-82f629f2f843"],"requestBody":"896e8fb9-ca60-4ce1-934e-73039f4ef4eb","responses":{"200":"2e4f1549-1fc3-446f-a75f-9bec7edbd335","201":"7e8f5254-c692-42a8-b61d-e2d6f758a44b","422":"f6f0f851-a674-4819-869f-055ddabc950c"},"method":"post","type":"path","servers":["af1b148e-d8db-4688-89f3-24054875814d"],"security":[],"path":"/letters","baseUrlOptions":["https://sendmypaper.com/v1"],"title":"Create a letter","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"900ee24d-4bd6-4bae-879b-82f629f2f843":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. Retrying with the same key returns the original order instead of creating a duplicate.","schema":{"type":"string","maxLength":120,"isRequired":false,"description":"Any unique string. Retrying with the same key returns the original order instead of creating a duplicate.","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["from","content","to"],"properties":{"to":{"type":"object","required":["name","line1","city","state","zip"],"properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.0.to.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.0.to.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"isRequired":true,"uniqueKey":"oneOf.0.to.city","typeLabel":"string"},"state":{"type":"string","description":"Two-letter US state or territory code","example":"CA","isRequired":true,"uniqueKey":"oneOf.0.to.state","typeLabel":"string"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","example":"94105","isRequired":true,"uniqueKey":"oneOf.0.to.zip","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.0.to.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.0.to.line2","typeLabel":"string"}},"description":"Recipient address Use `recipients` instead to send to several people.","isRequired":true,"uniqueKey":"oneOf.0.to","typeLabel":"object"},"from":{"type":"object","required":["name","line1","city"],"description":"Return address. It may be outside the US: set `country`. For a US address (no `country`, or `US`), `state` and `zip` are required and follow the US rules; elsewhere `state` is the region and `zip` the postcode, both optional.","properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.0.from.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.0.from.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"description":"City or town","isRequired":true,"uniqueKey":"oneOf.0.from.city","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.0.from.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.0.from.line2","typeLabel":"string"},"state":{"type":"string","maxLength":40,"description":"US: two-letter state or territory code (required). Elsewhere: region, county or province, if any","example":"CA","uniqueKey":"oneOf.0.from.state","typeLabel":"string"},"zip":{"type":"string","maxLength":12,"description":"US: 5-digit ZIP or ZIP+4 (required). Elsewhere: postcode","example":"94105","uniqueKey":"oneOf.0.from.zip","typeLabel":"string"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","default":"US","description":"Two-letter ISO 3166-1 country code of the return address, e.g. GB. Defaults to US. US territories use US with their state code.","example":"GB","uniqueKey":"oneOf.0.from.country","typeLabel":"string"}},"isRequired":true,"uniqueKey":"oneOf.0.from","typeLabel":"object"},"content":{"type":"object","required":[],"properties":{"body":{"type":"string","maxLength":9000,"description":"Plain text; blank lines separate paragraphs","uniqueKey":"oneOf.0.content.body","typeLabel":"string"},"font":{"type":"string","enum":["serif","sans"],"default":"serif","uniqueKey":"oneOf.0.content.font","typeLabel":"enum\u003cstring>"},"image_url":{"type":"string","format":"uri","description":"Optional https URL of a JPG or PNG printed under the date. A letter with a photo prints in color and costs $1.00 more.","uniqueKey":"oneOf.0.content.image_url","typeLabel":"string\u003curi>"},"pdf_url":{"type":"string","format":"uri","description":"Mail your own PDF (public https link, up to 6 pages) instead of body. Pages are fitted to 8.5x11; an address page is added in front.","uniqueKey":"oneOf.0.content.pdf_url","typeLabel":"string\u003curi>"},"color":{"type":"boolean","description":"PDF letters: print in color (+$1.00).","uniqueKey":"oneOf.0.content.color","typeLabel":"boolean"}},"isRequired":true,"uniqueKey":"oneOf.0.content","typeLabel":"object"},"customer_email":{"type":"string","format":"email","uniqueKey":"oneOf.0.customer_email","typeLabel":"string\u003cemail>"},"idempotency_key":{"type":"string","description":" With `recipients`, a retry with the same key returns the same batch.","uniqueKey":"oneOf.0.idempotency_key","typeLabel":"string"},"certified":{"type":"string","enum":["none","certified","certified_return_receipt"],"default":"none","description":"USPS Certified Mail. `certified` ($14.99): tracking number and proof of mailing and delivery. `certified_return_receipt` ($19.99): adds the recipient's signature. `none` ($4.99): regular First-Class.","uniqueKey":"oneOf.0.certified","typeLabel":"enum\u003cstring>"},"express":{"type":"boolean","default":false,"description":"USPS Priority Mail (2-3 days, tracked); not with certified.","uniqueKey":"oneOf.0.express","typeLabel":"boolean"},"recipients":{"type":"array","minItems":2,"maxItems":25,"items":{"type":"object","required":["name","line1","city","state","zip"],"properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.0.recipients.items.[INDEX].name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.0.recipients.items.[INDEX].line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"isRequired":true,"uniqueKey":"oneOf.0.recipients.items.[INDEX].city","typeLabel":"string"},"state":{"type":"string","description":"Two-letter US state or territory code","example":"CA","isRequired":true,"uniqueKey":"oneOf.0.recipients.items.[INDEX].state","typeLabel":"string"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","example":"94105","isRequired":true,"uniqueKey":"oneOf.0.recipients.items.[INDEX].zip","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.0.recipients.items.[INDEX].company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.0.recipients.items.[INDEX].line2","typeLabel":"string"}},"description":"A US address (recipients are always in the US, including territories and APO/FPO/DPO).","uniqueKey":"oneOf.0.recipients.items.[INDEX]","typeLabel":"object"},"description":"Send the same postcard or letter to several people: 2–25 addresses, used instead of `to`. Each recipient becomes its own order (own review, tracking and refund), grouped into a batch that is paid with one checkout link. The response is a Batch, not an Order.","uniqueKey":"oneOf.0.recipients","typeLabel":"object[]"}},"uniqueKey":"oneOf.0","typeLabel":"object"},{"type":"object","required":["from","content","recipients"],"properties":{"from":{"type":"object","required":["name","line1","city"],"description":"Return address. It may be outside the US: set `country`. For a US address (no `country`, or `US`), `state` and `zip` are required and follow the US rules; elsewhere `state` is the region and `zip` the postcode, both optional.","properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.1.from.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.1.from.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"description":"City or town","isRequired":true,"uniqueKey":"oneOf.1.from.city","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.1.from.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.1.from.line2","typeLabel":"string"},"state":{"type":"string","maxLength":40,"description":"US: two-letter state or territory code (required). Elsewhere: region, county or province, if any","example":"CA","uniqueKey":"oneOf.1.from.state","typeLabel":"string"},"zip":{"type":"string","maxLength":12,"description":"US: 5-digit ZIP or ZIP+4 (required). Elsewhere: postcode","example":"94105","uniqueKey":"oneOf.1.from.zip","typeLabel":"string"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","default":"US","description":"Two-letter ISO 3166-1 country code of the return address, e.g. GB. Defaults to US. US territories use US with their state code.","example":"GB","uniqueKey":"oneOf.1.from.country","typeLabel":"string"}},"isRequired":true,"uniqueKey":"oneOf.1.from","typeLabel":"object"},"content":{"type":"object","required":[],"properties":{"body":{"type":"string","maxLength":9000,"description":"Plain text; blank lines separate paragraphs","uniqueKey":"oneOf.1.content.body","typeLabel":"string"},"font":{"type":"string","enum":["serif","sans"],"default":"serif","uniqueKey":"oneOf.1.content.font","typeLabel":"enum\u003cstring>"},"image_url":{"type":"string","format":"uri","description":"Optional https URL of a JPG or PNG printed under the date. A letter with a photo prints in color and costs $1.00 more.","uniqueKey":"oneOf.1.content.image_url","typeLabel":"string\u003curi>"},"pdf_url":{"type":"string","format":"uri","description":"Mail your own PDF (public https link, up to 6 pages) instead of body. Pages are fitted to 8.5x11; an address page is added in front.","uniqueKey":"oneOf.1.content.pdf_url","typeLabel":"string\u003curi>"},"color":{"type":"boolean","description":"PDF letters: print in color (+$1.00).","uniqueKey":"oneOf.1.content.color","typeLabel":"boolean"}},"isRequired":true,"uniqueKey":"oneOf.1.content","typeLabel":"object"},"recipients":{"type":"array","minItems":2,"maxItems":25,"items":{"type":"object","required":["name","line1","city","state","zip"],"properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.1.recipients.items.[INDEX].name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.1.recipients.items.[INDEX].line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"isRequired":true,"uniqueKey":"oneOf.1.recipients.items.[INDEX].city","typeLabel":"string"},"state":{"type":"string","description":"Two-letter US state or territory code","example":"CA","isRequired":true,"uniqueKey":"oneOf.1.recipients.items.[INDEX].state","typeLabel":"string"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","example":"94105","isRequired":true,"uniqueKey":"oneOf.1.recipients.items.[INDEX].zip","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.1.recipients.items.[INDEX].company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.1.recipients.items.[INDEX].line2","typeLabel":"string"}},"description":"A US address (recipients are always in the US, including territories and APO/FPO/DPO).","uniqueKey":"oneOf.1.recipients.items.[INDEX]","typeLabel":"object"},"description":"Send the same postcard or letter to several people: 2–25 addresses, used instead of `to`. Each recipient becomes its own order (own review, tracking and refund), grouped into a batch that is paid with one checkout link. The response is a Batch, not an Order.","isRequired":true,"uniqueKey":"oneOf.1.recipients","typeLabel":"object[]"},"to":{"type":"object","required":["name","line1","city","state","zip"],"properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.1.to.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.1.to.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"isRequired":true,"uniqueKey":"oneOf.1.to.city","typeLabel":"string"},"state":{"type":"string","description":"Two-letter US state or territory code","example":"CA","isRequired":true,"uniqueKey":"oneOf.1.to.state","typeLabel":"string"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","example":"94105","isRequired":true,"uniqueKey":"oneOf.1.to.zip","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.1.to.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.1.to.line2","typeLabel":"string"}},"description":"Recipient address Use `recipients` instead to send to several people.","uniqueKey":"oneOf.1.to","typeLabel":"object"},"customer_email":{"type":"string","format":"email","uniqueKey":"oneOf.1.customer_email","typeLabel":"string\u003cemail>"},"idempotency_key":{"type":"string","description":" With `recipients`, a retry with the same key returns the same batch.","uniqueKey":"oneOf.1.idempotency_key","typeLabel":"string"},"certified":{"type":"string","enum":["none","certified","certified_return_receipt"],"default":"none","description":"USPS Certified Mail. `certified` ($14.99): tracking number and proof of mailing and delivery. `certified_return_receipt` ($19.99): adds the recipient's signature. `none` ($4.99): regular First-Class.","uniqueKey":"oneOf.1.certified","typeLabel":"enum\u003cstring>"},"express":{"type":"boolean","default":false,"description":"USPS Priority Mail (2-3 days, tracked); not with certified.","uniqueKey":"oneOf.1.express","typeLabel":"boolean"}},"uniqueKey":"oneOf.1","typeLabel":"object"}],"uniqueKey":"","typeLabel":"object"},"examples":{"one":{"title":"one","summary":"One recipient","value":{"to":{"name":"Pat Lee","line1":"500 Main St","line2":"Apt 4","city":"Boston","state":"MA","zip":"02110"},"from":{"name":"Alex Kim","line1":"88 Pine Ave","city":"Denver","state":"CO","zip":"80202"},"content":{"body":"Dear Pat,\n\nThank you for fixing the roof so quickly.\n\nBest,\nAlex","font":"serif"}}},"many":{"title":"many","summary":"Same letter to several people","value":{"from":{"name":"Alex Kim","line1":"88 Pine Ave","city":"Denver","state":"CO","zip":"80202"},"content":{"body":"Dear Pat,\n\nThank you for fixing the roof so quickly.\n\nBest,\nAlex","font":"serif"},"recipients":[{"name":"Sam Rivera","line1":"12 Oak St","city":"Austin","state":"TX","zip":"78701"},{"name":"Jo Park","line1":"12 Oak St","city":"Dayton","state":"OH","zip":"45402"}]}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"2e4f1549-1fc3-446f-a75f-9bec7edbd335":{"description":"Idempotency-Key already used: the original order is returned (a Batch when the request used `recipients`)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","example":"ord_8k2m4qz7c1x9b3vd","uniqueKey":"oneOf.0.id","typeLabel":"string"},"object":{"type":"string","enum":["postcard","letter"],"uniqueKey":"oneOf.0.object","typeLabel":"enum\u003cstring>"},"product":{"type":"string","enum":["postcard_4x6","postcard_6x9","postcard_6x11","letter","letter_certified","letter_certified_rr"],"uniqueKey":"oneOf.0.product","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["awaiting_payment","paid","printing","mailed","cancelled","refunded"],"uniqueKey":"oneOf.0.status","typeLabel":"enum\u003cstring>"},"status_detail":{"type":"string","uniqueKey":"oneOf.0.status_detail","typeLabel":"string"},"price":{"type":"object","properties":{"amount_cents":{"type":"integer","uniqueKey":"oneOf.0.price.amount_cents","typeLabel":"integer"},"currency":{"type":"string","uniqueKey":"oneOf.0.price.currency","typeLabel":"string"},"display":{"type":"string","uniqueKey":"oneOf.0.price.display","typeLabel":"string"}},"uniqueKey":"oneOf.0.price","typeLabel":"object"},"to":{"type":"object","required":["name","line1","city","state","zip"],"properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.0.to.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.0.to.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"isRequired":true,"uniqueKey":"oneOf.0.to.city","typeLabel":"string"},"state":{"type":"string","description":"Two-letter US state or territory code","example":"CA","isRequired":true,"uniqueKey":"oneOf.0.to.state","typeLabel":"string"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","example":"94105","isRequired":true,"uniqueKey":"oneOf.0.to.zip","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.0.to.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.0.to.line2","typeLabel":"string"}},"description":"A US address (recipients are always in the US, including territories and APO/FPO/DPO).","uniqueKey":"oneOf.0.to","typeLabel":"object"},"from":{"type":"object","required":["name","line1","city"],"description":"Return address. It may be outside the US: set `country`. For a US address (no `country`, or `US`), `state` and `zip` are required and follow the US rules; elsewhere `state` is the region and `zip` the postcode, both optional.","properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.0.from.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.0.from.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"description":"City or town","isRequired":true,"uniqueKey":"oneOf.0.from.city","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.0.from.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.0.from.line2","typeLabel":"string"},"state":{"type":"string","maxLength":40,"description":"US: two-letter state or territory code (required). Elsewhere: region, county or province, if any","example":"CA","uniqueKey":"oneOf.0.from.state","typeLabel":"string"},"zip":{"type":"string","maxLength":12,"description":"US: 5-digit ZIP or ZIP+4 (required). Elsewhere: postcode","example":"94105","uniqueKey":"oneOf.0.from.zip","typeLabel":"string"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","default":"US","description":"Two-letter ISO 3166-1 country code of the return address, e.g. GB. Defaults to US. US territories use US with their state code.","example":"GB","uniqueKey":"oneOf.0.from.country","typeLabel":"string"}},"uniqueKey":"oneOf.0.from","typeLabel":"object"},"content":{"type":"object","uniqueKey":"oneOf.0.content","typeLabel":"object"},"checkout_url":{"oneOf":[{"type":"string","description":"Where the person pays. Null once paid or closed. Never expires.","uniqueKey":"oneOf.0.checkout_url.oneOf.0","typeLabel":"string"},{"type":"null","description":"Where the person pays. Null once paid or closed. Never expires.","uniqueKey":"oneOf.0.checkout_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.checkout_url","typeLabel":"string | null"},"order_url":{"type":"string","description":"Human-readable status page","uniqueKey":"oneOf.0.order_url","typeLabel":"string"},"preview_url":{"type":"string","description":"Exact print preview","uniqueKey":"oneOf.0.preview_url","typeLabel":"string"},"created_at":{"type":"string","format":"date-time","uniqueKey":"oneOf.0.created_at","typeLabel":"string\u003cdate-time>"},"paid_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"oneOf.0.paid_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"oneOf.0.paid_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.paid_at","typeLabel":"string\u003cdate-time> | null"},"mailed_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"oneOf.0.mailed_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"oneOf.0.mailed_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.mailed_at","typeLabel":"string\u003cdate-time> | null"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","uniqueKey":"oneOf.0.events.items.[INDEX].at","typeLabel":"string"},"status":{"type":"string","uniqueKey":"oneOf.0.events.items.[INDEX].status","typeLabel":"string"},"note":{"type":"string","uniqueKey":"oneOf.0.events.items.[INDEX].note","typeLabel":"string"}},"uniqueKey":"oneOf.0.events.items.[INDEX]","typeLabel":"object"},"uniqueKey":"oneOf.0.events","typeLabel":"object[]"},"certified":{"type":"string","enum":["none","certified","certified_return_receipt"],"description":"Letters only: the USPS extra service.","uniqueKey":"oneOf.0.certified","typeLabel":"enum\u003cstring>"},"tracking":{"oneOf":[{"type":"object","description":"USPS tracking once the piece is accepted (certified letters always get one).","properties":{"number":{"type":"string","uniqueKey":"oneOf.0.tracking.oneOf.0.number","typeLabel":"string"},"url":{"type":"string","format":"uri","uniqueKey":"oneOf.0.tracking.oneOf.0.url","typeLabel":"string\u003curi>"}},"uniqueKey":"oneOf.0.tracking.oneOf.0","typeLabel":"object"},{"type":"null","description":"USPS tracking once the piece is accepted (certified letters always get one).","properties":{"number":{"type":"string"},"url":{"type":"string","format":"uri"}},"uniqueKey":"oneOf.0.tracking.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.tracking","typeLabel":"object | null"},"batch_id":{"oneOf":[{"type":"string","description":"Set when the order is part of a batch (created with `recipients`). Its checkout_url is then the batch's single payment link.","uniqueKey":"oneOf.0.batch_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"Set when the order is part of a batch (created with `recipients`). Its checkout_url is then the batch's single payment link.","uniqueKey":"oneOf.0.batch_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.batch_id","typeLabel":"string | null"}},"uniqueKey":"oneOf.0","typeLabel":"object"},{"type":"object","required":["batch","orders"],"properties":{"batch":{"type":"object","required":["id","count","url","price"],"properties":{"id":{"type":"string","description":"Batch id, batch_…","isRequired":true,"uniqueKey":"oneOf.1.batch.id","typeLabel":"string"},"count":{"type":"integer","description":"Number of recipients (one order each)","isRequired":true,"uniqueKey":"oneOf.1.batch.count","typeLabel":"integer"},"url":{"type":"string","format":"uri","description":"Batch page listing every recipient with links to each preview","isRequired":true,"uniqueKey":"oneOf.1.batch.url","typeLabel":"string\u003curi>"},"price":{"type":"object","properties":{"amount_cents":{"type":"integer","uniqueKey":"oneOf.1.batch.price.amount_cents","typeLabel":"integer"},"currency":{"type":"string","uniqueKey":"oneOf.1.batch.price.currency","typeLabel":"string"},"display":{"type":"string","uniqueKey":"oneOf.1.batch.price.display","typeLabel":"string"}},"description":"Total for the whole batch","isRequired":true,"uniqueKey":"oneOf.1.batch.price","typeLabel":"object"},"checkout_url":{"oneOf":[{"type":"string","format":"uri","description":"One payment link for every unpaid order in the batch; null once all are paid","uniqueKey":"oneOf.1.batch.checkout_url.oneOf.0","typeLabel":"string\u003curi>"},{"type":"null","format":"uri","description":"One payment link for every unpaid order in the batch; null once all are paid","uniqueKey":"oneOf.1.batch.checkout_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.batch.checkout_url","typeLabel":"string\u003curi> | null"},"discount":{"oneOf":[{"type":"object","properties":{"amount_cents":{"type":"integer","uniqueKey":"oneOf.1.batch.discount.oneOf.0.amount_cents","typeLabel":"integer"},"display":{"type":"string","uniqueKey":"oneOf.1.batch.discount.oneOf.0.display","typeLabel":"string"},"reason":{"type":"string","uniqueKey":"oneOf.1.batch.discount.oneOf.0.reason","typeLabel":"string"}},"description":"First-order discount across the batch, already taken off price","uniqueKey":"oneOf.1.batch.discount.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"amount_cents":{"type":"integer"},"display":{"type":"string"},"reason":{"type":"string"}},"description":"First-order discount across the batch, already taken off price","uniqueKey":"oneOf.1.batch.discount.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.batch.discount","typeLabel":"object | null"}},"isRequired":true,"uniqueKey":"oneOf.1.batch","typeLabel":"object"},"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ord_8k2m4qz7c1x9b3vd","uniqueKey":"oneOf.1.orders.items.[INDEX].id","typeLabel":"string"},"object":{"type":"string","enum":["postcard","letter"],"uniqueKey":"oneOf.1.orders.items.[INDEX].object","typeLabel":"enum\u003cstring>"},"product":{"type":"string","enum":["postcard_4x6","postcard_6x9","postcard_6x11","letter","letter_certified","letter_certified_rr"],"uniqueKey":"oneOf.1.orders.items.[INDEX].product","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["awaiting_payment","paid","printing","mailed","cancelled","refunded"],"uniqueKey":"oneOf.1.orders.items.[INDEX].status","typeLabel":"enum\u003cstring>"},"status_detail":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].status_detail","typeLabel":"string"},"price":{"type":"object","properties":{"amount_cents":{"type":"integer","uniqueKey":"oneOf.1.orders.items.[INDEX].price.amount_cents","typeLabel":"integer"},"currency":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].price.currency","typeLabel":"string"},"display":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].price.display","typeLabel":"string"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].price","typeLabel":"object"},"to":{"type":"object","required":["name","line1","city","state","zip"],"properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.city","typeLabel":"string"},"state":{"type":"string","description":"Two-letter US state or territory code","example":"CA","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.state","typeLabel":"string"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","example":"94105","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.zip","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.1.orders.items.[INDEX].to.line2","typeLabel":"string"}},"description":"A US address (recipients are always in the US, including territories and APO/FPO/DPO).","uniqueKey":"oneOf.1.orders.items.[INDEX].to","typeLabel":"object"},"from":{"type":"object","required":["name","line1","city"],"description":"Return address. It may be outside the US: set `country`. For a US address (no `country`, or `US`), `state` and `zip` are required and follow the US rules; elsewhere `state` is the region and `zip` the postcode, both optional.","properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].from.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].from.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"description":"City or town","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].from.city","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.1.orders.items.[INDEX].from.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.1.orders.items.[INDEX].from.line2","typeLabel":"string"},"state":{"type":"string","maxLength":40,"description":"US: two-letter state or territory code (required). Elsewhere: region, county or province, if any","example":"CA","uniqueKey":"oneOf.1.orders.items.[INDEX].from.state","typeLabel":"string"},"zip":{"type":"string","maxLength":12,"description":"US: 5-digit ZIP or ZIP+4 (required). Elsewhere: postcode","example":"94105","uniqueKey":"oneOf.1.orders.items.[INDEX].from.zip","typeLabel":"string"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","default":"US","description":"Two-letter ISO 3166-1 country code of the return address, e.g. GB. Defaults to US. US territories use US with their state code.","example":"GB","uniqueKey":"oneOf.1.orders.items.[INDEX].from.country","typeLabel":"string"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].from","typeLabel":"object"},"content":{"type":"object","uniqueKey":"oneOf.1.orders.items.[INDEX].content","typeLabel":"object"},"checkout_url":{"oneOf":[{"type":"string","description":"Where the person pays. Null once paid or closed. Never expires.","uniqueKey":"oneOf.1.orders.items.[INDEX].checkout_url.oneOf.0","typeLabel":"string"},{"type":"null","description":"Where the person pays. Null once paid or closed. Never expires.","uniqueKey":"oneOf.1.orders.items.[INDEX].checkout_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].checkout_url","typeLabel":"string | null"},"order_url":{"type":"string","description":"Human-readable status page","uniqueKey":"oneOf.1.orders.items.[INDEX].order_url","typeLabel":"string"},"preview_url":{"type":"string","description":"Exact print preview","uniqueKey":"oneOf.1.orders.items.[INDEX].preview_url","typeLabel":"string"},"created_at":{"type":"string","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].created_at","typeLabel":"string\u003cdate-time>"},"paid_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].paid_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].paid_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].paid_at","typeLabel":"string\u003cdate-time> | null"},"mailed_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].mailed_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].mailed_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].mailed_at","typeLabel":"string\u003cdate-time> | null"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].events.items.[INDEX].at","typeLabel":"string"},"status":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].events.items.[INDEX].status","typeLabel":"string"},"note":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].events.items.[INDEX].note","typeLabel":"string"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].events.items.[INDEX]","typeLabel":"object"},"uniqueKey":"oneOf.1.orders.items.[INDEX].events","typeLabel":"object[]"},"certified":{"type":"string","enum":["none","certified","certified_return_receipt"],"description":"Letters only: the USPS extra service.","uniqueKey":"oneOf.1.orders.items.[INDEX].certified","typeLabel":"enum\u003cstring>"},"tracking":{"oneOf":[{"type":"object","description":"USPS tracking once the piece is accepted (certified letters always get one).","properties":{"number":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].tracking.oneOf.0.number","typeLabel":"string"},"url":{"type":"string","format":"uri","uniqueKey":"oneOf.1.orders.items.[INDEX].tracking.oneOf.0.url","typeLabel":"string\u003curi>"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].tracking.oneOf.0","typeLabel":"object"},{"type":"null","description":"USPS tracking once the piece is accepted (certified letters always get one).","properties":{"number":{"type":"string"},"url":{"type":"string","format":"uri"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].tracking.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].tracking","typeLabel":"object | null"},"batch_id":{"oneOf":[{"type":"string","description":"Set when the order is part of a batch (created with `recipients`). Its checkout_url is then the batch's single payment link.","uniqueKey":"oneOf.1.orders.items.[INDEX].batch_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"Set when the order is part of a batch (created with `recipients`). Its checkout_url is then the batch's single payment link.","uniqueKey":"oneOf.1.orders.items.[INDEX].batch_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].batch_id","typeLabel":"string | null"}},"uniqueKey":"oneOf.1.orders.items.[INDEX]","typeLabel":"object"},"description":"One order per recipient, in the order given","isRequired":true,"uniqueKey":"oneOf.1.orders","typeLabel":"object[]"}},"uniqueKey":"oneOf.1","typeLabel":"object"}],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":"ord_8k2m4qz7c1x9b3vd","object":"postcard","product":"postcard_4x6","status":"awaiting_payment","status_detail":"\u003cstring>","price":{"amount_cents":123,"currency":"\u003cstring>","display":"\u003cstring>"},"to":{"name":"\u003cstring>","line1":"\u003cstring>","city":"\u003cstring>","state":"CA","zip":"94105","company":"\u003cstring>","line2":"\u003cstring>"},"from":{"name":"\u003cstring>","line1":"\u003cstring>","city":"\u003cstring>","company":"\u003cstring>","line2":"\u003cstring>","state":"CA","zip":"94105","country":"GB"},"content":{},"checkout_url":"\u003cstring>","order_url":"\u003cstring>","preview_url":"\u003cstring>","created_at":"2023-11-07T05:31:56Z","paid_at":"2023-11-07T05:31:56Z","mailed_at":"2023-11-07T05:31:56Z","events":[{"at":"\u003cstring>","status":"\u003cstring>","note":"\u003cstring>"}],"certified":"none","tracking":{"number":"\u003cstring>","url":"\u003cstring>"},"batch_id":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"7e8f5254-c692-42a8-b61d-e2d6f758a44b":{"description":"Order created (a Batch when the request used `recipients`)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","example":"ord_8k2m4qz7c1x9b3vd","uniqueKey":"oneOf.0.id","typeLabel":"string"},"object":{"type":"string","enum":["postcard","letter"],"uniqueKey":"oneOf.0.object","typeLabel":"enum\u003cstring>"},"product":{"type":"string","enum":["postcard_4x6","postcard_6x9","postcard_6x11","letter","letter_certified","letter_certified_rr"],"uniqueKey":"oneOf.0.product","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["awaiting_payment","paid","printing","mailed","cancelled","refunded"],"uniqueKey":"oneOf.0.status","typeLabel":"enum\u003cstring>"},"status_detail":{"type":"string","uniqueKey":"oneOf.0.status_detail","typeLabel":"string"},"price":{"type":"object","properties":{"amount_cents":{"type":"integer","uniqueKey":"oneOf.0.price.amount_cents","typeLabel":"integer"},"currency":{"type":"string","uniqueKey":"oneOf.0.price.currency","typeLabel":"string"},"display":{"type":"string","uniqueKey":"oneOf.0.price.display","typeLabel":"string"}},"uniqueKey":"oneOf.0.price","typeLabel":"object"},"to":{"type":"object","required":["name","line1","city","state","zip"],"properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.0.to.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.0.to.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"isRequired":true,"uniqueKey":"oneOf.0.to.city","typeLabel":"string"},"state":{"type":"string","description":"Two-letter US state or territory code","example":"CA","isRequired":true,"uniqueKey":"oneOf.0.to.state","typeLabel":"string"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","example":"94105","isRequired":true,"uniqueKey":"oneOf.0.to.zip","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.0.to.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.0.to.line2","typeLabel":"string"}},"description":"A US address (recipients are always in the US, including territories and APO/FPO/DPO).","uniqueKey":"oneOf.0.to","typeLabel":"object"},"from":{"type":"object","required":["name","line1","city"],"description":"Return address. It may be outside the US: set `country`. For a US address (no `country`, or `US`), `state` and `zip` are required and follow the US rules; elsewhere `state` is the region and `zip` the postcode, both optional.","properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.0.from.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.0.from.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"description":"City or town","isRequired":true,"uniqueKey":"oneOf.0.from.city","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.0.from.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.0.from.line2","typeLabel":"string"},"state":{"type":"string","maxLength":40,"description":"US: two-letter state or territory code (required). Elsewhere: region, county or province, if any","example":"CA","uniqueKey":"oneOf.0.from.state","typeLabel":"string"},"zip":{"type":"string","maxLength":12,"description":"US: 5-digit ZIP or ZIP+4 (required). Elsewhere: postcode","example":"94105","uniqueKey":"oneOf.0.from.zip","typeLabel":"string"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","default":"US","description":"Two-letter ISO 3166-1 country code of the return address, e.g. GB. Defaults to US. US territories use US with their state code.","example":"GB","uniqueKey":"oneOf.0.from.country","typeLabel":"string"}},"uniqueKey":"oneOf.0.from","typeLabel":"object"},"content":{"type":"object","uniqueKey":"oneOf.0.content","typeLabel":"object"},"checkout_url":{"oneOf":[{"type":"string","description":"Where the person pays. Null once paid or closed. Never expires.","uniqueKey":"oneOf.0.checkout_url.oneOf.0","typeLabel":"string"},{"type":"null","description":"Where the person pays. Null once paid or closed. Never expires.","uniqueKey":"oneOf.0.checkout_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.checkout_url","typeLabel":"string | null"},"order_url":{"type":"string","description":"Human-readable status page","uniqueKey":"oneOf.0.order_url","typeLabel":"string"},"preview_url":{"type":"string","description":"Exact print preview","uniqueKey":"oneOf.0.preview_url","typeLabel":"string"},"created_at":{"type":"string","format":"date-time","uniqueKey":"oneOf.0.created_at","typeLabel":"string\u003cdate-time>"},"paid_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"oneOf.0.paid_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"oneOf.0.paid_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.paid_at","typeLabel":"string\u003cdate-time> | null"},"mailed_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"oneOf.0.mailed_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"oneOf.0.mailed_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.mailed_at","typeLabel":"string\u003cdate-time> | null"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","uniqueKey":"oneOf.0.events.items.[INDEX].at","typeLabel":"string"},"status":{"type":"string","uniqueKey":"oneOf.0.events.items.[INDEX].status","typeLabel":"string"},"note":{"type":"string","uniqueKey":"oneOf.0.events.items.[INDEX].note","typeLabel":"string"}},"uniqueKey":"oneOf.0.events.items.[INDEX]","typeLabel":"object"},"uniqueKey":"oneOf.0.events","typeLabel":"object[]"},"certified":{"type":"string","enum":["none","certified","certified_return_receipt"],"description":"Letters only: the USPS extra service.","uniqueKey":"oneOf.0.certified","typeLabel":"enum\u003cstring>"},"tracking":{"oneOf":[{"type":"object","description":"USPS tracking once the piece is accepted (certified letters always get one).","properties":{"number":{"type":"string","uniqueKey":"oneOf.0.tracking.oneOf.0.number","typeLabel":"string"},"url":{"type":"string","format":"uri","uniqueKey":"oneOf.0.tracking.oneOf.0.url","typeLabel":"string\u003curi>"}},"uniqueKey":"oneOf.0.tracking.oneOf.0","typeLabel":"object"},{"type":"null","description":"USPS tracking once the piece is accepted (certified letters always get one).","properties":{"number":{"type":"string"},"url":{"type":"string","format":"uri"}},"uniqueKey":"oneOf.0.tracking.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.tracking","typeLabel":"object | null"},"batch_id":{"oneOf":[{"type":"string","description":"Set when the order is part of a batch (created with `recipients`). Its checkout_url is then the batch's single payment link.","uniqueKey":"oneOf.0.batch_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"Set when the order is part of a batch (created with `recipients`). Its checkout_url is then the batch's single payment link.","uniqueKey":"oneOf.0.batch_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.batch_id","typeLabel":"string | null"}},"uniqueKey":"oneOf.0","typeLabel":"object"},{"type":"object","required":["batch","orders"],"properties":{"batch":{"type":"object","required":["id","count","url","price"],"properties":{"id":{"type":"string","description":"Batch id, batch_…","isRequired":true,"uniqueKey":"oneOf.1.batch.id","typeLabel":"string"},"count":{"type":"integer","description":"Number of recipients (one order each)","isRequired":true,"uniqueKey":"oneOf.1.batch.count","typeLabel":"integer"},"url":{"type":"string","format":"uri","description":"Batch page listing every recipient with links to each preview","isRequired":true,"uniqueKey":"oneOf.1.batch.url","typeLabel":"string\u003curi>"},"price":{"type":"object","properties":{"amount_cents":{"type":"integer","uniqueKey":"oneOf.1.batch.price.amount_cents","typeLabel":"integer"},"currency":{"type":"string","uniqueKey":"oneOf.1.batch.price.currency","typeLabel":"string"},"display":{"type":"string","uniqueKey":"oneOf.1.batch.price.display","typeLabel":"string"}},"description":"Total for the whole batch","isRequired":true,"uniqueKey":"oneOf.1.batch.price","typeLabel":"object"},"checkout_url":{"oneOf":[{"type":"string","format":"uri","description":"One payment link for every unpaid order in the batch; null once all are paid","uniqueKey":"oneOf.1.batch.checkout_url.oneOf.0","typeLabel":"string\u003curi>"},{"type":"null","format":"uri","description":"One payment link for every unpaid order in the batch; null once all are paid","uniqueKey":"oneOf.1.batch.checkout_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.batch.checkout_url","typeLabel":"string\u003curi> | null"},"discount":{"oneOf":[{"type":"object","properties":{"amount_cents":{"type":"integer","uniqueKey":"oneOf.1.batch.discount.oneOf.0.amount_cents","typeLabel":"integer"},"display":{"type":"string","uniqueKey":"oneOf.1.batch.discount.oneOf.0.display","typeLabel":"string"},"reason":{"type":"string","uniqueKey":"oneOf.1.batch.discount.oneOf.0.reason","typeLabel":"string"}},"description":"First-order discount across the batch, already taken off price","uniqueKey":"oneOf.1.batch.discount.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"amount_cents":{"type":"integer"},"display":{"type":"string"},"reason":{"type":"string"}},"description":"First-order discount across the batch, already taken off price","uniqueKey":"oneOf.1.batch.discount.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.batch.discount","typeLabel":"object | null"}},"isRequired":true,"uniqueKey":"oneOf.1.batch","typeLabel":"object"},"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ord_8k2m4qz7c1x9b3vd","uniqueKey":"oneOf.1.orders.items.[INDEX].id","typeLabel":"string"},"object":{"type":"string","enum":["postcard","letter"],"uniqueKey":"oneOf.1.orders.items.[INDEX].object","typeLabel":"enum\u003cstring>"},"product":{"type":"string","enum":["postcard_4x6","postcard_6x9","postcard_6x11","letter","letter_certified","letter_certified_rr"],"uniqueKey":"oneOf.1.orders.items.[INDEX].product","typeLabel":"enum\u003cstring>"},"status":{"type":"string","enum":["awaiting_payment","paid","printing","mailed","cancelled","refunded"],"uniqueKey":"oneOf.1.orders.items.[INDEX].status","typeLabel":"enum\u003cstring>"},"status_detail":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].status_detail","typeLabel":"string"},"price":{"type":"object","properties":{"amount_cents":{"type":"integer","uniqueKey":"oneOf.1.orders.items.[INDEX].price.amount_cents","typeLabel":"integer"},"currency":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].price.currency","typeLabel":"string"},"display":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].price.display","typeLabel":"string"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].price","typeLabel":"object"},"to":{"type":"object","required":["name","line1","city","state","zip"],"properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.city","typeLabel":"string"},"state":{"type":"string","description":"Two-letter US state or territory code","example":"CA","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.state","typeLabel":"string"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","example":"94105","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.zip","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.1.orders.items.[INDEX].to.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.1.orders.items.[INDEX].to.line2","typeLabel":"string"}},"description":"A US address (recipients are always in the US, including territories and APO/FPO/DPO).","uniqueKey":"oneOf.1.orders.items.[INDEX].to","typeLabel":"object"},"from":{"type":"object","required":["name","line1","city"],"description":"Return address. It may be outside the US: set `country`. For a US address (no `country`, or `US`), `state` and `zip` are required and follow the US rules; elsewhere `state` is the region and `zip` the postcode, both optional.","properties":{"name":{"type":"string","maxLength":60,"isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].from.name","typeLabel":"string"},"line1":{"type":"string","maxLength":64,"description":"Street address","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].from.line1","typeLabel":"string"},"city":{"type":"string","maxLength":40,"description":"City or town","isRequired":true,"uniqueKey":"oneOf.1.orders.items.[INDEX].from.city","typeLabel":"string"},"company":{"type":"string","maxLength":60,"uniqueKey":"oneOf.1.orders.items.[INDEX].from.company","typeLabel":"string"},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, unit","uniqueKey":"oneOf.1.orders.items.[INDEX].from.line2","typeLabel":"string"},"state":{"type":"string","maxLength":40,"description":"US: two-letter state or territory code (required). Elsewhere: region, county or province, if any","example":"CA","uniqueKey":"oneOf.1.orders.items.[INDEX].from.state","typeLabel":"string"},"zip":{"type":"string","maxLength":12,"description":"US: 5-digit ZIP or ZIP+4 (required). Elsewhere: postcode","example":"94105","uniqueKey":"oneOf.1.orders.items.[INDEX].from.zip","typeLabel":"string"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","default":"US","description":"Two-letter ISO 3166-1 country code of the return address, e.g. GB. Defaults to US. US territories use US with their state code.","example":"GB","uniqueKey":"oneOf.1.orders.items.[INDEX].from.country","typeLabel":"string"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].from","typeLabel":"object"},"content":{"type":"object","uniqueKey":"oneOf.1.orders.items.[INDEX].content","typeLabel":"object"},"checkout_url":{"oneOf":[{"type":"string","description":"Where the person pays. Null once paid or closed. Never expires.","uniqueKey":"oneOf.1.orders.items.[INDEX].checkout_url.oneOf.0","typeLabel":"string"},{"type":"null","description":"Where the person pays. Null once paid or closed. Never expires.","uniqueKey":"oneOf.1.orders.items.[INDEX].checkout_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].checkout_url","typeLabel":"string | null"},"order_url":{"type":"string","description":"Human-readable status page","uniqueKey":"oneOf.1.orders.items.[INDEX].order_url","typeLabel":"string"},"preview_url":{"type":"string","description":"Exact print preview","uniqueKey":"oneOf.1.orders.items.[INDEX].preview_url","typeLabel":"string"},"created_at":{"type":"string","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].created_at","typeLabel":"string\u003cdate-time>"},"paid_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].paid_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].paid_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].paid_at","typeLabel":"string\u003cdate-time> | null"},"mailed_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].mailed_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"oneOf.1.orders.items.[INDEX].mailed_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].mailed_at","typeLabel":"string\u003cdate-time> | null"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].events.items.[INDEX].at","typeLabel":"string"},"status":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].events.items.[INDEX].status","typeLabel":"string"},"note":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].events.items.[INDEX].note","typeLabel":"string"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].events.items.[INDEX]","typeLabel":"object"},"uniqueKey":"oneOf.1.orders.items.[INDEX].events","typeLabel":"object[]"},"certified":{"type":"string","enum":["none","certified","certified_return_receipt"],"description":"Letters only: the USPS extra service.","uniqueKey":"oneOf.1.orders.items.[INDEX].certified","typeLabel":"enum\u003cstring>"},"tracking":{"oneOf":[{"type":"object","description":"USPS tracking once the piece is accepted (certified letters always get one).","properties":{"number":{"type":"string","uniqueKey":"oneOf.1.orders.items.[INDEX].tracking.oneOf.0.number","typeLabel":"string"},"url":{"type":"string","format":"uri","uniqueKey":"oneOf.1.orders.items.[INDEX].tracking.oneOf.0.url","typeLabel":"string\u003curi>"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].tracking.oneOf.0","typeLabel":"object"},{"type":"null","description":"USPS tracking once the piece is accepted (certified letters always get one).","properties":{"number":{"type":"string"},"url":{"type":"string","format":"uri"}},"uniqueKey":"oneOf.1.orders.items.[INDEX].tracking.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].tracking","typeLabel":"object | null"},"batch_id":{"oneOf":[{"type":"string","description":"Set when the order is part of a batch (created with `recipients`). Its checkout_url is then the batch's single payment link.","uniqueKey":"oneOf.1.orders.items.[INDEX].batch_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"Set when the order is part of a batch (created with `recipients`). Its checkout_url is then the batch's single payment link.","uniqueKey":"oneOf.1.orders.items.[INDEX].batch_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.orders.items.[INDEX].batch_id","typeLabel":"string | null"}},"uniqueKey":"oneOf.1.orders.items.[INDEX]","typeLabel":"object"},"description":"One order per recipient, in the order given","isRequired":true,"uniqueKey":"oneOf.1.orders","typeLabel":"object[]"}},"uniqueKey":"oneOf.1","typeLabel":"object"}],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":"ord_8k2m4qz7c1x9b3vd","object":"postcard","product":"postcard_4x6","status":"awaiting_payment","status_detail":"\u003cstring>","price":{"amount_cents":123,"currency":"\u003cstring>","display":"\u003cstring>"},"to":{"name":"\u003cstring>","line1":"\u003cstring>","city":"\u003cstring>","state":"CA","zip":"94105","company":"\u003cstring>","line2":"\u003cstring>"},"from":{"name":"\u003cstring>","line1":"\u003cstring>","city":"\u003cstring>","company":"\u003cstring>","line2":"\u003cstring>","state":"CA","zip":"94105","country":"GB"},"content":{},"checkout_url":"\u003cstring>","order_url":"\u003cstring>","preview_url":"\u003cstring>","created_at":"2023-11-07T05:31:56Z","paid_at":"2023-11-07T05:31:56Z","mailed_at":"2023-11-07T05:31:56Z","events":[{"at":"\u003cstring>","status":"\u003cstring>","note":"\u003cstring>"}],"certified":"none","tracking":{"number":"\u003cstring>","url":"\u003cstring>"},"batch_id":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"f6f0f851-a674-4819-869f-055ddabc950c":{"description":"Validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"invalid_request","uniqueKey":"error.type","typeLabel":"string"},"message":{"type":"string","uniqueKey":"error.message","typeLabel":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","uniqueKey":"error.fields.items.[INDEX].field","typeLabel":"string"},"message":{"type":"string","uniqueKey":"error.fields.items.[INDEX].message","typeLabel":"string"}},"uniqueKey":"error.fields.items.[INDEX]","typeLabel":"object"},"uniqueKey":"error.fields","typeLabel":"object[]"}},"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"type":"invalid_request","message":"\u003cstring>","fields":[{"field":"\u003cstring>","message":"\u003cstring>"}]}}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{},"servers":{"af1b148e-d8db-4688-89f3-24054875814d":{"url":"https://sendmypaper.com/v1"}}},"originalFileLocation":"openapi.json"},"subdomain":"sendpaper","siteName":"Sendpaper","title":"Create a letter - Sendpaper","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-13T16:36:01.750Z","originalFileLocation":"api-reference/create-a-letter.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"light\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in awaiting_payment and returns a checkout_url. Set certified to send it by USPS Certified Mail. To send the same letter to several people, pass recipients (2–25 addresses) instead of to. You get back a Batch: one order per recipient and a single batch.checkout_url. POST /orders/{id}/pay with any order in the batch pays for every unpaid order in it (scope the token to batch.price).\">\u003cmeta data-mint-head name=\"application-name\" content=\"Sendpaper\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create a letter - Sendpaper\">\u003cmeta data-mint-head property=\"og:description\" content=\"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in awaiting_payment and returns a checkout_url. Set certified to send it by USPS Certified Mail. To send the same letter to several people, pass recipients (2–25 addresses) instead of to. You get back a Batch: one order per recipient and a single batch.checkout_url. POST /orders/{id}/pay with any order in the batch pays for every unpaid order in it (scope the token to batch.price).\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Sendpaper\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.sendmypaper.com/api-reference/create-a-letter\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://sendpaper.mintlify.site/_mintlify/api/og/v2?division=Endpoints\u0026amp;title=Create+a+letter\u0026amp;description=Creates+a+printed+letter+%28up+to+%7E3+pages%2C+8.5%C3%9711%2C+%2310+envelope%29+in+%60awaiting_payment%60+and+returns+a+%60checkout_url%60.+Set+%60certified%60+to+send+it+by+USPS+Certified\u0026amp;theme=f8994d32c62ac5300cd43db0\u0026amp;signature=b2fb971ae2a3e2e0446ad5d778634610502c9f6dde0ceb2d6d48265a635580df\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create a letter - Sendpaper\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in awaiting_payment and returns a checkout_url. Set certified to send it by USPS Certified Mail. To send the same letter to several people, pass recipients (2–25 addresses) instead of to. You get back a Batch: one order per recipient and a single batch.checkout_url. POST /orders/{id}/pay with any order in the batch pays for every unpaid order in it (scope the token to batch.price).\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://sendpaper.mintlify.site/_mintlify/api/og/v2?division=Endpoints\u0026amp;title=Create+a+letter\u0026amp;description=Creates+a+printed+letter+%28up+to+%7E3+pages%2C+8.5%C3%9711%2C+%2310+envelope%29+in+%60awaiting_payment%60+and+returns+a+%60checkout_url%60.+Set+%60certified%60+to+send+it+by+USPS+Certified\u0026amp;theme=f8994d32c62ac5300cd43db0\u0026amp;signature=b2fb971ae2a3e2e0446ad5d778634610502c9f6dde0ceb2d6d48265a635580df\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/sendpaper/ESCtK68PwY-w-3IX/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Sendpaper\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0F7A52\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.sendmypaper.com/api-reference/create-a-letter\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/create-a-letter.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.sendmypaper.com/#organization\",\"name\":\"Sendpaper\",\"url\":\"https://docs.sendmypaper.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/sendpaper/ocvZXr2TobeYH0v1/logo/light.svg?fit=max\u0026auto=format\u0026n=ocvZXr2TobeYH0v1\u0026q=85\u0026s=b4054fbffdded86698467d3db937e7a4\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.sendmypaper.com#website\",\"name\":\"Sendpaper\",\"url\":\"https://docs.sendmypaper.com\",\"publisher\":{\"@id\":\"https://docs.sendmypaper.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.sendmypaper.com/api-reference/create-a-letter#webpage\",\"url\":\"https://docs.sendmypaper.com/api-reference/create-a-letter\",\"name\":\"Create a letter\",\"description\":\"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in awaiting_payment and returns a checkout_url. Set certified to send it by USPS Certified Mail. To send the same letter to several people, pass recipients (2–25 addresses) instead of to. You get back a Batch: one order per recipient and a single batch.checkout_url. POST /orders/{id}/pay with any order in the batch pays for every unpaid order in it (scope the token to batch.price).\",\"dateModified\":\"2026-11-13T16:36:01.750Z\",\"isPartOf\":{\"@id\":\"https://docs.sendmypaper.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.sendmypaper.com/api-reference/create-a-letter#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.sendmypaper.com/api-reference/create-a-letter#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.sendmypaper.com/api-reference/list-products\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create a letter\",\"item\":\"https://docs.sendmypaper.com/api-reference/create-a-letter\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.sendmypaper.com/api-reference/create-a-letter#apireference\",\"headline\":\"Create a letter\",\"name\":\"Create a letter\",\"description\":\"Creates a printed letter (up to ~3 pages, 8.5×11, #10 envelope) in awaiting_payment and returns a checkout_url. Set certified to send it by USPS Certified Mail. To send the same letter to several people, pass recipients (2–25 addresses) instead of to. You get back a Batch: one order per recipient and a single batch.checkout_url. POST /orders/{id}/pay with any order in the batch pays for every unpaid order in it (scope the token to batch.price).\",\"url\":\"https://docs.sendmypaper.com/api-reference/create-a-letter\",\"mainEntityOfPage\":{\"@id\":\"https://docs.sendmypaper.com/api-reference/create-a-letter#webpage\"},\"dateModified\":\"2026-11-13T16:36:01.750Z\",\"publisher\":{\"@id\":\"https://docs.sendmypaper.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.sendmypaper.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Sendpaper\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Sendpaper\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/create-a-letter.md","siteName":"Sendpaper","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Overview","pages":[{"title":"API introduction","href":"/api/introduction"}]},{"group":"Endpoints","pages":[{"title":"List products","deprecated":null,"version":null,"openapi":"/openapi.json get /products","href":"/api-reference/list-products"},{"title":"Create a postcard","description":"Creates a 4×6, 6×9 or 6×11 postcard order in `awaiting_payment` and returns a `checkout_url`. Send the person to it; the postcard is reviewed, printed and mailed after payment.\n\nTo send the same postcard to several people, pass `recipients` (2–25 addresses) instead of `to`. You get back a Batch: one order per recipient and a single `batch.checkout_url`. `POST /orders/{id}/pay` with any order in the batch pays for every unpaid order in it (scope the token to `batch.price`).","deprecated":null,"version":null,"openapi":"/openapi.json post /postcards","href":"/api-reference/create-a-postcard"},{"title":"Create a letter","deprecated":null,"version":null,"openapi":"/openapi.json post /letters","href":"/api-reference/create-a-letter"},{"title":"Pay with an agent token","description":"Pay an unpaid order with a Stripe shared payment token (`spt_…`) the user approved, scoped to at least the order amount in USD. Safe to retry with the same token.\n\nFor an order that belongs to a batch, this charges one token for every unpaid order in the batch; scope the token to the batch total.","deprecated":null,"version":null,"openapi":"/openapi.json post /orders/{id}/pay","href":"/api-reference/pay-with-an-agent-token"},{"title":"Retrieve an order","deprecated":null,"version":null,"openapi":"/openapi.json get /orders/{id}","href":"/api-reference/retrieve-an-order"},{"title":"Cancel an unpaid order","deprecated":null,"version":null,"openapi":"/openapi.json post /orders/{id}/cancel","href":"/api-reference/cancel-an-unpaid-order"},{"title":"Ask for volume rates","deprecated":null,"version":null,"openapi":"/openapi.json post /enterprise-inquiries","href":"/api-reference/ask-for-volume-rates"}]}]}]},"basePath":"","title":"Create a letter - Sendpaper","buildId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","deploymentId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","dynamics":["10e4515597","c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["BannerMarkdown-Dlc3Qr3h.js","dist-D2J8knkn.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","clsx-Dq9TQuNi.js","html-void-elements-mCSPHezU.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","OpenApiReferenceProvider-DdEMm2kG.js","utils-BMo572L7.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-C-4m9KAx.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DPLK2Oq9.js","snippetPresets-BKjfJMC9.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-DTsgtCEj.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-C8vmhyQM.js","shallow-r9w8LQGS.js","getApiPlaygroundDisplay-DjPI64HQ.js","CodeSnippet-C8Bvhl16.js","CodeSnippets-BtWUwcMy.js","Page-BIYvYBgk.js","getPastedJson-Dcm_3Pgl.js","icon-BXwrTpjc.js","MethodPill-CcjfVmmy.js","DuplicateIcon-BuKIbXAQ.js","createIcon-DaL9yXsO.js","DynamicMarkdown-Co5nikxh.js","SectionHeading-P4UNTsMZ.js","axios-vUo_bRtp.js","Markdown-CEfymfIH.js","AssistantPageLink-BgZ2ThuU.js"]}