---
title: "Create Email Broadcast"
method: POST
path: "/workspaces/{workspace_id}/emails/broadcasts"
tags: ["Emails::Broadcast"]
---

# Create Email Broadcast

`POST /workspaces/{workspace_id}/emails/broadcasts`

Create a new email broadcast. Broadcasts are created in DRAFT status — creating one does not send it. 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.) When accessing the API through an OAuth connection from a third-party platform, this endpoint is restricted to trusted developer platforms. If you are using your own API key, you can send emails directly from your account. Prefer a verified sending address for from_email and reply_to_email: an unverified custom domain hurts deliverability, while the shared workspace-default domain is a safe fallback. List addresses (with their verification status) via GET /workspaces/{workspace_id}/emails/addresses.

## Path parameters

- `workspace_id` integer, required

## Request body

- object
  - `emails_broadcast` EmailsBroadcastParameters — Email Broadcasts
    - `name` string, required — Internal name for the broadcast (required)
    - `subject` string — Email subject line seen by recipients
    - `preheadline` string, nullable — Preview text shown in email clients before opening. Maximum 150 characters.
    - `from_email` string, required — Sender email address. Required on create. Must be an email address that belongs to the workspace. Prefer a verified sending address for best deliverability; the shared workspace-default domain is a safe fallback. See GET /workspaces/{workspace_id}/emails/addresses for verification status.
    - `reply_to_email` string, nullable — Reply-to email address. Must be an address in the workspace if provided. A verified sending address is preferred.
    - `html_body` string, nullable — HTML email body. If provided without a template_id, a template is automatically created from this content.
    - `text_body` string, nullable — Plain text email body
    - `template_id` integer, nullable — Numeric id of an existing email template in this workspace to use. Alternative to providing html_body/text_body directly; takes precedence when both are given. The broadcast references this template (it is not copied).
    - `filter_id` union — Contact filter for the broadcast audience. Accepts any of three forms: the numeric `id` or the public id (string) of a saved contact filter (`Refine::StoredFilter`) in this workspace, or a serialized contact filter. The supplied filter is copied onto the broadcast — the broadcast points at its own copy, so later edits to (or deletion of) the saved filter never change this broadcast's audience. Saved contact filters can be created/listed via the [Refine Filters Skill](https://accounts.myclickfunnels.com/.well-known/refine-filters/skill.md). If `recipients` are provided instead, a filter is created automatically from them and takes precedence over `filter_id`. See [Applying filters to email broadcasts](https://accounts.myclickfunnels.com/.well-known/refine-filters/skill.md#applying-filters-to-email-broadcasts).
      - string
      - integer
    - `send_immediately` boolean — Set to true to send the broadcast immediately upon creation. If false, use send_at, send_at_local_time, and time_zone to schedule.
    - `send_at` string, nullable — Scheduled send date. Required when send_immediately is false.
    - `send_at_local_time` string, nullable — Scheduled send time in HH:MM:SS format. Defaults to 18:00:00.
    - `time_zone` string, nullable — Time zone for scheduling (defaults to workspace time zone)
    - `external_id` string, nullable — An optional external identifier for your own tracking
    - `topic_ids` integer[] — Topic IDs to associate. Only topics belonging to the workspace are accepted.
    - `recipients` object[] — List of recipients (maximum 1,000). Contacts are created or matched by email address.
      - `email` string, required — Recipient email address (required)
      - `first_name` string, nullable — Recipient first name
      - `last_name` string, nullable — Recipient last name

## Response `201`

Created

- EmailsBroadcastAttributes — Email Broadcasts
  - `id` integer — Broadcast ID
  - `public_id` string, nullable — Broadcast public ID
  - `workspace_id` integer — Workspace ID
  - `name` string, nullable — Internal name for the broadcast
  - `subject` string, nullable — Email subject line seen by recipients
  - `preheadline` string, 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_type` string, nullable — The type of origination channel that created this broadcast
  - `origination_channel_id` integer, nullable — The ID of the origination channel
  - `external_id` string, nullable — An optional external identifier for tracking purposes
  - `filter_id` integer, 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](https://accounts.myclickfunnels.com/.well-known/refine-filters/skill.md#applying-filters-to-email-broadcasts).
  - `send_at` string, nullable — Scheduled send date
  - `send_at_local_time` string, nullable — Scheduled send time in HH:MM:SS format, relative to the specified time zone
  - `time_zone` string, nullable — Time zone for scheduled sending
  - `send_immediately` boolean — Whether the broadcast sends immediately upon creation
  - `sending_at` string, date-time, nullable — Timestamp when sending actually began
  - `complete_at` string, date-time, nullable — Timestamp when sending completed
  - `from_email` string, nullable — The sender email address
  - `from_name` string, nullable — The sender display name associated with the from address
  - `reply_to_email` string, nullable — The reply-to email address
  - `template` object, nullable — A lean reference to the email template this broadcast uses (a broadcast points at a template; it does not copy it, unlike a workflow send-email step). Null when no template is attached. The template's rendered body is not inlined here — fetch it from the templates endpoint via this public_id: GET /api/v2/emails/templates/{public_id}?expand[]=html_body.
    - `id` integer — Template ID
    - `public_id` string — Template public ID
    - `name` string, nullable — Template name
  - `topic_ids` integer[] — IDs of topics associated with this broadcast
  - `created_at` string, date-time, nullable — Created at datetime
  - `updated_at` string, date-time, nullable — Updated at datetime

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/myclickfunnels/apis/clickfunnels-api.md) · [All operations](https://skmtc.net/myclickfunnels/apis/clickfunnels-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/myclickfunnels/clickfunnels-api/revisions/ae6313eaa176/schema)