All docsDeveloper settings

API

Emails API

Email documents, rendering, assets, and test sends.

A message document is the versioned, linted email: structured JSON content, subject, preheader, emailStyle, locale, and status.

Create: createMessageDocument, createMessageProposal, createMessageGeneration Read: getMessageDocument, getMessageContext, listMessageDocumentVersions, listMessageTemplates Revise: reviseMessageDocument, updateMessageDocument (title), translateMessageVariant, assistDraftMessage Preview / test: previewMessageDocument, previewDraftMessage, sendMessageTest Assets: uploadProjectAsset, listProjectAssets, listEmailIcons

Scope: write to draft. API-token requests that confirm a Journey proposal or publish a revision also require deliver; humans can confirm in the app or authorize their agent to do so in chat. Agents should leave status: "proposed" until that explicit approval. Confirmation publishes a version of the email; it is not a request to approve each recipient’s delivery.

Create a starter

POST with title / subject / locale and omit content to get a confirmed brand scaffold. If you supply a full body, default status is proposed unless you set it.

Subject is the inbox line (required). Title is internal (max 120). Preheader is required on revise (1–180 characters).

Revise

reviseMessageDocument sends subject, preheader, content, optional emailStyle and status (proposed | confirmed).

Read the document first and pass its revisionToken as message.expectedRevision, or as a quoted If-Match header. A missing precondition returns 428; a stale revision returns 409 with the current revision token and latest message ID. Read with latest=true to resolve the latest version, compare your changes, then retry against that version. Renaming with updateMessageDocument changes the lineage title only and does not use this content revision precondition.

Agent-authored Journey proposals validate the original document and return 422 with field pointers for invalid blocks, unsupported or unconfirmed merge tags, invalid image sources, or more than 24 top-level blocks. They do not silently discard or truncate blocks. Declared event properties are also checked for eligible event-triggered Journeys; see Event catalog.

Lint reports editorial findings such as placeholder destinations and malformed merge tags. Inspect these alongside validation errors before confirming; the shared marketing footer is composed separately from the authored body.

Idempotency-Key on generation and test send.

Copy into a Journey

copyMessageDocumentToJourney attaches a library email onto a node without silently forking unless you need an independent revision.

Templates, themes, sections

listMessageTemplates, listEmailThemes, pushEmailTheme, pushEmailStyles, listEmailSectionTemplates, pushEmailSectionTemplate. Push never mutates confirmed documents.

Preview

Saved previews and draft previews accept contactId and a dataVariables object. Draft previews can also take messageId to retain the saved email's Journey and system-email context. Conditions, merge tags and repeat blocks use this test context without saving it into the email or contact.

Inspect missingValues for visible values missing without a fallback and unresolvedVariables for merge tags still present after substitution. Use realistic event data even when a catalog declares the field: a declaration does not guarantee a runtime value. See Personalization.

Test send

sendMessageTest delivers one addressed copy. It is not a campaign and does not enroll. Still requires a verified identity for real ESP delivery. It accepts the same contactId and dataVariables preview context.

PreviousJourneys APINextCampaigns API