Create Message

post

https://{APP_DOMAIN}/api/3.2/messages

Creates and sends or schedules an email or SMS message. IMPORTANT for email: the content field on this endpoint is the source of truth — exactly that HTML (after server-side macro and link processing) is what subscribers receive. template_id is stored as metadata only; this endpoint does NOT re-render template + resource → HTML. You must build the final HTML on the client first. Typical email workflow: (1) Pick a content type, which determines message_type.name: Article → email-article, Lift Letter → email-promo (when promoted_publication_id is set) or email-renewal (when sending to a renewal cohort), Free Style → email-free-style. (2) Assemble content. For Article / Lift Letter, call GET /messages/contents/{resource_id} (retrieveMessageContent) with template_id, publication_id, message_type_id, plus promoted_publication_id / renewal_type as relevant — use the returned content, subject, and preview_line directly. For Free Style, fetch the template via GET /templates/{template_id} (retrieveTemplate), strip the {$sys_email.content} (or {$sys_email_content}) placeholder, write the body in its place, and use that as content. (3) POST here with the assembled content, plus template_id, subject, sender_id, reply_id, and either included_segment_ids (live) or emails (test). For SMS, provide messaging_service_id, content, and either included_segment_ids (live) or numbers (test). Use splits for A/B testing — each variant carries its own content, template_id, subject, sender_id, reply_id, and amount.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

message_type_id

integer

required

Numeric ID of the message type to send. Look up the ID via GET /messages/types — the name field there will be one of: 'email-free-style', 'email-article', 'email-renewal', 'email-promo', or 'sms-message'.

is_test

boolean

required

Whether the message is a test send. When true, emails (for email) or numbers (for SMS) must be provided instead of included/excluded segments.

send_at

string

A future date for a scheduled message. Eg. 1970-01-01T00:00:00-00:00

mail_type

string

The type of the message test or live

content

string

The fully assembled message body. For email this is final HTML; for SMS it is plain text (max 500 chars). For email this is the source of truth — exactly this content (after server-side macro raw-pass, video thumbnail replacement, link tracking, UTM injection, CSS inlining, and preview-line injection) is what subscribers receive. The create endpoint does NOT render template_id into HTML; you must build the HTML first. Recommended way to obtain it: call GET /messages/contents/{resource_id} (retrieveMessageContent) for article/lift-letter types and use the returned content, or fetch a template via GET /templates/{id} for email-free-style, strip the {$sys_email.content} (or {$sys_email_content}) placeholder, and write the body in its place. Required when splits is not provided. When splits are used, provide content inside each split entry instead.

template_id

integer

The ID of an email template (must exist in templates). Email messages only; required when splits is not provided. NOTE: this is persisted as metadata — the create endpoint does NOT re-render the template into content. The body sent to subscribers comes from the content field. Use this same template_id as a query param when calling GET /messages/contents/{resource_id} (article/lift-letter) or GET /templates/{id} (free-style) to build content before submitting.

numbers

array of strings

Array of recipient phone numbers in E.164 format (e.g. '+15555555555'). Required when is_test is true and the message type is SMS.

numbers

publication_id

integer

required

Publication ID the message belongs to

resource_id

integer

The ID of the Resource (article or lift letter) the message is built from. Required for email-article (Article — resource is an article), email-promo (Lift Letter — resource is a lift letter on the promoted publication), and email-renewal (Lift Letter — resource is a renewal lift letter). Optional and typically null for email-free-style, which has no associated resource.

publish_on_send

boolean

Whether to publish the associated Resource when the message is sent. Only applicable to resource-backed types (email-article / email-promo / email-renewal).

promoted_publication_id

integer

ID of the publication being promoted. Required for email-promo (a lift letter sent to one publication's audience promoting another publication's offer).

renewal_type

string

enum

The renewal cohort. Required for email-renewal. One of: 'active' or 'expired'.

Allowed:

campaign

object

Campaign / effort metadata for promo and renewal sends (e.g. campaign_id, partner_id, effort details). Used by the frontend's campaign-link generation step prior to submitting.

messaging_service_id

integer

ID of the messaging service to send through. Required for sms-message (must exist in messaging_services).

name

string

Optional display name for the message (used in lists/reporting).

binding_id

integer

The id of the binding on which to send the message.

included_segment_ids

array of integers

The segment IDs to send the message to. Required when is_test is false (live send).

included_segment_ids

excluded_segment_ids

array of integers

The segment IDs to exclude from the live send.

excluded_segment_ids

emails

array of strings

Array of email addresses to send a test to. Required when is_test is true and the message type is email.

emails

splits

array of objects

Optional A/B test splits. When provided, each split entry must include its own content/subject/sender/reply_id/resource_id and a numeric amount (or a shared sample_size at the top level).

splits

sample_size

integer

Total sample size across splits. Required when splits are provided without per-split amount values.

winning_metric

string

The metric used to pick the winning split (e.g. 'opens', 'clicks', 'revenue'). Required when splits are provided.

win_by_percentage

integer

Minimum lead percentage required to declare a winner. Required when splits are provided.

win_after

integer

Seconds to wait after the test sample completes before sending the winner to the remaining audience. Required when splits are provided and win_after_time is not set.

win_after_time

date-time

Absolute ISO 8601 timestamp to declare a winner. Alternative to win_after.

subject

string

The subject of the message being sent.

sender_id

integer

The id of the sender the message should come from.

reply_id

integer

The id of the reply-to sender for the message.

preview_line

string

The preview line that will be displayed in a message.

tag_ids

array of integers

Array of tag ids to associate with Message

tag_ids

Response

201The created Message