Update a letter
const url = 'https://api.tryletterhead.com/api/v3/letters/example';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"publicationStatus":3,"segmentId":0,"includePromotions":true,"title":"This week\'s edition","subtitle":"Everything you need to know","blocks":"[]","openGraphHeadline":"This week\'s edition","openGraphDescription":"Everything you need to know","openGraphImageUrl":""}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.tryletterhead.com/api/v3/letters/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "publicationStatus": 3, "segmentId": 0, "includePromotions": true, "title": "This week'\''s edition", "subtitle": "Everything you need to know", "blocks": "[]", "openGraphHeadline": "This week'\''s edition", "openGraphDescription": "Everything you need to know", "openGraphImageUrl": "" }'Update a letter (or template) by its unique identifier.
This is the v3 (company-scoped) full update. It replaces the letter’s content and configuration in one call and returns the updated letter.
What is the letter’s unique identifier? An alphanumeric string, often around ten characters, e.g. ludctamgd6. It is returned by the create/draft/send endpoints.
This is a full replace, not a partial update
Every writable field is set from the request body. Any field you omit is reset to its default (empty string for text fields, default settings for settings). Fetch the letter first with Retrieve a Letter by its UUID, change what you need, and send the whole object back.
If you only want to change one thing, prefer the narrower endpoints — they exist precisely so you don’t have to round-trip the full payload:
| Endpoint | Updates |
|---|---|
POST /api/v3/letters/{uniqueId}/settings | Letter settings |
POST /api/v3/letters/{uniqueId}/permissions | Permissions only |
POST /api/v3/letters/{uniqueId}/update-status | Publication status only |
POST /api/v3/letters/{uniqueId}/tags | Tags |
Required fields
| Field | Type | Notes |
|---|---|---|
publicationStatus | integer | One of 3 (template), 8 (configuring), 9 (configured). Scheduling and sending are not done here — use the send/schedule endpoints. |
segmentId | integer | The audience segment the letter targets. |
includePromotions | boolean | Whether promotions are composed into the letter. |
Optional fields
title, subtitle, blocks, html, mjmlTemplate, campaignId, private, publicationDate, openGraphHeadline (max 180), openGraphDescription (max 180), openGraphImageUrl.
If openGraphHeadline / openGraphDescription are omitted they fall back to title / subtitle.
Responses
-
200— the updated letter. -
403— the letter is claimed by another editor (body is the current claimant). -
422— validation failed.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The letter’s unique identifier — an alphanumeric string around ten characters, e.g. ludctamgd6.
Request Body required
Section titled “Request Body required ”object
Example
{ "publicationStatus": 3, "segmentId": 0, "includePromotions": true, "title": "This week's edition", "subtitle": "Everything you need to know", "blocks": "[]", "openGraphHeadline": "This week's edition", "openGraphDescription": "Everything you need to know", "openGraphImageUrl": ""}Responses
Section titled “ Responses ”Successful response
Still can’t find what you need? Contact support.