ClickFunnels Emails::Broadcast API

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: <h1>Hello World</h1>
                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: <h1>Hello World</h1>
          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

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clickfunnels/refs/heads/main/openapi/clickfunnels-emails-broadcast-api-openapi.yml