Update a letter template

Applies a partial update: provide at least one of name, html, variables, or status — an empty request is a 400, name/html cannot be set to empty strings, and html over 512 KiB is a 413.

Endpoint

PATCH https://api.dairo.app/v1/letters/templates/{id}

Applies a partial update: provide at least one of name, html, variables, or status — an empty request is a 400, name/html cannot be set to empty strings, and html over 512 KiB is a 413. Set status to archived to retire a template without deleting it, or back to active to reuse it; letters already sent from it are unaffected. Returns the updated letter_template, or 404 when the id is unknown. Requires the letters:send scope.

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

Request

cURL

curl -X PATCH "https://api.dairo.app/v1/letters/templates/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Path parameters

Name	Type	Required	Description
`id`	string	yes	The letter template's ID.

Body

Required, application/json: UpdateLetterTemplateRequest.

Partial update. Provide at least one of name, html, variables, or status.

Field	Type	Required	Description
`name`	string	no
`html`	string	no
`variables`	array of string or LetterTemplateVariable or object	no	Declared template variables. Preferred: [{name, type?, example?, label?}]. Also accepted: an array of names, or an object {name: type}. Stored and returned in the preferred shape.
`status`	LetterTemplateStatus	no

Response

200 Success. Body: application/json, LetterTemplate.

Field	Type	Required	Description
`object`	`"letter_template"`	yes
`id`	string	yes
`name`	string	yes
`html`	string	no	The branded letter HTML with {{placeholders}} and a blank recipient address window. Omitted from list items.
`variables`	array of LetterTemplateVariable	no	Declared template variables, stored and returned as [{name, type?, example?, label?}].
`status`	LetterTemplateStatus	yes
`createdAt`	string (date-time) or null	no
`updatedAt`	string (date-time) or null	no

200

{
  "object": "letter_template",
  "id": "string",
  "name": "Ada Lovelace",
  "html": "string",
  "variables": [
    {
      "name": "Ada Lovelace",
      "type": "string",
      "example": "string",
      "label": "production"
    }
  ],
  "status": "active",
  "createdAt": "2026-10-19T09:30:00Z",
  "updatedAt": "2026-10-19T09:30:00Z"
}

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`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`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`).