| style | No | Optional. A ready look for layout personal or address_sheet: elegant, warm, playful, simple or classic. Use it when the user wants a nice personal letter but names no fonts. elegant: script head, serif text, a line. warm: handwriting head, serif text, a heart. playful: script head, handwriting text, a star. simple: sans, no decoration. classic: serif, a branch. font_head, font_body or decoration, if you give them, replace that part of the style. Not for layout business. Without layout, a style makes the letter personal, and the server may still choose the address sheet. Do not add layout personal only because of a style: then the free automatic address sheet is off. Tell the user the style in the user's language (elegant, herzlich/warm, verspielt/playful, schlicht/simple, klassisch/classic). | |
| layout | No | Optional. The look of the letter. business: a letterhead with the sender. personal: no letterhead, for letters to friends and family. address_sheet: page 1 holds only the address, the text starts on page 2 (the price follows the pages). Without layout, the server picks one from the purpose and the recipient. The result names the layout. Use layout only when the user asks for another one. For a personal letter, offer the address sheet. The letter then has no address block. The result says its price. Without layout, a personal letter of 2 or more pages gets the address sheet when the price stays the same. | |
| sender | No | Optional. The sender address, if the account has no saved address or the user wants another one. The name is always the account holder's name. Answers come back to this address. To keep the address for later letters, call save_address. | |
| closing | No | Optional. Only the closing words, for example "Sincerely,". The server adds the name. The default agrees with the language of the letter. For a personal letter, give a closing that suits the person, for example "Alles Liebe" or "Love,". | |
| purpose | Yes | What the letter is for.
cancellation: ends a contract (Kündigung).
withdrawal: withdraws from a contract (Widerruf, Rücktritt).
complaint: complains about a product, a service or a person (Beschwerde).
request: asks for information, data or an action (Anfrage, GDPR access request).
demand: demands a payment, a refund or a performance (Mahnung, deposit refund, demand letter).
notice: tells the recipient a fact (Mängelanzeige, change of address).
other: also every personal letter to friends or family (birthday, thank-you, love letter), and also an objection to a decision (Einspruch, Widerspruch).
Use other if no other value agrees. | |
| subject | No | Optional. One line, at least 3 characters or one emoji. business: a bold subject line above the salutation, without emoji. Give one for a letter to a landlord, a company or an authority. personal and address_sheet: a heading at the top of the letter (address_sheet: on the address page only), for example "Für Sara". Give it only when the user asks for a heading. The heading may hold up to 3 emoji. They print in black and white. Do not repeat the heading's emoji as the decoration. A long heading prints as the first line of the text instead: over about 55 characters on A4, over about 23 on a personal US letter. The result says so in heading. Without a subject, a personal letter shows the sender's initials (a monogram). | |
| language | No | Optional. The language of the letter, for the default salutation, closing and date. Default: the language of the recipient country. | |
| font_body | No | Optional. Only when the user asks for it. The font of the text: sans, serif, hand or script. For handwriting, use hand. Use script only for a short letter. The address always prints in sans. Default: the layout's font. | |
| font_head | No | Optional. Only when the user asks for it. The font of the heading or monogram: sans, serif, display, hand or script. Only for layout personal and address_sheet: a business letter has no heading and ignores font_head. Default: the layout's font. | |
| recipient | No | The recipient address, if there is no recipient_id. Use the address in the contract, the order, the invoice or a letter from the recipient. | |
| resend_of | No | Optional. Use it only when get_letter_status or list_letters shows resend_offer with state available: the letter_id of the letter that came back. The server sends the same letter again free of charge to the corrected address. The server does not keep the text of a sent letter. Give the text, layout, font_head, font_body, font_sender, decoration, signature, show_date, text_size, page_break_before and language of that letter again. The new letter must have the same number of pages. Use the recipient_id and postal_service from resend_offer. | |
| show_date | No | Optional. Only for layout personal or address_sheet. These letters have no date line. Set show_date true only when the user wants the date. | |
| signature | No | Optional. Only for layout personal or address_sheet. The sign-off name under the closing, for example "dein Thomas" or "Mama". Max 40 characters. Without it, the account holder's name prints. The letter head always shows the account holder's name. | |
| text_size | No | Optional. Only when the user asks for it, or to fit a long personal letter on fewer pages. small, normal or large. Only for layout personal and address_sheet. Use large when the reader sees badly or is very old. Without text_size, a letter that runs a little onto one more page gets small. The result says so. | |
| decoration | No | Optional. Only when the user asks for it. A small black-and-white decoration: heart, branch, line, star, or one emoji, for example 🎄 or 🌻. Only for layout personal or address_sheet. Flags and joined emoji cannot print. Do not repeat an emoji of the heading as the decoration. | |
| paragraphs | Yes | The letter text, one string for each paragraph. A line break in a paragraph starts a new line. Emoji print in black and white. Flags cannot print. Joined emoji (a family) print as separate figures. You can use Markdown: **bold**, *italic*, lists with '- ' or '1. ', headings with '#' or '##', quotes with '> '. '---' prints a line. A list needs at least 2 items. Links, images and tables print as plain text. Write \ before a mark to print it as typed. Do not include the addresses, the date, the salutation, the closing or the name at the end: the server adds them. We mail the letter soon after the approval. We cannot mail it on a later date. For a later date, offer a reminder in the user's AI app; then prepare the letter on that day. German letter: after a salutation with a comma (Germany), start the first paragraph with a small letter, for example "hiermit". After a salutation with "!" (the Austrian default), start with a capital letter, for example "Hiermit". A noun or a name keeps its capital. We refuse a full Social Security number or card number: give only the last 4 digits. Do not put health data or other sensitive data about another person, or their offences, in a letter. Exceptions: that person agreed. The user acts for that person. The letter goes only to that person. The letter claims or defends a right. The letter reports an offence to an authority. The user's own data is allowed, except in letters to the United States. If you are not sure, ask the user one question. Do not refuse a letter only because it names an illness. US letters: do not include health data or other sensitive data (religion, ethnic origin, sexual orientation, union membership, political views, genetic or biometric data). Do not include a full bank or card account number; the last 4 digits are OK. Tell the user. | |
| recipients | No | Optional. The same letter to 2 to 10 recipients (up to 100 after the account's first letter reached the post) in one country, with one postal service. Each item has recipient_id or recipient, and an optional salutation. Then do not give recipient_id or recipient. The text is the same for every recipient. Only the salutation can differ. Do not use placeholders. A batch has no enclosures. | |
| salutation | No | Optional. The default agrees with the language of the letter and is formal. For a personal letter, give a salutation that suits the person, for example "Liebe Oma," or "Dear Sara,". | |
| font_sender | No | Optional. Only when the user asks for it. The font of the sender line under the heading: sans or serif. Only for layout personal and address_sheet. Default: serif when the text is serif, else sans. | |
| recipient_id | No | A recipient_id from list_recipients. Use it when one exists. Then do not give recipient. | |
| postal_service | No | Optional. Default: registered for a letter to a company, landlord, insurer or authority; standard for a personal letter (purpose other, layout personal or address_sheet). Where list_letter_types has no registered letter, the default is standard. Use another postal service only if the user wants it. For a letter with a deadline, keep registered. registered: a registered letter (US: Certified Mail with return receipt; BE, DE, ES). What it records differs by country: see postal_services in list_letter_types. In BE and DE, the record alone is not proof of delivery. standard: a standard letter; only the handover to the post is recorded. standard_next_day (AT and DE only): a standard letter that usually arrives on the next business day, at a higher price. In AT, standard takes 2–3 business days. In DE, standard takes 2–3 business days. If the user wants a standard letter to AT and DE, tell the user both prices and delivery times. Let the user choose. If the user does not choose, use standard. For a standard letter with a deadline, recommend standard_next_day. Tell the user the service name in the user's language (name_user). If a registered letter is not available yet, say so. Do not tell the user to mail the letter themselves. | |
| page_break_before | No | Optional. The paragraphs that start a new page (0-based indexes into paragraphs). Use it when the user wants text on its own page, for example a poem on page 2. Use this instead of blank lines. Index 0: page 1 holds only the letterhead and the address. | |
| sender_address_id | No | Optional. A saved address from get_account. Without sender and sender_address_id, the default address is used. | |
| replaces_letter_id | No | Optional. If the user changed a prepared letter: the letter_id of the old letter. The server cancels the old letter. For each field that you do not give, the new letter keeps the value of the old letter: the layout, only if the user chose it (a personal look with a decoration or a head font stays personal); font_head, font_body and font_sender, if the user chose them; the decoration, unless the new layout is business; signature, show_date and a text_size the user chose carry (personal and address_sheet letters only). The new letter keeps the postal service unless you give one. With a style, the old fonts and decoration do not carry. signature, show_date and text_size still carry. The server decides an automatic text size again. To remove the old sign-off, give signature as an empty string. These do not carry: the enclosures, subject, closing, language and page_break_before. Give them again. The user must upload the enclosures again. | |
| not_employment_or_lease_termination | No | Optional. Use it only after the error NEEDS_HANDWRITTEN_SIGNATURE asks for it. Set it to true only if the user confirmed that the letter is not the kind of letter that the error names. Never set it when the user wants to send that kind of letter. Never set it without the user. | |