ClickFunnels Emails::Settings API

openapi: 3.2.0
info:
  title: ClickFunnels Emails::Settings 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.


    ### For AI agents


    This document is the catalogue: every operation ClickFunnels exposes over REST is described here, with a unique operationId, typed schemas, and the scopes it needs. It is served from `/openapi.json`, `/openapi.yaml`, `/api/openapi.{json,yaml}`, and `/api/v2/openapi.{json,yaml}` on the accounts host.


    Three things it does not describe, each one request away:


    - MCP server: the app-native Model Context Protocol server (Streamable HTTP, OAuth 2.1 with PKCE). Prefer it over raw REST when your client supports MCP - it describes itself at runtime.

    - Skill guides, also as an Agent Skills index: one task guide per job (pages, blogs, products, orders, workflows, emails, courses, stats, external SDK pages). Read the guide that matches your job before your first write. llms.txt covers when to use ClickFunnels at all, how to get credentials, and how to behave around rate limits.

    - Protected resource metadata (RFC 9728) and authorization server metadata (RFC 8414): the scope vocabulary and the OAuth endpoints. Dynamic client registration is for MCP clients only.


    On ClickFunnels-owned API hosts (`myclickfunnels.com` and its subdomains), the OpenAPI specification responses and API authentication failures (401, or 403 for insufficient scope) carry those links in an RFC 8288 `Link` header, so clients can discover the documentation and authentication metadata from those responses. Requests sent through a customer''s custom domain keep the Bearer challenge but omit those discovery pointers.'
  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: []
- OAuth2: []
tags:
- name: Emails::Settings
  description: '> Email Settings


    Email Settings represent your workspace''s email configuration, including default from and reply-to addresses for system and marketing emails.


    See the Business mailing address prerequisite in the Emails Skill.'
paths:
  /workspaces/{workspace_id}/emails/settings:
    get:
      tags:
      - Emails::Settings
      summary: Get Email Settings
      description: 'Retrieve email settings for a workspace. A workspace that has never configured its email settings has no persisted record yet; this returns `200` with the empty settings shape (`address: null`, `address_complete: false`) rather than a `404`, signalling "not set up yet - PUT to configure".

        Check `address_complete` here before sending marketing email: see the Business mailing address prerequisite in the Emails Skill.'
      operationId: getEmailsSettings
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailsSettingsAttributes'
              example:
                workspace_id: 42000
                name: Acme Inc.
                hide_branding: false
                unsubscribe_footer: null
                footer_alignment: center
                address_single_line: false
                system_emails_from_address:
                  email_address: system@example.com
                  name: System Notifications
                system_emails_reply_to_address:
                  email_address: support@example.com
                  name: Support
                marketing_emails_from_address:
                  email_address: marketing@example.com
                  name: Marketing Team
                marketing_emails_reply_to_address: null
                address: null
                address_complete: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: API key missing or invalid
                hint: 'Send the token as `Authorization: Bearer <token>`. Create one under Account > Team > Platform Applications (a workspace API key), or obtain one with OAuth 2.1; both use the same scopes. See https://developers.myclickfunnels.com/docs/authentication, or append .md to that URL for markdown.'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: 'Not found: Record missing'
                hint: null
    put:
      tags:
      - Emails::Settings
      summary: Update Email Settings
      description: 'Update a workspace''s email/marketing settings. Most importantly, this sets the marketing (business) address, which is the workspace-wide prerequisite for creating broadcasts and workflow send-email steps, and for sending broadcasts. When an `address` is supplied it is validated for completeness, so a 422 here means marketing-email creation and sending remain blocked. A workspace that has never configured its email settings has no persisted record yet; the first PUT builds and persists it, so it succeeds rather than returning a `404`.

        See the Business mailing address prerequisite in the Emails Skill for the exact body to send.'
      operationId: updateEmailsSettings
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: Information about updated fields in the email settings
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                marketing_setting:
                  type: object
                  $ref: '#/components/schemas/EmailsSettingsParameters'
            example:
              marketing_setting:
                name: Acme Inc.
                address:
                  address_one: 123 Main St
                  city: San Francisco
                  postal_code: '94105'
                  country_code: US
                  region: CA
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailsSettingsAttributes'
              example:
                workspace_id: 42000
                name: Acme Inc.
                hide_branding: false
                unsubscribe_footer: null
                footer_alignment: center
                address_single_line: false
                system_emails_from_address:
                  email_address: system@example.com
                  name: System Notifications
                system_emails_reply_to_address:
                  email_address: support@example.com
                  name: Support
                marketing_emails_from_address:
                  email_address: marketing@example.com
                  name: Marketing Team
                marketing_emails_reply_to_address: null
                address:
                  address_one: 123 Main St
                  address_two: null
                  city: San Francisco
                  postal_code: '94105'
                  region_name: California
                  region: CA
                  country: US
                address_complete: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: API key missing or invalid
                hint: 'Send the token as `Authorization: Bearer <token>`. Create one under Account > Team > Platform Applications (a workspace API key), or obtain one with OAuth 2.1; both use the same scopes. See https://developers.myclickfunnels.com/docs/authentication, or append .md to that URL for markdown.'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: 'Not found: Record missing'
                hint: null
        '422':
          description: Unprocessable Entity. Returned when the supplied `address` is incomplete, when a sender/reply-to id does not belong to this workspace, or when `footer_alignment` is not one of `left`, `center`, `right`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  hint:
                    type:
                    - string
                    - 'null'
                    description: 'The next step for the caller: how to authenticate, which scope was missing, or where the route list lives. Always present, and null when this error has no next step to offer.'
              example:
                error: Address is incomplete
                hint: null
