MYmyclickfunnels
Emails::Broadcast

Create Email Broadcast

Changed on

Create a new email broadcast. Broadcasts are created in DRAFT status — creating one does not send it. The top-level subject/preheadline are split-test variant A; pass one alternate in variants and set split_test true to configure variant B. To send it, create a send action for the broadcast (POST /emails/broadcasts/{broadcast_id}/send_actions): omit send_at to send now, or pass a future send_at to schedule. (Alternatively, the legacy inline path accepts recipients with send_immediately=true, or send_at/send_at_local_time/time_zone to schedule.) A complete business mailing address is required even when creating a draft. Configure it first with PUT /workspaces/{workspace_id}/emails/settings; an incomplete address returns 422. Pick from_email and reply_to_email from addresses whose top-level usable_as_sender is true, not from the sending domain's verified flag: verified covers email transport only, and sending a broadcast from an address that is not usable is rejected with 422. List addresses via GET /workspaces/{workspace_id}/emails/addresses. See Broadcasts and the Business mailing address prerequisite in the Emails Skill.

post/workspaces/{workspace_id}/emails/broadcasts

Request

Path parameters

workspace_idstring required

Request body

Example request

{
  "emails_broadcast": {
    "name": "Weekly Newsletter",
    "subject": "This Week's Updates",
    "preheadline": "Check out what's new",
    "from_email": "marketing@example.com",
    "reply_to_email": "replies@example.com",
    "html_body": "<h1>Hello World</h1>",
    "text_body": "Hello World",
    "send_immediately": false,
    "split_test": true,
    "split_test_percentage": 20,
    "split_test_wait_time": 4,
    "variants": [
      {
        "subject": "Don't miss this week's updates",
        "preheadline": "See what's new"
      }
    ],
    "smart_sending": false,
    "send_at": "2025-06-01",
    "send_at_local_time": "18:00:00",
    "time_zone": "Pacific Time (US & Canada)",
    "topic_ids": [
      1,
      2
    ],
    "recipients": [
      {
        "email": "user@example.com",
        "first_name": "Jane",
        "last_name": "Doe"
      }
    ]
  }
}

Response

Created

idinteger

Broadcast ID

public_idstring nullable

Broadcast public ID

workspace_idinteger

Workspace ID

namestring nullable

Internal name for the broadcast

subjectstring nullable

Email subject line seen by recipients

preheadlinestring nullable

Preview text shown in email clients before opening (max 150 characters)

status'draft' | 'scheduled' | 'sending' | 'paused' | 'unhealthy' | 'complete' | 'canceled'

Current broadcast status. New broadcasts start as draft.

origination_channel_typestring nullable

The type of origination channel that created this broadcast

origination_channel_idinteger nullable

The ID of the origination channel

external_idstring nullable

An optional external identifier for tracking purposes

filter_idinteger nullable

The contact filter determining which contacts receive this broadcast. Numeric Refine::StoredFilter id (not the public id) — the broadcast's own unnamed copy of the filter, created automatically from the filter_id (or recipients) supplied on create/update. null until an audience is set. See Applying filters to email broadcasts.

send_atstring nullable

Scheduled send date

send_at_local_timestring nullable

Scheduled send time in HH:MM:SS format, relative to the specified time zone

time_zonestring nullable

Time zone for scheduled sending

send_immediatelyboolean

Whether the broadcast sends immediately upon creation

smart_sendingboolean

Whether Smart Sending is on. When on, the broadcast is delivered gradually across a window instead of all at once, which protects deliverability. Defaults to true, so a broadcast batches unless you explicitly send smart_sending: false. Above 5,000 recipients Smart Sending is mandatory: the API may coerce false to true, and the send batches at that size regardless of the stored value.

smart_sending_timenumber nullable

How many smart_sending_units the delivery window spans. null means no override is stored and the window is sized from the audience instead.

smart_sending_unit'hour' | 'day' | 'null' nullable

The unit of the Smart Sending delivery window. null means no override is stored and the window is sized from the audience instead.

sending_atstring date-time nullable

Timestamp when sending actually began

complete_atstring date-time nullable

Timestamp when sending completed

from_emailstring nullable

The sender email address

from_namestring nullable

The sender display name associated with the from address

reply_to_emailstring nullable

The reply-to email address

topic_idsinteger[]

IDs of topics associated with this broadcast

split_testboolean

Whether this broadcast is a subject-line split test. When true, a split_test_percentage share of the audience is split evenly across the variants; after split_test_wait_time hours the variant with the most opens wins and the rest of the audience receives it.

split_test_percentageinteger nullable

Share of the audience (0-100) used for the test sends. This can remain populated while a configured test is disabled, and is null when no percentage has been configured.

split_test_wait_timeinteger nullable

Hours to wait after the test sends before the winner is picked. This can remain populated while a configured test is disabled, and is null when no wait time has been configured.

created_atstring date-time nullable

Created at datetime

updated_atstring date-time nullable

Updated at datetime

Example response

{
  "id": 1,
  "public_id": "GhIjKl",
  "workspace_id": 42000,
  "name": "Weekly Newsletter",
  "subject": "This Week's Updates",
  "preheadline": "Check out what's new",
  "status": "draft",
  "origination_channel_type": null,
  "origination_channel_id": null,
  "external_id": null,
  "filter_id": null,
  "send_at": null,
  "send_at_local_time": null,
  "time_zone": "Pacific Time (US & Canada)",
  "send_immediately": false,
  "smart_sending": true,
  "smart_sending_time": 0.5,
  "smart_sending_unit": "hour",
  "sending_at": null,
  "complete_at": null,
  "from_email": "marketing@example.com",
  "from_name": "Marketing Team",
  "reply_to_email": null,
  "template": {
    "id": 3001,
    "public_id": "TmPl01",
    "name": "Weekly Newsletter Template"
  },
  "topic_ids": [
    1,
    2
  ],
  "split_test": false,
  "split_test_percentage": null,
  "split_test_wait_time": null,
  "variants": [
    {
      "subject": "This Week's Updates",
      "preheadline": "Check out what's new",
      "send_percentage": 100,
      "main": true,
      "open_count": 0,
      "winner": null
    }
  ],
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-01T00:00:00.000Z"
}

Changes

  • 511d88b30aeaRevision changes
    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      for the path request parameter workspace_id, the type was generalized from integer to string

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status