AppConnect V3 — Contact Lists

naftiko: 1.0.0-alpha2
info:
  label: AppConnect V3 — Contact Lists
  description: 'AppConnect V3 — Contact Lists. 6 operations. Lead operation: GET Lists Collection. Self-contained Naftiko
    capability covering one Constant Contact business surface.'
  tags:
  - Constant Contact
  - Contact Lists
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    CONSTANT_CONTACT_API_KEY: CONSTANT_CONTACT_API_KEY
capability:
  consumes:
  - type: http
    namespace: v3-contact-lists
    baseUri: https://api.cc.email/v3
    description: AppConnect V3 — Contact Lists business capability. Self-contained, no shared references.
    resources:
    - name: contact_lists
      path: /contact_lists
      operations:
      - name: getlists
        method: GET
        description: GET Lists Collection
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: limit
          in: query
          type: integer
          description: Use to specify the number of results displayed per page of output, from 1 - 500, default = 50.
        - name: include_count
          in: query
          type: boolean
          description: Set `include_count` to `true` to return the total number of contact lists that meet your selection
            criteria.
        - name: include_membership_count
          in: query
          type: string
          description: Use to include the total number of contacts per list. Set to  `active`, to count only active (mailable)
            contacts, or `all` to count all contacts.
        - name: name
          in: query
          type: string
          description: Use to get details for a single list by entering the full name of the list.
        - name: status
          in: query
          type: string
          description: Use to get lists by status. Accepts comma-separated status values.
        - name: channel_type
          in: query
          type: string
          description: Use to return lists by channel type. The default value is `email`.
        - name: include_sms_membership_count
          in: query
          type: boolean
          description: Set to `true` to return the total number of SMS members in each list. Only applicable when `channel_type`
            is `sms`. Default is `false`.
      - name: createlist
        method: POST
        description: POST (create) a List
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: string
          description: JSON payload defining the new contact list
          required: true
    - name: contact_lists-list_id_xrefs
      path: /contact_lists/list_id_xrefs
      operations:
      - name: getlistidxrefs
        method: GET
        description: GET a collection of V2 and V3 API List IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: sequence_ids
          in: query
          type: string
          description: Comma delimited list of V2 API list `ids` to cross-reference with the V3 API `list_id` value. Endpoint
            accepts a maximum of 500 ids at a time.
          required: true
    - name: contact_lists-list_id
      path: /contact_lists/{list_id}
      operations:
      - name: getlist
        method: GET
        description: GET a List
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: list_id
          in: path
          type: string
          description: The system generated ID that uniquely identifies a contact list.
          required: true
        - name: include_membership_count
          in: query
          type: string
          description: 'Returns the total number of contacts per list that meet your selection criteria. Set the `include_membership_count`
            to `active`, to count only active contacts, '
      - name: putlist
        method: PUT
        description: PUT (update) a List
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: list_id
          in: path
          type: string
          description: Unique ID of the contact list to update
          required: true
        - name: JSON PUT body
          in: body
          type: string
          description: JSON payload containing updates to the specified contact list
          required: true
      - name: deletelistactivity
        method: DELETE
        description: DELETE a List
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: list_id
          in: path
          type: string
          description: Unique ID of the list to delete
          required: true
  exposes:
  - type: rest
    namespace: v3-contact-lists-rest
    port: 8080
    description: REST adapter for AppConnect V3 — Contact Lists. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/contact-lists
      name: contact-lists
      description: REST surface for contact_lists.
      operations:
      - method: GET
        name: getlists
        description: GET Lists Collection
        call: v3-contact-lists.getlists
        with:
          limit: rest.limit
          include_count: rest.include_count
          include_membership_count: rest.include_membership_count
          name: rest.name
          status: rest.status
          channel_type: rest.channel_type
          include_sms_membership_count: rest.include_sms_membership_count
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createlist
        description: POST (create) a List
        call: v3-contact-lists.createlist
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contact-lists/list-id-xrefs
      name: contact-lists-list-id-xrefs
      description: REST surface for contact_lists-list_id_xrefs.
      operations:
      - method: GET
        name: getlistidxrefs
        description: GET a collection of V2 and V3 API List IDs
        call: v3-contact-lists.getlistidxrefs
        with:
          sequence_ids: rest.sequence_ids
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contact-lists/{list-id}
      name: contact-lists-list-id
      description: REST surface for contact_lists-list_id.
      operations:
      - method: GET
        name: getlist
        description: GET a List
        call: v3-contact-lists.getlist
        with:
          list_id: rest.list_id
          include_membership_count: rest.include_membership_count
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: putlist
        description: PUT (update) a List
        call: v3-contact-lists.putlist
        with:
          list_id: rest.list_id
          JSON PUT body: rest.JSON PUT body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletelistactivity
        description: DELETE a List
        call: v3-contact-lists.deletelistactivity
        with:
          list_id: rest.list_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: v3-contact-lists-mcp
    port: 9090
    transport: http
    description: MCP adapter for AppConnect V3 — Contact Lists. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: get-lists-collection
      description: GET Lists Collection
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v3-contact-lists.getlists
      with:
        limit: tools.limit
        include_count: tools.include_count
        include_membership_count: tools.include_membership_count
        name: tools.name
        status: tools.status
        channel_type: tools.channel_type
        include_sms_membership_count: tools.include_sms_membership_count
      outputParameters:
      - type: object
        mapping: $.
    - name: post-create-list
      description: POST (create) a List
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: v3-contact-lists.createlist
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-collection-v2-and-v3
      description: GET a collection of V2 and V3 API List IDs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v3-contact-lists.getlistidxrefs
      with:
        sequence_ids: tools.sequence_ids
      outputParameters:
      - type: object
        mapping: $.
    - name: get-list
      description: GET a List
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v3-contact-lists.getlist
      with:
        list_id: tools.list_id
        include_membership_count: tools.include_membership_count
      outputParameters:
      - type: object
        mapping: $.
    - name: put-update-list
      description: PUT (update) a List
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: v3-contact-lists.putlist
      with:
        list_id: tools.list_id
        JSON PUT body: tools.JSON PUT body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-list
      description: DELETE a List
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: v3-contact-lists.deletelistactivity
      with:
        list_id: tools.list_id
      outputParameters:
      - type: object
        mapping: $.