components:
  schemas:
    EmailsSettingsParameters:
      type: object
      title: Email Settings
      description: Email/marketing settings for a workspace
      required: []
      properties:
        name:
          type: string
          description: Business/sender name shown on email broadcasts
        address_single_line:
          type: boolean
          description: Render the marketing address on a single line
        hide_branding:
          type: boolean
          description: Hide ClickFunnels branding in the email footer
        unsubscribe_footer:
          type: string
          description: Custom unsubscribe footer text
        footer_alignment:
          type: string
          enum:
          - left
          - center
          - right
          description: Alignment of the email footer. Any other value is rejected with a 422.
        system_emails_from_address_id:
          type:
          - integer
          - 'null'
          description: An Emails::Address id used as the from address for system emails
        system_emails_reply_to_address_id:
          type:
          - integer
          - 'null'
          description: An Emails::Address id used as the reply-to address for system emails
        marketing_emails_from_address_id:
          type:
          - integer
          - 'null'
          description: An Emails::Address id used as the from address for marketing emails
        marketing_emails_reply_to_address_id:
          type:
          - integer
          - 'null'
          description: An Emails::Address id used as the reply-to address for marketing emails
        address:
          type: object
          description: The marketing (business) address. This workspace-wide prerequisite must be complete before creating a broadcast or workflow send-email step, and before sending a broadcast.
          properties:
            address_one:
              type: string
              description: Street address line one
            address_two:
              type:
              - string
              - 'null'
              description: Street address line two
            city:
              type: string
              description: City
            postal_code:
              type: string
              description: Postal/ZIP code
            country_code:
              type: string
              description: ISO 3166-1 alpha-2 country code, e.g. "US"
            region:
              type: string
              description: State/region by its code (e.g. "CA") or name
      example:
        marketing_setting:
          name: Acme Inc.
          address:
            address_one: 123 Main St
            city: San Francisco
            postal_code: '94105'
            country_code: US
            region: CA
    EmailsSettingsAttributes:
      type: object
      title: Email Settings
      description: Email Settings
      properties:
        workspace_id:
          type: integer
          description: Workspace ID
        name:
          type:
          - string
          - 'null'
          description: Business/sender name shown on email broadcasts
        hide_branding:
          type: boolean
          description: Whether ClickFunnels branding is hidden in the email footer
        unsubscribe_footer:
          type:
          - string
          - 'null'
          description: Custom unsubscribe footer text
        footer_alignment:
          type: string
          enum:
          - left
          - center
          - right
          description: Alignment of the email footer
        address_single_line:
          type: boolean
          description: Whether the marketing address renders on a single line
        system_emails_from_address:
          type:
          - object
          - 'null'
          properties:
            email_address:
              type: string
              description: Email address
            name:
              type:
              - string
              - 'null'
              description: Display name
          description: From address for system emails
        system_emails_reply_to_address:
          type:
          - object
          - 'null'
          properties:
            email_address:
              type: string
              description: Email address
            name:
              type:
              - string
              - 'null'
              description: Display name
          description: Reply-to address for system emails
        marketing_emails_from_address:
          type:
          - object
          - 'null'
          properties:
            email_address:
              type: string
              description: Email address
            name:
              type:
              - string
              - 'null'
              description: Display name
          description: From address for marketing emails
        marketing_emails_reply_to_address:
          type:
          - object
          - 'null'
          properties:
            email_address:
              type: string
              description: Email address
            name:
              type:
              - string
              - 'null'
              description: Display name
          description: Reply-to address for marketing emails
        address:
          type:
          - object
          - 'null'
          properties:
            address_one:
              type: string
              description: Street address line one
            address_two:
              type:
              - string
              - 'null'
              description: Street address line two
            city:
              type: string
              description: City
            postal_code:
              type: string
              description: Postal/ZIP code
            region_name:
              type:
              - string
              - 'null'
              description: State/region name
            region:
              type:
              - string
              - 'null'
              description: State/region code (e.g. "CA")
            country:
              type:
              - string
              - 'null'
              description: ISO 3166-1 alpha-2 country code (e.g. "US")
          description: The marketing (business) address used on email broadcasts
        address_complete:
          type: boolean
          description: True once the marketing address satisfies the email broadcast gate. See 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).
      example:
        workspace_id: 42000
        name: Acme Inc.
        hide_branding: false
        unsubscribe_footer: null
        footer_alignment: center
        address_single_line: false
        system_emails_from_address:
          email_address: system@example.com
          name: System Notifications
        system_emails_reply_to_address:
          email_address: support@example.com
          name: Support
        marketing_emails_from_address:
          email_address: marketing@example.com
          name: Marketing Team
        marketing_emails_reply_to_address: null
        address:
          address_one: 123 Main St
          address_two: null
          city: San Francisco
          postal_code: '94105'
          region_name: California
          region: CA
          country: US
        address_complete: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'A workspace API key or an OAuth access token, sent as `Authorization: Bearer <token>`.


        Both carry the same scope vocabulary as the `OAuth2` scheme below. Category-only

        scopes restrict access to the categories they name. Coarse wildcards remain additive:

        `read contacts:read` reads every category, while `write contacts:read` can write every

        category. Omit coarse scopes when restricting access to specific categories.

        Legacy tokens with only coarse scopes retain their existing unrestricted access;

        a bare `read` scope alone does not enforce read-only access.

        '
    OAuth2:
      type: oauth2
      description: 'OAuth 2.0 authorization code flow for REST integrations. Create a Platform Application

        and follow `https://developers.myclickfunnels.com/docs/oauth-20` to connect users.

        Authorization server metadata is published at

        `https://accounts.myclickfunnels.com/.well-known/oauth-authorization-server`.

        Dynamic client registration at `/oauth/register` is for MCP clients only; MCP-scoped

        tokens must use `https://agents.myclickfunnels.com/mcp`, not the REST API.


        Scopes are least-privilege by category. Ask for the two coarse wildcards (`read`,

        `write`) only when an integration genuinely needs the whole workspace; otherwise ask

        for the `<category>:read` / `<category>:write` pairs you use. `write` implies `read`

        for the same category. Protected resource metadata (RFC 9728) for this API lives at

        `https://accounts.myclickfunnels.com/.well-known/oauth-protected-resource`.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.myclickfunnels.com/oauth/authorize
          tokenUrl: https://accounts.myclickfunnels.com/oauth/token
          refreshUrl: https://accounts.myclickfunnels.com/oauth/token
          scopes:
            read: Read any resource in the granted workspaces
            write: Read and write any resource in the granted workspaces
            contacts:read: Read Contacts
            contacts:write: Read and write Contacts
            workflows:read: Read Workflows (Automations)
            workflows:write: Read and write Workflows (Automations)
            funnels:read: Read Funnels
            funnels:write: Read and write Funnels
            sites:read: Read Sites & Design
            sites:write: Read and write Sites & Design
            courses:read: Read Courses
            courses:write: Read and write Courses
            emails:read: Read Emails
            emails:write: Read and write Emails
            blog:read: Read Blog
            blog:write: Read and write Blog
            community:read: Read Community
            community:write: Read and write Community
            appointments:read: Read Appointments
            appointments:write: Read and write Appointments
            opportunities:read: Read Opportunities
            opportunities:write: Read and write Opportunities
            store:read: Read Store
            store:write: Read and write Store
            forms:read: Read Forms
            forms:write: Read and write Forms
            media:read: Read Media
            media:write: Read and write Media
            webhooks:read: Read Webhooks
            webhooks:write: Read and write Webhooks
            account:read: Read Account
            account:write: Read and write Account
            reference:read: Read Reference Data
            reference:write: Read and write Reference Data
externalDocs:
  description: More in-depth guides and further resources
  url: https://developers.myclickfunnels.com
x-provenance:
  method: harvested
  publisher: ClickFunnels
  source: https://accounts.myclickfunnels.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)