Mailchimp Surveys API

openapi: 3.2.0
info:
  version: 3.0.91
  title: Mailchimp Marketing Surveys API
  contact:
    name: Mailchimp API Support
    email: apihelp@mailchimp.com
  x-permalink: https://github.com/mailchimp/mailchimp-client-lib-codegen/blob/main/spec/marketing.json
servers:
- url: https://server.api.mailchimp.com/3.0
security:
- basicAuth: []
tags:
- name: Surveys
paths:
  /lists/{list_id}/surveys/{survey_id}/actions/publish:
    post:
      summary: Publish a Survey
      description: Publish a survey that is in draft, unpublished, or has been previously published and edited.
      parameters:
      - name: list_id
        x-title: List ID
        in: path
        description: The unique ID for the list.
        required: true
        schema:
          type: string
      - in: path
        name: survey_id
        x-title: Survey ID
        required: true
        description: The ID of the survey.
        schema:
          type: string
      responses:
        '200':
          description: Survey Published
        default:
          description: An error generated by the Mailchimp API.
          content:
            application/json:
              schema:
                type: object
                title: Problem Detail Document
                description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
                required:
                - type
                - title
                - status
                - detail
                - instance
                properties:
                  type:
                    type: string
                    title: Problem Type
                    description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                    example: https://mailchimp.com/developer/marketing/docs/errors/
                  title:
                    type: string
                    title: Error Title
                    description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                    example: Resource Not Found
                  status:
                    type: integer
                    title: HTTP Status Code
                    description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                    example: 404
                  detail:
                    type: string
                    title: Error Message
                    description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                    example: The requested resource could not be found.
                  instance:
                    type: string
                    title: Instance ID
                    description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                    example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
            application/problem+json:
              schema:
                type: object
                title: Problem Detail Document
                description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
                required:
                - type
                - title
                - status
                - detail
                - instance
                properties:
                  type:
                    type: string
                    title: Problem Type
                    description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                    example: https://mailchimp.com/developer/marketing/docs/errors/
                  title:
                    type: string
                    title: Error Title
                    description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                    example: Resource Not Found
                  status:
                    type: integer
                    title: HTTP Status Code
                    description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                    example: 404
                  detail:
                    type: string
                    title: Error Message
                    description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                    example: The requested resource could not be found.
                  instance:
                    type: string
                    title: Instance ID
                    description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                    example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Surveys
      x-custom-config:
        methodNameSnake: publish_survey
        methodNameCamel: publishSurvey
      operationId: postListsIdSurveysIdActionsPublish
  /lists/{list_id}/surveys/{survey_id}/actions/unpublish:
    post:
      summary: Unpublish a Survey
      description: Unpublish a survey that has been published.
      parameters:
      - name: list_id
        x-title: List ID
        in: path
        description: The unique ID for the list.
        required: true
        schema:
          type: string
      - in: path
        name: survey_id
        x-title: Survey ID
        required: true
        description: The ID of the survey.
        schema:
          type: string
      responses:
        '200':
          description: Survey Instance
        default:
          description: An error generated by the Mailchimp API.
          content:
            application/json:
              schema:
                type: object
                title: Problem Detail Document
                description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
                required:
                - type
                - title
                - status
                - detail
                - instance
                properties:
                  type:
                    type: string
                    title: Problem Type
                    description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                    example: https://mailchimp.com/developer/marketing/docs/errors/
                  title:
                    type: string
                    title: Error Title
                    description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                    example: Resource Not Found
                  status:
                    type: integer
                    title: HTTP Status Code
                    description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                    example: 404
                  detail:
                    type: string
                    title: Error Message
                    description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                    example: The requested resource could not be found.
                  instance:
                    type: string
                    title: Instance ID
                    description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                    example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
            application/problem+json:
              schema:
                type: object
                title: Problem Detail Document
                description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
                required:
                - type
                - title
                - status
                - detail
                - instance
                properties:
                  type:
                    type: string
                    title: Problem Type
                    description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                    example: https://mailchimp.com/developer/marketing/docs/errors/
                  title:
                    type: string
                    title: Error Title
                    description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                    example: Resource Not Found
                  status:
                    type: integer
                    title: HTTP Status Code
                    description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                    example: 404
                  detail:
                    type: string
                    title: Error Message
                    description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                    example: The requested resource could not be found.
                  instance:
                    type: string
                    title: Instance ID
                    description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                    example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Surveys
      x-custom-config:
        methodNameSnake: unpublish_survey
        methodNameCamel: unpublishSurvey
      operationId: postListsIdSurveysIdActionsUnpublish
  /lists/{list_id}/surveys/{survey_id}/actions/create-email:
    post:
      summary: Create a Survey Campaign
      description: Utilize the List ID and Survey ID to generate a Campaign that links to your survey.
      parameters:
      - name: list_id
        x-title: List ID
        in: path
        description: The unique ID for the list.
        required: true
        schema:
          type: string
      - in: path
        name: survey_id
        x-title: Survey ID
        required: true
        description: The ID of the survey.
        schema:
          type: string
      responses:
        '200':
          description: Campaign Instance
          content:
            application/json:
              schema:
                type: object
                title: Campaign
                description: A summary of an individual campaign's settings and content.
                required:
                - type
                properties:
                  id:
                    type: string
                    title: Campaign ID
                    description: A string that uniquely identifies this campaign.
                    readOnly: true
                  web_id:
                    type: integer
                    title: Campaign Web ID
                    description: The ID used in the Mailchimp web application. View this campaign in your Mailchimp account at `https://{dc}.admin.mailchimp.com/campaigns/show/?id={web_id}`.
                    readOnly: true
                  parent_campaign_id:
                    type: string
                    title: Parent Campaign ID
                    description: If this campaign is the child of another campaign, this identifies the parent campaign. For Example, for RSS or Automation children.
                    readOnly: true
                  type:
                    type: string
                    title: Campaign Type
                    description: There are four types of [campaigns](https://mailchimp.com/help/getting-started-with-campaigns/) you can create in Mailchimp. A/B Split campaigns have been deprecated and variate campaigns should be used instead.
                    enum:
                    - regular
                    - plaintext
                    - absplit
                    - rss
                    - variate
                  create_time:
                    type: string
                    format: date-time
                    title: Create Time
                    description: The date and time the campaign was created in ISO 8601 format.
                    readOnly: true
                  archive_url:
                    type: string
                    title: Archive URL
                    description: The link to the campaign's archive version.
                    readOnly: true
                  long_archive_url:
                    type: string
                    title: Long Archive URL
                    description: The original link to the campaign's archive version.
                    readOnly: true
                  status:
                    type: string
                    title: Campaign Status
                    description: The current status of the campaign.
                    enum:
                    - save
                    - paused
                    - schedule
                    - sending
                    - sent
                    - canceled
                    - canceling
                    - archived
                    readOnly: true
                  emails_sent:
                    type: integer
                    title: Emails Sent
                    description: The total number of emails sent for this campaign.
                    readOnly: true
                  send_time:
                    type: string
                    format: date-time
                    title: Send Time
                    description: The date and time a campaign was sent in ISO 8601 format.
                    readOnly: true
                  content_type:
                    type: string
                    title: Content Type
                    description: How the campaign's content is put together ('template', 'drag_and_drop', 'html', 'url').
                    readOnly: true
                  needs_block_refresh:
                    type: boolean
                    title: Needs Block Refresh
                    description: Determines if the campaign needs its blocks refreshed by opening the web-based campaign editor. Deprecated and will always return false.
                    readOnly: true
                  resendable:
                    type: boolean
                    title: Resendable
                    description: Determines if the campaign qualifies to be resent to non-openers.
                    readOnly: true
                  recipients:
                    type: object
                    title: List
                    description: List settings for the campaign.
                    required:
                    - list_id
                    properties:
                      list_id:
                        type: string
                        title: List ID
                        description: The unique list id.
                      list_name:
                        type: string
                        title: List Name
                        description: The name of the list.
                        readOnly: true
                      segment_text:
                        type: string
                        title: Segment Text
                        description: A description of the [segment](https://mailchimp.com/help/save-and-manage-segments/) used for the campaign. Formatted as a string marked up with HTML.
                        readOnly: true
                      recipient_count:
                        type: integer
                        title: Recipient Count
                        description: Count of the recipients on the associated list. Formatted as an integer.
                        readOnly: true
                      segment_opts:
                        type: object
                        title: Segment Options
                        description: An object representing all segmentation options. This object should contain a `saved_segment_id` to use an existing segment, or you can create a new segment by including both `match` and `conditions` options.
                        properties:
                          saved_segment_id:
                            type: integer
                            title: Saved Segment ID
                            description: The id for an existing saved segment.
                          prebuilt_segment_id:
                            type: string
                            title: Prebuilt Segment Id
                            description: The prebuilt segment id, if a prebuilt segment has been designated for this campaign.
                            example: subscribers-female
                          match:
                            type: string
                            title: Match Type
                            description: Segment match type.
                            enum:
                            - any
                            - all
                          conditions:
                            type: array
                            title: Segment Type
                            description: Segment match conditions. There are multiple possible types, see the [condition types documentation](https://mailchimp.com/developer/marketing/docs/alternative-schemas/#segment-condition-schemas).
                            items:
                              x-discriminator:
                                type: string
                                propertyName: condition_type
                              x-oneOf:
                              - type: object
                                title: Aim Segment
                                description: Segment by interaction with a specific campaign.
                                properties:
                                  condition_type:
                                    type: string
                                    x-value: Aim
                                    enum:
                                    - Aim
                                  field:
                                    type: string
                                    enum:
                                    - aim
                                    title: Segment Field
                                    description: Segment by interaction with a specific campaign.
                                    example: aim
                                  op:
                                    type: string
                                    enum:
                                    - open
                                    - click
                                    - sent
                                    - noopen
                                    - noclick
                                    - nosent
                                    title: Segment Operator
                                    description: 'The status of the member with regard to their campaign interaction. One of the following: opened, clicked, was sent, didn''t open, didn''t click, or was not sent.'
                                    example: open
                                  value:
                                    type: string
                                    title: Segment Data
                                    description: Either the web id value for a specific campaign or 'any' to account for subscribers who have/have not interacted with any campaigns.
                                    example: any
                              - type: object
                                title: Automation Segment
                                description: Segment by interaction with an Automation workflow.
                                required:
                                - field
                                - op
                                - value
                                properties:
                                  condition_type:
                                    type: string
                                    x-value: Automation
                                    enum:
                                    - Automation
                                  field:
                                    type: string
                                    enum:
                                    - automation
                                    title: Segment Field
                                    description: Segment by interaction with an Automation workflow.
                                    example: automation
                                  op:
                                    type: string
                                    enum:
                                    - started
                                    - completed
                                    - not_started
                                    - not_completed
                                    title: Segment Operator
                                    description: 'The status of the member with regard to the automation workflow. One of the following: has started the workflow, has completed the workflow, has not started the workflow, or has not completed the workflow.'
                                    example: started
                                  value:
                                    type: string
                                    title: Segment Data
                                    description: The web id for the automation workflow to segment against.
                                    example: '2135217'
                              - type: object
                                title: Poll Activity Segment
                                description: Segment by poll activity.
                                required:
                                - field
                                - op
                                - value
                                properties:
                                  condition_type:
                                    type: string
                                    x-value: CampaignPoll
                                    enum:
                                    - CampaignPoll
                                  field:
                                    type: string
                                    enum:
                                    - poll
                                    title: Segment Field
                                    description: Segment by poll activity.
                                    example: poll
                                  op:
                                    type: string
                                    enum:
                                    - member
                                    - notmember
                                    title: Segment Operator
                                    description: Members have/have not interacted with a specific poll in a Mailchimp email.
                                    example: member
                                  value:
                                    type: number
                                    title: Segment Operator
                                    description: The id for the poll.
                                    example: 409
                              - type: object
                                title: Conversation Segment
                                description: Segment by interaction with a campaign via Conversations.
                                required:
                                - field
                                - op
                                - value
                                properties:
                                  condition_type:
                                    type: string
                                    x-value: Conversation
                                    enum:
                                    - Conversation
                                  field:
                                    type: string
                                    enum:
                                    - conversation
                                    title: Segment Field
                                    description: Segment by interaction with a campaign via Conversations.
                                    example: conversation
                                  op:
                                    type: string
                                    enum:
                                    - member
                                    - notmember
                                    title: Segment Operator
                                    description: 'The status of a member''s interaction with a conversation. One of the following: has replied or has not replied.'
                                    example: member
                                  value:
                                    type: string
                                    title: Segment Data
                                    description: The web id value for a specific campaign or 'any' to account for subscribers who have/have not interacted with any campaigns.
                                    example: any
                              - type: object
                                title: Date Segment
                                description: Segment by a specific date field.
                                required:
                                - field
                                - op
                                - value
                                properties:
                                  condition_type:
                                    type: string
                                    x-value: Date
                                    enum:
                                    - Date
                                  field:
                                    type: string
                                    enum:
                                    - timestamp_opt
                                    - info_changed
                                    - ecomm_date
                                    title: Segment Field
                                    description: 'The type of date field to segment on: The opt-in time for a signup, the date the subscriber was last updated, or the date of their last ecomm purchase.'
                                    example: timestamp_opt
                                  op:
                                    type: string
                                    enum:
                                    - greater
                                    - less
                                    - is
                                    - not
                                    - blank
                                    - blank_not
                                    - within
                                    - notwithin
                                    title: Segment Operator
                                    description: 'When the event took place:  Before, after, is a specific date, is not a specific date, is blank, or is not blank.'
                                    example: greater
                                  value:
                                    type: string
                                    title: Segment Data
                                    description: 'What type of data to segment on: a specific date, a specific campaign, or the last campaign sent.'
                                    example: date
                                  extra:
                                    type: string
                                    title: Segment Extra Value
                                    description: When segmenting on 'date' or 'campaign', the date for the segment formatted as YYYY-MM-DD or the web id for the campaign.
                                    example: '2015-01-30'
                              - type: object
                                title: Email Client Segment
                                description: Segment by use of a particular email client.
                                required:
                                - field
                                - op
                                - value
                                properties:
                                  condition_type:
                                    type: string
                                    x-value: EmailClient
                                    enum:
                                    - EmailClient
                                  field:
                                    type: string
                                    enum:
                                    - email_client
                                    title: Segment Field
                                    description: Segment by use of a particular email client.
                                    example: email_client
                                  op:
                                    type: string
                                    enum:
                                    - client_is
                                    - client_not
                                    title: Segment Operator
                                    description: The operation to determine whether we select clients that match the value, or clients that do not match the value.
                                    example: client_is
                                  value:
                                    type: string
                                    title: Segment Data
                                    description: The name of the email client.
                                    example: Gmail
                              - type: object
                                title: Language Segment
                                description: Segment by language.
                                required:
                                - field
                                - op
                                - value
                                properties:
                                  condition_type:
                                    type: string
                                    x-value: Language
                                    enum:
                                    - Language
                                  field:
                                    type: string
                                    enum:
                                    - language
                                    title: Segment Field
                                    description: Segmenting based off of a subscriber's language.
                                    example: language
                                  op:
                                    type: string
                                    enum:
                                    - is
                                    - not
                                    title: Segment Operator
                                    description: Whether the member's language is or is not set to a specific language.
                                    example: is
                                  value:
                                    type: string
                                    title: Segment Data
                                    description: A two-letter language identifier.
                                    example: en
                              - type: object
                                title: Member Rating Segment
                                description: Segment by member rating.
                                required:
                                - field
                                - op
                                - value
                                properties:
                                  condition_type:
                            

# --- truncated at 32 KB (268 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mailchimp/refs/heads/main/openapi/mailchimp-surveys-api-openapi.yml