Letters

High-level description

Letters are non-payable content delivered as a document. Use the common payload below for every letter, then choose the most specific type for the recipient experience.

Sub-types

Type	Description	Retained delivery
letter	Informational letter for general communication.	Not supported
letter.creditnotice	Credit notice about a credit or adjustment.	Supported
letter.form	Content with an interactive form; see the Forms guide.	Not supported
letter.signed	Letter containing a signed document.	Supported
letter.salary	Legacy salary specification; deprecated from 1 October 2026.	Supported until deprecation

Common payload

Every letter request needs a recipient identifier, subject, type, and usually one or more PDF parts. letter is the default type for non-payable content.

Field	Purpose
ssn, email, or vat_number	Identifies the person or company recipient
subject	Short inbox title; never include personal or sensitive information
type	Selects the letter subtype
parts	Contains the complete letter as a PDF
generated_at	Optional timestamp used for inbox sorting
retain and retention_time	Enables retained delivery only for supported letter types
Type-specific object	Adds metadata such as form or signed when required

{
  "ssn": "YYYYMMDDNNNN",
  "subject": "Service update",
  "type": "letter",
  "parts": [
    {
      "name": "service-update.pdf",
      "content_type": "application/pdf",
      "data": "BASE64_ENCODED_PDF"
    }
  ]
}

Other information

See Retained content for delivery to recipients who have not yet registered, and Responsive content for adding a mobile-friendly view alongside the PDF.