openapi: 3.2.0
info:
title: ClickFunnels Emails::Broadcast API
termsOfService: https://www.clickfunnels.com/terms-of-service
contact:
name: ClickFunnels API Team
url: https://developers.myclickfunnels.com
x-logo:
url: https://statics.myclickfunnels.com/image/1126065/file/31edf05760fafe41a82f16a668ab251f.png
description: 'The ClickFunnels REST API that powers webhooks, native integrations, and Zapier lets you manage your ClickFunnels data, automate your workflows, and recreate ClickFunnels functionality in your own apps.
'
license:
name: MIT
url: https://opensource.org/licenses/MIT
version: 2.0.0
servers:
- url: https://{subdomain}.myclickfunnels.com/api/v2
description: ClickFunnels API
variables:
subdomain:
default: myworkspace
security:
- BearerAuth: []
tags:
- name: Emails::Broadcast
description: '> Email Broadcasts
Email Broadcasts allow you to send one-time email campaigns to your contacts. Broadcasts are created in draft status and can be sent immediately or scheduled for later delivery.
To target a broadcast''s audience, set `filter_id` to a contact filter. You can pass the numeric id or the public id of a saved contact filter (a RefineFilter created via the [Refine Filters Skill](https://accounts.myclickfunnels.com/.well-known/refine-filters/skill.md)), or a serialized contact filter. The supplied filter is copied onto the broadcast, so editing or deleting the saved filter afterward never changes an existing broadcast''s audience. See [Applying filters to email broadcasts](https://accounts.myclickfunnels.com/.well-known/refine-filters/skill.md#applying-filters-to-email-broadcasts) for the full flow.
See [Broadcasts](https://accounts.myclickfunnels.com/.well-known/emails/skill.md#broadcasts) in the [Emails Skill](https://accounts.myclickfunnels.com/.well-known/emails/skill.md).
'
paths:
/workspaces/{workspace_id}/emails/broadcasts:
get:
tags:
- Emails::Broadcast
summary: List Email Broadcasts
description: List all email broadcasts for a workspace. Filterable by id and status.
operationId: listEmailsBroadcasts
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/sort_order'
- $ref: '#/components/parameters/sort_property'
- name: filter
in: query
description: 'Filter by available properties in query params, like this: `api/v2/resources?filter[id]=value&filter[another_property]=value1,value2`. Check our Filtering guide for examples and all about filtering [here](https://developers.myclickfunnels.com/docs/filtering).
'
required: false
schema:
type: object
properties:
id:
type: string
description: A comma-separated list of broadcast IDs to filter by.
example: 1,42
status:
type: string
description: A comma-separated list of statuses to filter by (draft, scheduled, sending, paused, unhealthy, complete, canceled).
example: draft,scheduled
style: deepObject
explode: true
responses:
'200':
description: OK
headers:
Pagination-Next:
$ref: '#/components/headers/PaginationNext'
Link:
$ref: '#/components/headers/Link'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EmailsBroadcastAttributes'
example:
- 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
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
created_at: '2025-01-01T00:00:00.000Z'
updated_at: '2025-01-01T00:00:00.000Z'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: API key missing or invalid
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Not found: Record missing'
post:
tags:
- Emails::Broadcast
summary: Create Email Broadcast
description: '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.) 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. 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. 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](https://accounts.myclickfunnels.com/.well-known/emails/skill.md#broadcasts) and the [Business mailing address prerequisite](https://accounts.myclickfunnels.com/.well-known/emails/skill.md#business-mailing-address-prerequisite) in the [Emails Skill](https://accounts.myclickfunnels.com/.well-known/emails/skill.md).'
operationId: createEmailsBroadcast
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
requestBody:
description: Information about a new Email Broadcast
required: true
content:
application/json:
schema:
type: object
properties:
emails_broadcast:
type: object
$ref: '#/components/schemas/EmailsBroadcastParameters'
example:
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:
Hello World
text_body: Hello World
send_immediately: 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
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/EmailsBroadcastAttributes'
example:
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
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
created_at: '2025-01-01T00:00:00.000Z'
updated_at: '2025-01-01T00:00:00.000Z'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Bad request: HTTP body must be valid JSON'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: API key missing or invalid
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Forbidden: This endpoint is restricted to trusted developer platforms. Apply for trusted platform access at https://developers.myclickfunnels.com or contact support.'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Request unprocessable: A complete business mailing address is required to create marketing emails. Set it first via the email settings endpoint (GET/PUT /api/v2/workspaces/:workspace_id/emails/settings), providing a name and address, then try again.'
/emails/broadcasts/{id}:
get:
tags:
- Emails::Broadcast
summary: Fetch Email Broadcast
description: Retrieve a single email broadcast by ID
operationId: getEmailsBroadcast
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailsBroadcastAttributes'
example:
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
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
created_at: '2025-01-01T00:00:00.000Z'
updated_at: '2025-01-01T00:00:00.000Z'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: API key missing or invalid
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Forbidden: This endpoint is restricted to trusted developer platforms. Apply for trusted platform access at https://developers.myclickfunnels.com or contact support.'
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Not found: Record missing'
patch:
tags:
- Emails::Broadcast
summary: Update Email Broadcast
description: Update an email broadcast. Only broadcasts in draft status can be updated. 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. See [Broadcasts](https://accounts.myclickfunnels.com/.well-known/emails/skill.md#broadcasts) in the [Emails Skill](https://accounts.myclickfunnels.com/.well-known/emails/skill.md).
operationId: updateEmailsBroadcast
parameters:
- $ref: '#/components/parameters/id'
requestBody:
description: Information about updated fields in Email Broadcast
required: true
content:
application/json:
schema:
type: object
properties:
emails_broadcast:
type: object
$ref: '#/components/schemas/EmailsBroadcastParametersUpdate'
example:
emails_broadcast:
name: Updated Newsletter
subject: Updated Subject
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailsBroadcastAttributes'
example:
id: 1
public_id: GhIjKl
workspace_id: 42000
name: Updated Newsletter
subject: Updated Subject
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
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
created_at: '2025-01-01T00:00:00.000Z'
updated_at: '2025-01-01T00:00:00.000Z'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Bad request: HTTP body must be valid JSON'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: API key missing or invalid
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Not found: Record missing'
delete:
tags:
- Emails::Broadcast
summary: Delete Email Broadcast
description: Delete an email broadcast. Only broadcasts in draft status can be deleted. 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.
operationId: removeEmailsBroadcast
parameters:
- $ref: '#/components/parameters/id'
responses:
'204':
description: No Content
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: API key missing or invalid
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Forbidden: This endpoint is restricted to trusted developer platforms. Apply for trusted platform access at https://developers.myclickfunnels.com or contact support.'
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: 'Not found: Record missing'
components:
schemas:
EmailsBroadcastParametersUpdate:
type: object
title: Email Broadcasts
description: Email Broadcasts. Only draft broadcasts can be updated.
required: []
properties:
name:
type: string
description: Internal name for the broadcast
subject:
type: string
description: Email subject line seen by recipients
preheadline:
type:
- string
- 'null'
description: Preview text shown in email clients before opening. Maximum 150 characters.
from_email:
type: string
description: Sender email address. Must be a verified email address that belongs to the workspace.
reply_to_email:
type:
- string
- 'null'
description: Reply-to email address. Must be a verified address in the workspace if provided.
html_body:
type:
- string
- 'null'
description: HTML email body
text_body:
type:
- string
- 'null'
description: Plain text email body
template_id:
type:
- integer
- 'null'
description: Numeric id of an existing email template in this workspace to point this draft broadcast at (swaps the referenced template). Takes precedence over an inline html_body/text_body. Only draft broadcasts can be updated; an unknown id returns 422.
filter_id:
type:
- string
- integer
- 'null'
description: '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). See [Applying filters to email broadcasts](https://accounts.myclickfunnels.com/.well-known/refine-filters/skill.md#applying-filters-to-email-broadcasts).
'
send_at:
type:
- string
- 'null'
description: Scheduled send date
send_at_local_time:
type:
- string
- 'null'
description: Scheduled send time in HH:MM:SS format
time_zone:
type:
- string
- 'null'
description: Time zone for scheduling
external_id:
type:
- string
- 'null'
description: An optional external identifier for your own tracking
topic_ids:
type: array
items:
type: integer
description: Topic IDs to associate
example:
emails_broadcast:
name: Updated Newsletter
subject: Updated Subject
EmailsBroadcastParameters:
type: object
title: Email Broadcasts
description: Email Broadcasts
required:
- name
- from_email
properties:
name:
type: string
description: Internal name for the broadcast (required)
subject:
type: string
description: Email subject line seen by recipients
preheadline:
type:
- string
- 'null'
description: Preview text shown in email clients before opening. Maximum 150 characters.
from_email:
type: string
description: 'Sender email address. Required on create. Must be an email address that belongs to the workspace, and it must have `usable_as_sender: true` or the send is rejected with 422. Do not pick by the sending domain''s `verified` flag: that covers email transport only. See GET /workspaces/{workspace_id}/emails/addresses, where a shared workspace-default address is usable only while the workspace has no ready custom sender.'
reply_to_email:
type:
- string
- 'null'
description: Reply-to email address. Must be an address in the workspace if provided. Pick one whose `usable_as_sender` is `true`.
html_body:
type:
- string
- 'null'
description: HTML email body. If provided without a template_id, a template is automatically created from this content.
text_body:
type:
- string
- 'null'
description: Plain text email body
template_id:
type:
- integer
- 'null'
description: 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:
type:
- string
- integer
- 'null'
description: '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).
'
send_immediately:
type: boolean
description: 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:
type:
- string
- 'null'
description: Scheduled send date. Required when send_immediately is false.
send_at_local_time:
type:
- string
- 'null'
description: Scheduled send time in HH:MM:SS format. Defaults to 18:00:00.
time_zone:
type:
- string
- 'null'
description: Time zone for scheduling (defaults to workspace time zone)
external_id:
type:
- string
- 'null'
description: An optional external identifier for your own tracking
topic_ids:
type: array
items:
type: integer
description: Topic IDs to associate. Only topics belonging to the workspace are accepted.
recipients:
type: array
items:
type: object
required:
- email
properties:
email:
type: string
description: Recipient email address (required)
first_name:
type:
- string
- 'null'
description: Recipient first name
last_name:
type:
- string
- 'null'
description: Recipient last name
description: List of recipients (maximum 1,000). Contacts are created or matched by email address.
example:
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: Hello World
text_body: Hello World
send_immediately: 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
EmailsBroadcastAttributes:
type: object
title: Email Broadcasts
description: Email Broadcasts
properties:
id:
type: integer
description: Broadcast ID
public_id:
type:
- string
- 'null'
description: Broadcast public ID
workspace_id:
type: integer
description: Workspace ID
name:
type:
- string
- 'null'
description: Internal name for the broadcast
subject:
type:
- string
- 'null'
description: Email subject line seen by recipients
preheadline:
type:
- string
- 'null'
description: Preview text shown in email clients before opening (max 150 characters)
status:
type: string
enum:
- draft
- scheduled
- sending
- paused
- unhealthy
- complete
- canceled
description: Current broadcast status. New broadcasts start as draft.
origination_channel_type:
type:
- string
- 'null'
description: The type of origination channel that created this broadcast
origination_channel_id:
type:
- integer
- 'null'
description: The ID of the origination channel
external_id:
type:
- string
- 'null'
description: An optional external identifier for tracking purposes
filter_id:
type:
- integer
- 'null'
description: '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:
type:
- string
- 'null'
description: Scheduled send date
send_at_local_time:
type:
- string
- 'null'
description: Scheduled send time in HH:MM:SS format, relative to the specified time zone
time_zone:
type:
- string
- 'null'
description: Time zone for scheduled sending
send_immediately:
type: boolean
description: Whether the broadcast sends immediately upon creation
sending_at:
type:
- string
- 'null'
format: date-time
description: Timestamp when sending actually began
complete_at:
type:
- string
- 'null'
format: date-time
description: Timestamp when sending completed
from_email:
type:
- string
- 'null'
description: The sender email address
from_name:
type:
- string
- 'null'
description: The sender display name associated with the from address
reply_to_email:
type:
- string
- 'null'
description: The reply-to email address
template:
type:
- object
- 'null'
description: '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.'
properties:
id:
type: integer
description: Template ID
public_id:
type: string
description: Template public ID
name:
type:
- string
- 'null'
description: Template name
topic_ids:
type: array
items:
type: integer
description: IDs of topics associated with this broadcast
created_at:
type:
- string
- 'null'
format: date-time
description: Created at datetime
updated_at:
type:
- string
- 'null'
format: date-time
description: Updated at datetime
example:
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
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
created_at: '2025-01-01T00:00:00.000Z'
updated_at: '2025-01-01T00:00:00.000Z'
required:
- complete_at
- created_at
- external_id
- filter_id
- from_email
- from_name
- id
- name
- origination_channel_id
- origination_channel_type
- preheadline
- public_id
- reply_to_email
- send_at
- send_at_local_time
- send_immediately
- sending_at
- status
- subject
- template
- time_zone
- topic_ids
- updated_at
- workspace_id
parameters:
id:
name: id
in: path
required: true
schema:
type: string
sort_property:
name: sort_property
in: query
description: 'Sort property of a list response. The default is id and thus the created_at order.
If you sort by other properties, we additionally sort by id implicitly as a secondary sort property, so that you can rely on the sort order to be deterministic even if the main sort property ends up with the same values.
'
required: false
schema:
type: string
enum:
- id
- updated_at
sort_order:
name: sort_order
in: query
description: Sort order of a list response. Use 'desc' to reverse the default 'asc' (ascending) sort order. Examples [in our guides](https://developers.myclickfunnels.com/docs/pagination).
required: false
schema:
type: string
enum:
- asc
- desc
after:
name: after
in: query
required: false
schema:
type: string
description: ID of item after which the collection should be returned. More examples and info about pagination [in our guides](https://developers.myclickfunnels.com/docs/pagination).
headers:
Link:
description: A direct link to the next page for the cursor-based pagination. It includes the `after` and the Pagination-Next ID value.
schema:
type: string
PaginationNext:
description: ID of the last item in the current response after which more records exist. You can use it in an `after` query parameter for cursor-based pagination to get to the next page.
schema:
type: string
securitySchemes:
BearerAuth:
type: http
scheme: bearer
externalDocs:
description: More in-depth guides and further resources
url: https://developers.myclickfunnels.com