Create a letter

POST

/api/v3/letters

const url = 'https://api.tryletterhead.com/api/v3/letters?api=true';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

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?api=true' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Create a new company letter — a template, ready to configure and eventually publish to a channel.

Two ways to create one:

Omit html to create a blank company template, the same starting point as clicking “New” in the composer. Edit it afterward with Update a letter or the narrower per-field endpoints.
Pass html to create the letter directly from your own markup instead. A letter created this way is not editable in our visual composer — you continue to manage its content by sending updated HTML.

The new letter always starts as a company-level template, not yet attached to a channel or scheduled. Use Clone a letter to move a copy onto a channel, then Update a letter to configure it for sending.

Authorizations

bearerAuth

Parameters

Query Parameters

api

required

boolean

When true, tells the endpoint you are authenticating with a company API key (generated under a company’s administrative settings) rather than a logged-in user session. For API integrations you will almost always set this to true.

Request Body

application/json

object

html

(optional) Raw HTML to seed the letter’s content. Omit to create a blank template instead.

string

esp

(optional, advanced) The sending integration to create the letter under, for companies with more than one connected ESP. Defaults to Letterhead’s own sending integration if omitted.

integer

Example

{}

Responses

201

Letter created

application/json

object

items

The new letter. Shown here are the fields most integrators use — the full letter object carries many more.

object

uniqueId

string

title

string

subtitle

string

publicationStatus

integer

channelSlug

string

nullable

channelName

string

nullable

createdAt

string

updatedAt

string

message

string

total

integer

Example

{
  "items": {
    "uniqueId": "p3nx8y2qka",
    "title": "",
    "subtitle": "",
    "publicationStatus": 3,
    "channelSlug": null,
    "channelName": null,
    "createdAt": "2026-08-31 09:12:00",
    "updatedAt": "2026-08-31 09:12:00"
  },
  "message": "Company letter created.",
  "total": 10
}

Still can’t find what you need? Contact support.