Get the letter layout spec and starter templates

Returns the machine-readable compliance spec for physical letters: the exact A4 geometry (address windows, franking/edge/corner keep-outs, all in mm from the top-left corner), the PDF rules (embed fonts, no encryption, A4 portrait), the recommended verify→price→dryRun→send workflow, and ready-made COMPLIANT starter templates whose html can be stored via POST /v1/letters/templates verbatim.

Endpoint

GET https://api.dairo.app/v1/letters/requirements

Returns the machine-readable compliance spec for physical letters: the exact A4 geometry (address windows, franking/edge/corner keep-outs, all in mm from the top-left corner), the PDF rules (embed fonts, no encryption, A4 portrait), the recommended verify→price→dryRun→send workflow, and ready-made COMPLIANT starter templates whose html can be stored via POST /v1/letters/templates verbatim. Static and deterministic — agents composing physical mail should fetch this first instead of relying on prior knowledge of postal layout standards.

Scope: letters:read. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl "https://api.dairo.app/v1/letters/requirements" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Response

200 Success. Body: application/json, LetterRequirements.

Field	Type	Required	Description
`object`	`"letter_requirements"`	no
`version`	string	no
`printMode`	`"test"`, `"live"`	no	The account's letter print mode, the same as `letters.printMode` on `GET /v1/whoami`. `test` letters are never printed.
`printModeNote`	string	no
`testMode`	object	no	`endState`: what happens to a letter created in test mode (it stays `processing`, is never printed or charged, does not expire; cancel it to close it out).
`destinations`	object	no	Accepted recipient countries: `supportedCountries` is `"any"` (every assigned ISO 3166-1 alpha-2 code) or the configured list; `printCentreCountry` is where letters are posted (domestic); `registered` states the domestic-only rule.
`summary`	string	no
`pageSetup`	object	no
`addressWindow`	object	no
`keepOuts`	object	no
`bodyLayout`	object	no
`pdfRules`	array of string	no
`workflow`	array of object	no
`starterTemplates`	array of object	no
`endpoints`	object	no
`agentHint`	string	no
`mcpTools`	map of string	no	Which MCP tool carries each letters action (prepare_letters, list_letters, send_letters).

200

{
  "object": "letter_requirements",
  "version": "string",
  "printMode": "test",
  "printModeNote": "string",
  "testMode": {},
  "destinations": {},
  "summary": "string",
  "pageSetup": {},
  "addressWindow": {},
  "keepOuts": {},
  "bodyLayout": {},
  "pdfRules": [
    "string"
  ],
  "workflow": [
    {}
  ],
  "starterTemplates": [
    {}
  ],
  "endpoints": {},
  "agentHint": "string",
  "mcpTools": {}
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).

Get the letter layout spec and starter templates

Request

Response

Errors

On this page