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