{"openapi":"3.1.0","info":{"title":"SendRegistered API","version":"1.0.0","summary":"Send registered letters to 8 countries from your software.","description":"Upload a PDF, create and pay a registered letter from prepaid business credit, follow tracking with signed webhooks and download the proof certificate. All amounts in API responses are in cents of the stated currency.","contact":{"name":"SendRegistered Support","url":"https://sendregistered.com/contact","email":"support@sendregistered.com"}},"servers":[{"url":"https://api.sendregistered.com/v1","description":"Production & test API host (mode determined by API key prefix sr_live_ or sr_test_)"},{"url":"https://sendregistered.com/v1","description":"Primary web origin"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Documents","description":"Upload PDFs and check envelope address window fit."},{"name":"Letters","description":"Create, pay, inspect, cancel and download proof for registered letters."},{"name":"Pricing & Balance","description":"List destinations, calculate quotes and inspect credit balance."},{"name":"Webhooks","description":"Signed event notifications for letter status transitions and low credit."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (sr_live_... or sr_test_...)","description":"Authenticate with `Authorization: Bearer sr_live_...` for real letters or `Authorization: Bearer sr_test_...` for free sandbox test letters."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique string (8–200 characters) per write operation to safely retry without duplicate charges.","schema":{"type":"string","minLength":8,"maxLength":200}},"LetterId":{"name":"id","in":"path","required":true,"description":"Letter identifier (e.g. `SR-2026-00042` or `SR-TEST-2026-00001`).","schema":{"type":"string"}}},"schemas":{"DestinationCode":{"type":"string","enum":["DE","FR","BE","ES","CH","NL","GB","US"]},"Address":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"street":{"type":"string","minLength":1,"maxLength":160},"zip":{"type":"string","minLength":1,"maxLength":20},"city":{"type":"string","minLength":1,"maxLength":100},"country":{"type":"string","minLength":2,"maxLength":60},"state":{"type":"string","maxLength":2},"attn":{"type":"string","maxLength":100}},"required":["name","street","zip","city","country"]},"QuoteRequest":{"type":"object","properties":{"destination":{"type":"string","enum":["DE","FR","BE","ES","CH","NL","GB","US"]},"product_id":{"type":"string","maxLength":100},"color":{"default":false,"type":"boolean"},"duplex":{"default":false,"type":"boolean"},"acknowledgement":{"default":false,"type":"boolean"},"pages":{"type":"integer","minimum":1,"maximum":20},"sender_country":{"type":"string","maxLength":60}},"required":["destination","pages"]},"DocumentUploadRequest":{"type":"object","properties":{"filename":{"default":"letter.pdf","type":"string","maxLength":100},"content_base64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["content_base64"]},"LetterCreateRequest":{"type":"object","properties":{"destination":{"type":"string","enum":["DE","FR","BE","ES","CH","NL","GB","US"]},"product_id":{"type":"string","maxLength":100},"color":{"default":false,"type":"boolean"},"duplex":{"default":false,"type":"boolean"},"acknowledgement":{"default":false,"type":"boolean"},"document_id":{"type":"string","minLength":1,"maxLength":100},"sender":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"street":{"type":"string","minLength":1,"maxLength":160},"zip":{"type":"string","minLength":1,"maxLength":20},"city":{"type":"string","minLength":1,"maxLength":100},"country":{"type":"string","minLength":2,"maxLength":60},"state":{"type":"string","maxLength":2},"attn":{"type":"string","maxLength":100}},"required":["name","street","zip","city","country"]},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"street":{"type":"string","minLength":1,"maxLength":160},"zip":{"type":"string","minLength":1,"maxLength":20},"city":{"type":"string","minLength":1,"maxLength":100},"country":{"type":"string","minLength":2,"maxLength":60},"state":{"type":"string","maxLength":2},"attn":{"type":"string","maxLength":100}},"required":["name","street","zip","city","country"]},"cover":{"default":true,"type":"boolean"},"fit_approved":{"default":false,"type":"boolean"},"terms":{"default":false,"type":"boolean"},"topic":{"type":"string","maxLength":80},"handwritten_ack":{"default":false,"type":"boolean"},"pay":{"default":true,"type":"boolean"}},"required":["destination","document_id","sender","recipient"]},"LetterPayRequest":{"type":"object","properties":{"terms":{"type":"boolean","const":true}},"required":["terms"],"additionalProperties":false},"LetterSummary":{"type":"object","required":["id","test","status","destination","product_id","pages","currency","amount","credit_amount","created_at","paid_at","tracking_number","times","cancelled"],"properties":{"id":{"type":"string","description":"Unique letter ID."},"test":{"type":"boolean","description":"True when created with an `sr_test_` key."},"status":{"type":"string","enum":["awaiting_confirmation","awaiting_payment","received","printed","posted","transit","delivered","returned","refunded","failed","closed"]},"destination":{"$ref":"#/components/schemas/DestinationCode"},"product_id":{"type":"string","description":"Catalogue product ID such as `de-einwurf` or `fr-lrar`."},"pages":{"type":"integer","minimum":1,"maximum":20},"currency":{"type":"string","enum":["EUR","CHF"]},"amount":{"type":"integer","description":"Total amount in cents."},"credit_amount":{"type":"integer","description":"Amount debited from prepaid credit in EUR cents."},"created_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"tracking_number":{"type":["string","null"]},"times":{"type":"object","additionalProperties":{"type":"string"}},"cancelled":{"type":"boolean"},"key_id":{"type":"string"}}},"WebhookEvent":{"type":"object","required":["id","type","created_at","livemode","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["letter.paid","letter.printed","letter.posted","letter.awaiting_pickup","letter.delivered","letter.failed","letter.cancelled","balance.low"]},"created_at":{"type":"string","format":"date-time"},"livemode":{"type":"boolean"},"data":{"type":"object"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","doc_url"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"doc_url":{"type":"string","format":"uri"}}}}}}},"paths":{"/openapi.json":{"get":{"operationId":"getOpenApiSpec","summary":"OpenAPI 3.1 specification","description":"Returns this OpenAPI 3.1 specification generated directly from the handler schemas.","security":[],"tags":["Pricing & Balance"],"responses":{"200":{"description":"OpenAPI 3.1 JSON document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/destinations":{"get":{"operationId":"listDestinations","summary":"List destinations and products","description":"Returns all 8 supported destination countries, available postal products, carrier names and prices in cents.","tags":["Pricing & Balance"],"responses":{"200":{"description":"Destinations and products on sale","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/quotes":{"post":{"operationId":"createQuote","summary":"Calculate a letter quote","description":"Quotes a letter in cents for the authenticated business account, applying EU reverse charge or non-EU VAT rules when configured on the account.","tags":["Pricing & Balance"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Price quote in cents","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid quote parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/balance":{"get":{"operationId":"getBalance","summary":"Get prepaid credit balance","description":"Returns the account's prepaid credit balance in EUR cents (`paid`, `bonus`, `subscription`, `total` and active `lots`).","tags":["Pricing & Balance"],"responses":{"200":{"description":"Current credit balance and active credit lots","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/documents":{"post":{"operationId":"uploadDocument","summary":"Upload a PDF document","description":"Uploads a base64-encoded PDF (up to 8 MB, 1–20 pages) and checks whether the pages fit the printable area and envelope window.","tags":["Documents"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadRequest"}}}},"responses":{"201":{"description":"Uploaded document metadata and fit check result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid PDF or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/letters":{"post":{"operationId":"createLetter","summary":"Create (and optionally pay) a registered letter","description":"Creates a registered letter from an uploaded document. Pass `pay: true` and `terms: true` to pay immediately from prepaid credit and queue for printing.","tags":["Letters"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterCreateRequest"}}}},"responses":{"201":{"description":"Created letter summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterSummary"}}}},"409":{"description":"Insufficient credit, spending limit exceeded, or product not on sale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listLetters","summary":"List recent letters","description":"Returns up to 100 letters created through the API in the key's mode (`live` or `test`).","tags":["Letters"],"responses":{"200":{"description":"List of letters","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LetterSummary"}}}}}}}}}},"/letters/{id}":{"get":{"operationId":"getLetter","summary":"Get a letter","description":"Returns status, price, timestamps and tracking number for one letter.","tags":["Letters"],"parameters":[{"$ref":"#/components/parameters/LetterId"}],"responses":{"200":{"description":"Letter summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterSummary"}}}},"404":{"description":"Letter not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/letters/{id}/pay":{"post":{"operationId":"payLetter","summary":"Pay an unpaid letter from credit","description":"Pays an existing `awaiting_confirmation` or `awaiting_payment` letter from prepaid credit within the API key's spending limit.","tags":["Letters"],"parameters":[{"$ref":"#/components/parameters/LetterId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterPayRequest"}}}},"responses":{"200":{"description":"Paid letter summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterSummary"}}}}}}},"/letters/{id}/cancel":{"post":{"operationId":"cancelLetter","summary":"Cancel a letter before printing","description":"Cancels an unpaid draft or withdraws a paid letter before it has been printed, returning credit to the balance.","tags":["Letters"],"parameters":[{"$ref":"#/components/parameters/LetterId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Cancelled letter summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterSummary"}}}}}}},"/letters/{id}/proof":{"get":{"operationId":"getLetterProof","summary":"Get proof certificate facts or PDF","description":"Returns proof hashes, timestamps and tracking JSON, or streams the proof certificate PDF when `?format=pdf` or `Accept: application/pdf` is passed.","tags":["Letters"],"parameters":[{"$ref":"#/components/parameters/LetterId"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","pdf"]},"description":"Pass `pdf` to download the proof certificate PDF."}],"responses":{"200":{"description":"Proof certificate JSON or PDF","content":{"application/json":{"schema":{"type":"object"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}}}}}}}