{"openapi":"3.1.0","info":{"title":"IRIS Postal Forms API","version":"1.0.0","description":"Account-bound document upload and individual US letter or postcard mailing with prepaid credits. Every submission requires an idempotency key and prior human review. Campaigns, mailing lists, EDDM, scheduling, QR-code generation, and international addresses are unavailable."},"servers":[{"url":"https://api-staging.irispostalforms.com"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"irk_"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Address":{"type":"object","additionalProperties":false,"required":["primaryLine","city","state","zipCode"],"properties":{"recipient":{"type":"string","maxLength":120},"primaryLine":{"type":"string","minLength":1,"maxLength":200},"secondaryLine":{"type":"string","maxLength":200},"urbanization":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","minLength":2,"maxLength":2,"example":"MA"},"zipCode":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$","example":"02108"}}},"MailingRequest":{"oneOf":[{"type":"object","additionalProperties":false,"required":["product","primaryDocumentId","sender","recipient","options"],"properties":{"product":{"const":"letter"},"primaryDocumentId":{"type":"string","format":"uuid"},"sender":{"$ref":"#/components/schemas/Address"},"recipient":{"$ref":"#/components/schemas/Address"},"options":{"type":"object","additionalProperties":false,"required":["color","double_sided","certified","certified_return_receipt"],"properties":{"color":{"type":"boolean"},"double_sided":{"type":"boolean"},"certified":{"type":"boolean"},"certified_return_receipt":{"type":"boolean"}}}}},{"type":"object","additionalProperties":false,"required":["product","primaryDocumentId","secondaryDocumentId","sender","recipient","options"],"properties":{"product":{"const":"postcard"},"primaryDocumentId":{"type":"string","format":"uuid"},"sender":{"$ref":"#/components/schemas/Address"},"recipient":{"$ref":"#/components/schemas/Address"},"secondaryDocumentId":{"type":"string","format":"uuid"},"options":{"type":"object","additionalProperties":false,"required":["size","layout","font","artwork"],"properties":{"size":{"type":"string","enum":["4x6","6x9"]},"layout":{"type":"string","enum":["banner","poster","minimal"]},"font":{"type":"string","enum":["editorial","modern","handwritten"]},"artwork":{"type":"object","description":"Identifies the already-rendered postcard artwork represented by the uploaded PDFs.","additionalProperties":true}}}}}],"discriminator":{"propertyName":"product"}},"Quote":{"type":"object","required":["priceCents","breakdown"],"properties":{"priceCents":{"type":"integer","minimum":0},"breakdown":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Mailing":{"type":"object","required":["orderId","product","status","priceCents","createdAt"],"properties":{"orderId":{"type":"string","format":"uuid"},"product":{"type":"string","enum":["letter","postcard"]},"status":{"type":"string"},"priceCents":{"type":"integer"},"trackingNumber":{"type":["string","null"]},"expectedDeliveryDate":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}}},"security":[{"ApiKey":[]}],"paths":{"/v1/account":{"get":{"summary":"Get account credit balance","responses":{"200":{"description":"Account balance","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["accountId","creditBalanceCents"],"properties":{"accountId":{"type":"string","format":"uuid"},"creditBalanceCents":{"type":"integer"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required API-key scope missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/uploads/presign":{"post":{"summary":"Create a private PDF upload URL","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["fileName","sizeBytes","kind"],"properties":{"fileName":{"type":"string","pattern":"\\.pdf$"},"sizeBytes":{"type":"integer","minimum":1,"maximum":27262976},"kind":{"type":"string","enum":["letter","postcard_4x6","postcard_6x9"]}}}}}},"responses":{"200":{"description":"Ten-minute presigned PUT URL","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["key","uploadUrl","uploadHeaders","expiresSeconds"],"properties":{"key":{"type":"string"},"uploadUrl":{"type":"string","format":"uri"},"uploadHeaders":{"type":"object","required":["Content-Type","If-None-Match"],"properties":{"Content-Type":{"const":"application/pdf"},"If-None-Match":{"const":"*"}}},"expiresSeconds":{"const":600}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required API-key scope missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents":{"post":{"summary":"Validate and register an uploaded PDF","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["key","fileName","kind"],"properties":{"key":{"type":"string"},"fileName":{"type":"string"},"kind":{"type":"string","enum":["letter","postcard_4x6","postcard_6x9"]}}}}}},"responses":{"201":{"description":"Immutable document registered"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required API-key scope missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mailings/quote":{"post":{"summary":"Validate documents and quote one mailing","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailingRequest"}}}},"responses":{"200":{"description":"Server-authoritative mailing price","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Quote"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required API-key scope missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Document not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mailings":{"post":{"summary":"Create one credited letter or postcard mailing","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailingRequest"}}}},"responses":{"200":{"description":"Completed request replayed"},"201":{"description":"Mailing created"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits"},"403":{"description":"Required API-key scope missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mailings/{id}":{"get":{"summary":"Get mailing status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Mailing status","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Mailing"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required API-key scope missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Mailing not found"},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp":{"post":{"summary":"MCP Streamable HTTP endpoint","description":"Use the MCP protocol with Authorization: Bearer irk_… and Accept: application/json, text/event-stream.","responses":{"200":{"description":"MCP response"},"401":{"description":"Invalid API key"}}}}}}