Concepts and System Objects

What Is a Formula?

A formula is the API’s internal representation of a message in Composer. Every message you see listed in the Composer UI corresponds to exactly one formula under the hood. When you open a message in Composer, browse its alternates, or trigger a send — you are interacting with a formula and the variants attached to it.

What a Formula Contains

A formula captures everything needed to describe a message:

Property	Description
`name`	The display name shown in the Composer UI
`message_type`	The channel — push, SMS, email, in-app, etc.
`status`	The current lifecycle state — Draft, Review, Approved, Live, etc.
`labels`	Tags that describe the formula’s overall intent and which component types they apply to
`topic_id`	The topic this message belongs to
`audience_id`	An optional segment filter controlling who can receive it
`send_start`	Optional delivery window start

The message structure and all actual copy live in the message-content record, which is a separate object automatically created alongside the formula.

Message-Content

Every formula has exactly one message-content record. This is where the structure (the slot layout) and all variants (the actual copy) live — not on the formula itself. The formula is the container: name, channel, status, targeting. The message-content is the payload: what the message looks like and what it says. When you create a formula, the API automatically creates a message-content record alongside it. You then set the structure and variants on that record directly.

Formula  →  created via POST /formulas
               └── message-content  →  auto-created, fetched via GET /formulas/{id}/message-contents
                     ├── structure  →  set via PUT /message-contents/{id}
                     └── variants   →  created via POST /variants or POST /variants/create/bulk

You’ll need the message-content ID for most content operations:

Endpoint	What it does
`GET /formulas/{id}/message-contents`	Returns the message-content ID
`PUT /message-contents/{id}`	Sets or replaces the structure and seed variants
`GET /message-contents/{id}`	Reads the current structure
`GET /message-contents/{id}/variants`	Lists all variants

Structure, Variants, Components, and Alternates

These four concepts work together to describe a message and all the ways it can be personalized.

Structure and Slots

The message-content’s structure defines the skeleton of the message — what slots exist (header, body, etc.) and what type of content each slot holds. It does not contain the message text itself. Each slot is one variant node in the structure. The node’s id is the component instance ID — a UUID you generate that identifies the slot and ties all its alternates together.

Variants

A variant is a single piece of message copy for a slot. It has a label, a text value, and a component_id pointing to the slot it belongs to. Every slot has at least one variant — the seed variant, which is set inline in the structure when you first define it.

Components

A component is a slot, identified by its component instance ID. In the Composer UI, a component appears as a single content block within a message that shows how many alternates it has. All variants sharing the same component_id belong to the same component.

Alternates

Alternates are the multiple variants grouped under a single component. If a header slot has three variants (Calm, Breathe, Stillness), those three are the alternates for that component. Aampe picks one alternate per component per send.

Formula
└── message-content
      ├── structure
      │     ├── slot: header  (component instance id = X)  ← seed text auto-creates first alternate
      │     └── slot: body    (component instance id = Y)
      └── variants
            ├── component_id = X, label = Calm       ← alternate 1 for header (seed)
            ├── component_id = X, label = Breathe    ← alternate 2 for header
            ├── component_id = X, label = Stillness  ← alternate 3 for header
            ├── component_id = Y, label = Science    ← alternate 1 for body (seed)
            └── component_id = Y, label = Sleep      ← alternate 2 for body

This formula produces 3 × 2 = 6 unique message combinations.

The Two Component IDs

There are two distinct IDs named “component ID” in the system. Confusing them is the most common source of errors:

Name	Type	Source	Used in
Component type ID	UUID	`GET /component-types` → `id`	`componentId` in structure nodes; identifies what kind of content a slot holds
Component instance ID	UUID	You generate with `uuid.uuid4()`	Variant node `id` in the structure; `component_id` when creating variants

The component type ID says what kind of slot this is (e.g. Offering, CallToAction). The component instance ID says which specific slot in this message a variant belongs to.

Formula Lifecycle

Draft → Review → Approved → Live / Scheduled / Expired
                     ↓
                 Archived

Only formulas in Approved or Live status are eligible for delivery. Formulas stay in Draft until explicitly submitted for review.

Content

Data Ingestion

Public Composer API

Concepts and System Objects

What Is a Formula?

What a Formula Contains

Message-Content

Structure, Variants, Components, and Alternates

Structure and Slots

Variants

Components

Alternates

The Two Component IDs

Formula Lifecycle

​What Is a Formula?

​What a Formula Contains

​Message-Content

​Structure, Variants, Components, and Alternates

​Structure and Slots

​Variants

​Components

​Alternates

​The Two Component IDs

​Formula Lifecycle

What Is a Formula?

What a Formula Contains

Message-Content

Structure, Variants, Components, and Alternates

Structure and Slots

Variants

Components

Alternates

The Two Component IDs

Formula Lifecycle