Skip to content
Letterhead Letterhead Letterhead Help Center
Admin Tools

Create a draft

POST
/api/v3/letters/actions/draft
 
curl --request POST \
  --url https://api.tryletterhead.com/api/v3/letters/actions/draft \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "api": true, "channel": "an-example-channel", "html": "<!DOCTYPE html><html><head><meta charset=\"UTF-8\"><title>Test</title></head><body><h1>Hello from Postman</h1><p>This is a test letter sent via the <strong>/api/v3/letters/actions/send</strong> endpoint.</p><p><a href=\"https://letterhead.co\">Visit Letterhead</a></p></body></html>", "segment": 0, "subject": "Who doesn'\''t love a good movie?", "subtitle": "A new exhibition, two openings, and a closer look at this season'\''s residency.", "tags": [ "an-excellent-tag" ], "suppress": [ "some-other-channel" ] }'

Creates a draft letter from the HTML you provide. This creates a letter in your channel that is ready to test, schedule, and send. Note that because you are providing your own HTML, you will not be able to edit this edition with our composer.

The response’s publicationStatus is always 7 for a letter created this way — the same status used for a letter that already has its content and audience set and is just waiting on a manual send. That’s expected, not an error: it’s a different status from 0, which is reserved for an empty, composer-editable draft (created through a separate, composer-internal flow this endpoint does not use) and isn’t a value this endpoint returns.

  • api: Boolean flag indicating the request is being made via the API.

  • channel: Channel slug to associate the draft with.

  • html: Full HTML content for the letter body.

  • segment: Segment identifier to target a subset of the channel audience; 0 applies to all subscribers.

  • subject: Draft subject/title.

  • suppress (optional): Array of channel slugs used to suppress recipients who are also subscribed to those channels.

  • subtitle (optional): Populates the email preview text shown in inbox previews after the subject, so the Letterhead UI only needs the send date filled in. Max 191 chars.

  • tags (optional): Newsletter tags applied to the created draft. Use this to label a send with your own internal identifier; tags are reused across sends and listed under GET /api/v3/letters/tags. Max 20 items, each ≤ 60 chars. Names are trimmed and deduped case-insensitively. Requires the newsletterTags flag on the company.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
api

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

boolean
channel

The channel you are targeting.

string
html

This endpoint is designed for you to use your own HTML.

string
segment

Identify a specific subset of your channel’s list. Pass 0 to send to every subscriber.

integer
subject
string
subtitle

(optional) Email preview text shown in inbox previews after the subject. Max 191 chars.

string
tags

(optional) Newsletter tags applied to the created letter. Max 20 items, each ≤ 60 chars. Names are trimmed and deduped case-insensitively.

Array<string>
suppress

(optional) An array of channel identifiers (slugs), to suppress sending to anyone on “an-example-channel” who is also subscribed to one or more of the channels passed here.

Array<string>
Example 
{
  "api": true,
  "channel": "an-example-channel",
  "html": "<!DOCTYPE html><html><head><meta charset=\"UTF-8\"><title>Test</title></head><body><h1>Hello from Postman</h1><p>This is a test letter sent via the <strong>/api/v3/letters/actions/send</strong> endpoint.</p><p><a href=\"https://letterhead.co\">Visit Letterhead</a></p></body></html>",
  "segment": 0,
  "subject": "Who doesn't love a good movie?",
  "subtitle": "A new exhibition, two openings, and a closer look at this season's residency.",
  "tags": [
    "an-excellent-tag"
  ],
  "suppress": [
    "some-other-channel"
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Create a draft

Media type application/json
object
items
object
createdAt
string
emailTemplate
string
insights
object
readability
object
ease
integer
seconds
integer
time
string
size
integer
wordCount
integer
publicationDate
string
publicationDateOffset
string
publicationDateTzCode
string
publicationStatus

Always 7 for this endpoint — content and audience are already set, awaiting a manual send. Not the same value as an empty composer draft, which uses 0.

integer
private
boolean
segmentId
integer
subtitle
string
title
string
updatedAt
string
uniqueId
string
useComposer
boolean
editor
string
message
string
total
integer
Example 
{
  "items": {
    "createdAt": "2026-05-06 12:24:09",
    "emailTemplate": "<!DOCTYPE html><html><head><meta charset=\"UTF-8\"><title>Test</title></head><body><h1>Hello from Postman</h1><p>This is a test letter sent via the <strong>/api/v3/letters/actions/send</strong> endpoint.</p><p><a href=\"https://letterhead.co\">Visit Letterhead</a></p></body></html>",
    "insights": {
      "readability": {
        "ease": 62,
        "seconds": 6,
        "time": "1 minute read"
      },
      "size": 0,
      "wordCount": 15
    },
    "publicationDate": "",
    "publicationDateOffset": "-08:00",
    "publicationDateTzCode": "America/Los_Angeles",
    "publicationStatus": 7,
    "private": true,
    "segmentId": 0,
    "subtitle": "",
    "title": "Who doesn't love a good movie?",
    "updatedAt": "2026-05-06 12:24:10",
    "uniqueId": "04c87gaemo",
    "useComposer": false,
    "editor": "html"
  },
  "message": "Html letter draft created.",
  "total": 1
}

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