{"openapi":"3.1.0","info":{"title":"Print and Mail Company API","version":"1.0.0","description":"Print and mail letters worldwide from Luxembourg. Upload a PDF or compose a letter, create a draft with the exact price, then send it (paid from prepaid credit). Authentication: create an API key in your account (Settings → API & AI assistants) and send it as `Authorization: Bearer pmc_…`. AI assistants should prefer the MCP server at https://printandmailcompany.com/mcp.","contact":{"name":"LeFaLux vGmbH","email":"support@printandmailcompany.com","url":"https://printandmailcompany.com"},"termsOfService":"https://printandmailcompany.com/en/legal/terms"},"servers":[{"url":"https://printandmailcompany.com/api/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"pmc_…"}},"schemas":{"Address":{"type":"object","required":["name","line1","city","country"],"properties":{"name":{"type":"string","maxLength":60},"company":{"type":"string","maxLength":60},"line1":{"type":"string","maxLength":60,"description":"Street and number or PO box"},"line2":{"type":"string","maxLength":60},"postalCode":{"type":"string","maxLength":16},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":50,"description":"State/province where used (e.g. US state code)"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}},"security":[{"apiKey":[]}],"paths":{"/quote":{"get":{"operationId":"getQuote","summary":"Price for a letter (public, no API key needed)","security":[],"parameters":[{"name":"pages","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":250}},{"name":"country","in":"query","required":true,"schema":{"type":"string"},"description":"ISO country code, e.g. DE"},{"name":"postal_code","in":"query","schema":{"type":"string"}},{"name":"duplex","in":"query","schema":{"type":"boolean"}},{"name":"color","in":"query","schema":{"type":"string","enum":["bw","color"]}},{"name":"envelope","in":"query","schema":{"type":"string","enum":["DL","C5","C4"]}},{"name":"registered","in":"query","schema":{"type":"boolean"}},{"name":"currency","in":"query","schema":{"type":"string","enum":["EUR","USD","GBP","CHF"]}}],"responses":{"200":{"description":"Price breakdown incl. VAT"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/destinations":{"get":{"operationId":"listDestinations","summary":"Countries, zones and 1-page price (public)","security":[],"responses":{"200":{"description":"List of destinations"}}}},"/balance":{"get":{"operationId":"getBalance","summary":"Prepaid credit","responses":{"200":{"description":"Balance in minor units"}}}},"/documents":{"post":{"operationId":"uploadDocument","summary":"Upload a PDF (multipart 'file', or JSON with pdf_url / pdf_base64) and run the print check","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","properties":{"pdf_url":{"type":"string","format":"uri"},"pdf_base64":{"type":"string"},"file_name":{"type":"string"}}}}}},"responses":{"201":{"description":"Document with print check (compliant, analysis per page)"}}}},"/documents/{id}":{"get":{"operationId":"getDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Document"}}}},"/documents/{id}/fix":{"post":{"operationId":"fixDocument","summary":"Shrink pages to fit the required margins","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated document"}}}},"/compose":{"post":{"operationId":"composeLetter","summary":"Render text into an A4 letter (DIN 5008) and create a draft","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["sender","recipient","subject","body"],"properties":{"sender":{"$ref":"#/components/schemas/Address"},"recipient":{"$ref":"#/components/schemas/Address"},"subject":{"type":"string"},"body":{"type":"string","description":"Paragraphs separated by blank lines, '- ' bullets, **bold**"},"language":{"type":"string","default":"en"},"place":{"type":"string"},"date":{"type":"string","format":"date"},"closing":{"type":"string"},"signature":{"type":"string"},"references":{"type":"array","items":{"type":"string"}},"duplex":{"type":"boolean","default":false},"color":{"type":"string","enum":["bw","color"],"default":"bw"},"envelope":{"type":"string","enum":["DL","C5","C4"],"description":"Omit for the smallest envelope that fits"},"registered":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Document and draft letter with price"}}}},"/letters":{"get":{"operationId":"listLetters","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Letters"}}},"post":{"operationId":"createLetter","summary":"Create a draft letter (nothing is charged)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["documentId","recipient"],"properties":{"documentId":{"type":"string"},"recipient":{"$ref":"#/components/schemas/Address"},"returnAddress":{"$ref":"#/components/schemas/Address"},"duplex":{"type":"boolean","default":false},"color":{"type":"string","enum":["bw","color"],"default":"bw"},"envelope":{"type":"string","enum":["DL","C5","C4"],"description":"Omit for the smallest envelope that fits"},"registered":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Draft letter with total"}}}},"/letters/{id}":{"get":{"operationId":"getLetter","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Letter"}}}},"/letters/{id}/send":{"post":{"operationId":"sendLetter","summary":"Pay from credit and send. acceptTerms must be true (the user accepted the Terms and the immediate start).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["acceptTerms"],"properties":{"acceptTerms":{"const":true}}}}}},"responses":{"200":{"description":"Paid letter"},"402":{"description":"Not enough credit (details.shortfall)"}}}},"/letters/{id}/cancel":{"post":{"operationId":"cancelLetter","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled letter; amount returned to credit"}}}}}}