Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      Template errors

      All errors are problem documents. The tables below give the title and detail you will see.

      Managing templates

      POST /v1/templates, PUT /v1/templates/{id}, GET, DELETE.

      Status Title Detail Cause
      400 Invalid JSON body the decoder’s message Malformed JSON, or a field of the wrong type.
      400 Invalid template A template needs a name. name missing or whitespace only.
      400 Invalid template That template name is too long. Over 120 characters.
      400 Invalid template That subject is too long. Over 255 characters.
      400 Invalid template That template is too large to save. html or text over 512 KiB.
      400 Invalid template Supply at least one of `html` or `text`. Both empty.
      400 Invalid template names the offending text A {{ that does not form a placeholder.
      400 Invalid template id empty The path segment is not a UUID.
      404 Template not found empty No such template in this workspace.
      403 Insufficient scope This endpoint requires scope: templates:write Key lacks templates:read or templates:write. Carries "code": "insufficient_scope".

      Validation stops at the first failure in the order above, so correcting one can reveal the next.

      Template history

      GET /v1/templates/{id}/versions, GET .../versions/{version}, POST .../versions/{version}/restore.

      Status Title Detail Cause
      400 Invalid template id empty The id is not a UUID.
      400 Invalid version names what a version is Not a positive whole number.
      404 Template not found empty No such template in this workspace.
      404 Version not found No version N for that template. Never existed, or pruned past the 50-version cap.
      403 Insufficient scope names the scope Restoring needs templates:write; reading needs templates:read.

      Sending with a template

      POST /v1/send and each entry of POST /v1/send/batch.

      Status Title Detail Cause
      400 Template conflict Provide either template_id or inline subject/text/html, not both. template_id sent with any of subject, html, text.
      400 Invalid template_id empty Not a UUID.
      400 Template not found No template with that id. Well-formed UUID, no such template here.
      400 Invalid variables Template variables must be strings... A number, boolean, array or object in variables.
      400 Invalid JSON body names the field and the type it wanted A type error on some other field.

      In a batch these arrive as the error string on the individual result rather than as a problem document, keyed by index. One bad entry does not fail the others.

      The non-string variable error

      { "variables": { "order_total": 49.99 } }
      {
        "status": 400,
        "title": "Invalid variables",
        "detail": "Template variables must be strings. Quote every value, including numbers and booleans: {\"variables\": {\"total\": \"49.99\"}}, not {\"variables\": {\"total\": 49.99}}."
      }

      Nothing is wrong with your JSON as JSON. variables accepts strings only, and a number, boolean, array or object in any value rejects the whole request before anything else is looked at.

      null is accepted and renders as an empty string.

      Errors you will not get

      These are the cases people expect to be errors and which succeed instead. Each one is covered in more detail elsewhere, and together they are the reason to read a rendered message rather than a status code.

      What you did What happens
      Misspelt a placeholder in the template Renders as an empty string. 202.
      Misspelt a key in variables Ignored. 202.
      Omitted a variable the template uses Renders as an empty string. 202.
      Saved a template with broken HTML Stored and sent as written.
      Saved a template with no subject Sent with an empty subject.

      {{#if x}} and {{a b}} used to be on that list too, sent to the recipient as literal text. They are now rejected at save time: see Template validation.

      The rest remain, because none of them can be distinguished from something somebody meant. Testing rendered emails is how to catch them.