{"openapi":"3.1.0","info":{"title":"mcpbrief","version":"1.8.0","description":"Send real letters and registered mail by post from ChatGPT (printed, enveloped, mailed). Prepaid, no subscription: standard letter from EUR 1.79, registered mail from EUR 7.79 (final prices incl. VAT, printing and postage). Always call getLetterPrice first and ask the user to confirm before sendLetter."},"servers":[{"url":"https://mcpbrief.de/api/v1"}],"paths":{"/letter/price":{"post":{"operationId":"getLetterPrice","summary":"Validate address, build the letter, count pages and get price + preview link (sends nothing, free)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient"],"properties":{"recipient":{"type":"object","description":"Postal address of the recipient exactly as given by the user. Never invent or look up an address.","properties":{"name":{"type":"string","description":"Person or company name (first address line), e.g. \"Stadtwerke Musterstadt GmbH\"."},"company":{"type":"string","description":"Optional second line, e.g. department or \"attn. Ms Smith\"."},"street":{"type":"string","description":"Street and house number, or PO box."},"zip":{"type":"string","description":"Postcode."},"city":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 code, e.g. \"DE\", \"AT\", \"CH\". Defaults to the account country."}},"required":["name","street","zip","city"]},"openaiFileIdRefs":{"type":"array","items":{"type":"string"},"description":"The file(s) the user uploaded in this chat that should be sent by post (PDF, JPG, PNG, DOCX). Only the first file is used; an address sheet is added as page 1."},"content":{"type":"string","description":"Letter body if there is no uploaded file (markdown or plain text): salutation, text, closing, sender name. Letterhead, recipient address and date are added automatically."},"content_format":{"type":"string","enum":["markdown","text"]},"delivery":{"type":"string","enum":["standard","express","registered"],"default":"standard","description":"standard = regular letter, express = priority mail, registered = registered mail (Einschreiben) with tracking number."},"color":{"type":"boolean","default":false,"description":"Colour print (+EUR 0.15 per page). Default black & white."},"duplex":{"type":"boolean","default":false,"description":"Print on both sides of the paper (fewer sheets, same price per page)."},"cost_center":{"type":"string","description":"Optional cost centre / reference for the user's accounting (shown in history and CSV export)."},"attachments":{"type":"array","maxItems":10,"description":"Optional enclosures appended after the letter (e.g. an invoice PDF): each item {file_base64, file_name} or {file_url}.","items":{"type":"object","properties":{"file_base64":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"}}}},"subject":{"type":"string","description":"Subject line printed in bold above the text (and on the address sheet)."},"address_mode":{"type":"string","enum":["auto","cover","document"],"default":"auto","description":"auto: text gets the letter layout, files get an address sheet (+1 page). document: the uploaded PDF already has the address in the left window position (recipient may then be omitted; pass country)."},"country":{"type":"string","description":"Only for address_mode=document without recipient: destination country (ISO-2) for the price."}}}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/letter/send":{"post":{"operationId":"sendLetter","summary":"Send the letter by post. External side effect that charges the balance – only after the user explicitly confirmed recipient address, delivery type, document and cost.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient"],"properties":{"recipient":{"type":"object","description":"Postal address of the recipient exactly as given by the user. Never invent or look up an address.","properties":{"name":{"type":"string","description":"Person or company name (first address line), e.g. \"Stadtwerke Musterstadt GmbH\"."},"company":{"type":"string","description":"Optional second line, e.g. department or \"attn. Ms Smith\"."},"street":{"type":"string","description":"Street and house number, or PO box."},"zip":{"type":"string","description":"Postcode."},"city":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 code, e.g. \"DE\", \"AT\", \"CH\". Defaults to the account country."}},"required":["name","street","zip","city"]},"openaiFileIdRefs":{"type":"array","items":{"type":"string"},"description":"The file(s) the user uploaded in this chat that should be sent by post (PDF, JPG, PNG, DOCX). Only the first file is used; an address sheet is added as page 1."},"content":{"type":"string","description":"Letter body if there is no uploaded file (markdown or plain text): salutation, text, closing, sender name. Letterhead, recipient address and date are added automatically."},"content_format":{"type":"string","enum":["markdown","text"]},"delivery":{"type":"string","enum":["standard","express","registered"],"default":"standard","description":"standard = regular letter, express = priority mail, registered = registered mail (Einschreiben) with tracking number."},"color":{"type":"boolean","default":false,"description":"Colour print (+EUR 0.15 per page). Default black & white."},"duplex":{"type":"boolean","default":false,"description":"Print on both sides of the paper (fewer sheets, same price per page)."},"cost_center":{"type":"string","description":"Optional cost centre / reference for the user's accounting (shown in history and CSV export)."},"attachments":{"type":"array","maxItems":10,"description":"Optional enclosures appended after the letter (e.g. an invoice PDF): each item {file_base64, file_name} or {file_url}.","items":{"type":"object","properties":{"file_base64":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"}}}},"subject":{"type":"string","description":"Subject line printed in bold above the text (and on the address sheet)."},"address_mode":{"type":"string","enum":["auto","cover","document"],"default":"auto","description":"auto: text gets the letter layout, files get an address sheet (+1 page). document: the uploaded PDF already has the address in the left window position (recipient may then be omitted; pass country)."},"country":{"type":"string","description":"Only for address_mode=document without recipient: destination country (ISO-2) for the price."},"idempotency_key":{"type":"string","description":"Unique key per send request; reuse on retries so the letter is never sent twice."},"max_cost_eur":{"type":"number"}}}}}},"responses":{"200":{"description":"Letter handed over","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"402":{"description":"Balance too low","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/letters/batch/price":{"post":{"operationId":"getBatchPrice","summary":"Mail merge: validate all recipients, fill placeholders, total price and preview (sends nothing)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipients","content"],"properties":{"recipients":{"type":"array","minItems":1,"maxItems":200,"description":"List of recipients. Each item: name, company (optional), street, zip, city, country (ISO-2) plus any custom fields used as placeholders (e.g. anrede, kundennummer).","items":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Person or company name (first address line), e.g. \"Stadtwerke Musterstadt GmbH\"."},"company":{"type":"string","description":"Optional second line, e.g. department or \"attn. Ms Smith\"."},"street":{"type":"string","description":"Street and house number, or PO box."},"zip":{"type":"string","description":"Postcode."},"city":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 code, e.g. \"DE\", \"AT\", \"CH\". Defaults to the account country."}},"required":["name","street","zip","city"]}},"content":{"type":"string","description":"Letter body template (Markdown) with placeholders like {{anrede}}, {{name}} or {{kundennummer}}. Letterhead, address and date are added automatically."},"content_format":{"type":"string","enum":["markdown","text"],"default":"markdown"},"delivery":{"type":"string","enum":["standard","express","registered"],"default":"standard","description":"standard = regular letter, express = priority mail, registered = registered mail (Einschreiben) with tracking number."},"color":{"type":"boolean","default":false,"description":"Colour print (+EUR 0.15 per page). Default black & white."},"duplex":{"type":"boolean","default":false,"description":"Print on both sides of the paper (fewer sheets, same price per page)."},"cost_center":{"type":"string","description":"Optional cost centre / reference for the user's accounting (shown in history and CSV export)."},"attachments":{"type":"array","maxItems":10,"description":"Optional enclosures appended after the letter (e.g. an invoice PDF): each item {file_base64, file_name} or {file_url}.","items":{"type":"object","properties":{"file_base64":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"}}}},"subject":{"type":"string","description":"Subject line printed in bold above the text (and on the address sheet)."}}}}}},"responses":{"200":{"description":"Batch quote","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/letters/batch/send":{"post":{"operationId":"sendLetterBatch","summary":"Mail merge: send one letter per recipient – only after the user confirmed count and total cost","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipients","content"],"properties":{"recipients":{"type":"array","minItems":1,"maxItems":200,"description":"List of recipients. Each item: name, company (optional), street, zip, city, country (ISO-2) plus any custom fields used as placeholders (e.g. anrede, kundennummer).","items":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"Person or company name (first address line), e.g. \"Stadtwerke Musterstadt GmbH\"."},"company":{"type":"string","description":"Optional second line, e.g. department or \"attn. Ms Smith\"."},"street":{"type":"string","description":"Street and house number, or PO box."},"zip":{"type":"string","description":"Postcode."},"city":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 code, e.g. \"DE\", \"AT\", \"CH\". Defaults to the account country."}},"required":["name","street","zip","city"]}},"content":{"type":"string","description":"Letter body template (Markdown) with placeholders like {{anrede}}, {{name}} or {{kundennummer}}. Letterhead, address and date are added automatically."},"content_format":{"type":"string","enum":["markdown","text"],"default":"markdown"},"delivery":{"type":"string","enum":["standard","express","registered"],"default":"standard","description":"standard = regular letter, express = priority mail, registered = registered mail (Einschreiben) with tracking number."},"color":{"type":"boolean","default":false,"description":"Colour print (+EUR 0.15 per page). Default black & white."},"duplex":{"type":"boolean","default":false,"description":"Print on both sides of the paper (fewer sheets, same price per page)."},"cost_center":{"type":"string","description":"Optional cost centre / reference for the user's accounting (shown in history and CSV export)."},"attachments":{"type":"array","maxItems":10,"description":"Optional enclosures appended after the letter (e.g. an invoice PDF): each item {file_base64, file_name} or {file_url}.","items":{"type":"object","properties":{"file_base64":{"type":"string"},"file_name":{"type":"string"},"file_url":{"type":"string"}}}},"subject":{"type":"string","description":"Subject line printed in bold above the text (and on the address sheet)."},"idempotency_key":{"type":"string"}}}}}},"responses":{"200":{"description":"Letters handed over","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/letter/{letter_id}":{"get":{"operationId":"getLetterStatus","summary":"Dispatch status (and tracking number for registered mail)","parameters":[{"name":"letter_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/letter/{letter_id}/resend":{"post":{"operationId":"resendLetter","summary":"Send a previous letter again (only after confirmation)","x-openai-isConsequential":true,"parameters":[{"name":"letter_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Letter handed over","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/letter/{letter_id}/cancel":{"post":{"operationId":"cancelLetter","summary":"Cancel a letter before it is printed (refund)","x-openai-isConsequential":true,"parameters":[{"name":"letter_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"409":{"description":"Already printed","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/letters":{"get":{"operationId":"getLetterHistory","summary":"List sent letters","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"since","in":"query","schema":{"type":"string","description":"YYYY-MM-DD"}}],"responses":{"200":{"description":"History","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/balance":{"get":{"operationId":"getAccountBalance","summary":"Prepaid balance, prices, sender address and top-up link","responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"schemas":{},"securitySchemes":{"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://mcpbrief.de/oauth/authorize.php","tokenUrl":"https://mcpbrief.de/oauth/token.php","scopes":{"letter":"Send letters and read letter status"}}}}}},"security":[{"oauth":["letter"]}]}