Send a transactional email
const url = 'https://api.tryletterhead.com/api/v3/transactionals/actions/send';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"api":true,"channel":"an-example-channel","to":"[email protected]","toName":"Jane Doe","subject":"Your password reset link","html":"<!DOCTYPE html><html><body><h1>Reset your password</h1><p><a href=\"https://example.com/reset\">Reset now</a></p></body></html>","substitutionData":{"firstName":"Jane","resetUrl":"https://example.com/reset"},"tags":["password-reset"]}'};
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/transactionals/actions/send \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "api": true, "channel": "an-example-channel", "to": "[email protected]", "toName": "Jane Doe", "subject": "Your password reset link", "html": "<!DOCTYPE html><html><body><h1>Reset your password</h1><p><a href=\"https://example.com/reset\">Reset now</a></p></body></html>", "substitutionData": { "firstName": "Jane", "resetUrl": "https://example.com/reset" }, "tags": [ "password-reset" ] }'Sends a single, event-driven transactional email (password reset, receipt, welcome, etc.) through a channel for sender identity, tagged by transactional type for metric rollups.
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.
Rate limit: 120 sends per minute, per company. Exceeding the cap returns 429 Too Many Requests.
Behavior: Creates a private, tagged Letter and immediately queues the send. The Letter’s uniqueId is used as the SparkPost campaignId, so engagement events aggregate through the standard metrics pipeline while the Letter stays out of newsletter listings and metrics. If the recipient matches a known contact, their profile data enriches substitutionData — caller-supplied values win on key conflicts.
Success: 200 OK — items.uniqueId is the created Letter’s id (and the SparkPost campaignId); items.to echoes the recipient.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Required. Set to true to authenticate with an API key.
The channel you send through (used for sender identity). Channel slug.
The recipient’s email address.
(optional) The recipient’s display name. Max 191 chars.
The email subject. Max 191 chars; must contain a non-whitespace character.
The full HTML body of the email. Bring your own HTML.
(optional) Key/value merge data interpolated into the HTML at send time. Caller-supplied values take precedence over any contact-profile enrichment.
object
Transactional type tags, used for metric rollups. Required: 1-20 items, each 60 chars or fewer. Trimmed and de-duplicated case-insensitively.
Example
{ "api": true, "channel": "an-example-channel", "toName": "Jane Doe", "subject": "Your password reset link", "html": "<!DOCTYPE html><html><body><h1>Reset your password</h1><p><a href=\"https://example.com/reset\">Reset now</a></p></body></html>", "substitutionData": { "firstName": "Jane", "resetUrl": "https://example.com/reset" }, "tags": [ "password-reset" ]}Responses
Section titled “ Responses ”200 OK
object
object
Example
{ "items": { "uniqueId": "6cuswtvr7p", }, "message": "Your transactional email will be sent shortly.", "total": 0}Still can’t find what you need? Contact support.