Skip to content
Letterhead Letterhead Letterhead Help Center
Admin Tools

Create a transactional email draft

POST
/api/v3/transactionals/actions/draft

Creates a transactional email draft (a private, tagged Letter) without sending it.

Authorization: Bearer token (company-level API key). The caller must be a company administrator for the channel’s owning company.

Feature flags: Requires both companyAudienceSending and transactionalEmail to be enabled.

Note: Recipient fields (to, toName, substitutionData) are ignored when drafting — only channel, subject, html, and tags are used. They may be sent (and are validated if present) but have no effect until the draft is sent.

Success: 201 Created — items.uniqueId is the created draft Letter’s id.

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”
Media type application/json
Examples
Example Create a transactional email draft 
{
    "api": true,
    /**
     * The channel you are drafting under (used for sender identity). Channel slug.
     */
    "channel": "an-example-channel",
    /**
     * The email subject. Max 191 chars; must contain a non-whitespace character.
     */
    "subject": "Your password reset link",
    /**
     * The full HTML body of the email. Bring your own HTML.
     */
    "html": "<!DOCTYPE html><html><body><h1>Reset your password</h1></body></html>",
    /**
     * Transactional type tags, used for metric rollups. Required: 1-20 items,
     * each 60 chars or fewer. Trimmed and de-duplicated case-insensitively.
     */
    "tags": ["password-reset"]
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

201 Created

Media type application/json
object
items
object
uniqueId
string
message
string
total
number
Examples
Example 201 Created 
{
  "items": {
    "uniqueId": "6cuswtvr7p"
  },
  "message": "Transactional email draft created.",
  "total": 0
}

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