Schedule a letter

POST

/api/v3/letters/{letterUuid}/actions/schedule

curl --request POST \
  --url https://api.tryletterhead.com/api/v3/letters/example/actions/schedule \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "api": true, "channel": "an-example-channel", "segment": 0, "date": "2026-11-20T06:00:00" }'

• Production

Schedule an existing letter to go out at a time you choose, or as soon as possible if you leave date out. Create the letter first, for example with Create a draft, then schedule it here. Scheduling a letter that is already scheduled moves it to the new time.

date is read in the newsletter’s own timezone and must be at least a minute in the future.

If the letter is an active template, Letterhead copies it into a new edition and schedules the copy, leaving the template as it was. A letter that has already been sent can’t be scheduled.

Authorizations

• bearerAuth

Parameters

Path Parameters

letterUuid

required

string

The letter’s unique identifier — an alphanumeric string around ten characters, e.g. ludctamgd6.

Request Body ^required

Media type application/json

object

api

required

Required. Set to true to authenticate with an API key.

boolean

channel

required

The slug of the channel the letter belongs to.

string

segment

required

The integer identifier of your target segment, which is either all or a subset of your target channel.

integer

date

(optional) When to send, as YYYY-MM-DDTHH:MM:SS in the newsletter’s timezone. Leave it out to send as soon as possible.

string

subject

(optional) Override the letter’s subject line for this send.

string

Example

{
  "api": true,
  "channel": "an-example-channel",
  "segment": 0,
  "date": "2026-11-20T06:00:00"
}

Responses

200

The letter is scheduled

Media type application/json

object

items

object

uniqueId

The scheduled letter. For an active template, this is the new edition, not the template.

string

publicationDate

When the letter will be sent, in the newsletter’s timezone.

string

template

Present only when the letter you scheduled was an active template. The template’s identifier; uniqueId is then the new edition copied from it.

string

message

string

total

integer

Example

{
  "items": {
    "uniqueId": "ludctamgd6",
    "publicationDate": "2026-11-20 06:00:00"
  },
  "message": "Your letter will be sent at 2026-11-20 06:00:00.",
  "total": 0
}

400

The request is invalid, for example date is in the past or not in YYYY-MM-DDTHH:MM:SS form, the letter belongs to a different channel, or it has already been sent.

403

The key can’t schedule letters for this channel.