# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Stannp Direct Mail Groups API
  version: 1.0.0
extends: openapi/stannp-groups-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/groups/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List recipient groups
      effect: read
      questions:
      - What mailing groups have I set up?
      - Can I page through my recipient groups a few at a time?
      instructions:
      - text: List all my recipient groups.
      - text: Show the next {limit} mailing groups starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/new'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a recipient group
      effect: write
      questions:
      - How do I set up a new mailing list group to hold recipients?
      - Can I create an empty group now and add addresses to it later?
      instructions:
      - text: Create a new recipient group called {name}.
        slots:
          name: requestBody.name
      - text: Set up a mailing group named {name} for my next campaign.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/add/{group_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add existing recipients to a group
      effect: write
      questions:
      - Can I put recipients I've already created into another mailing group?
      - Is there a way to add several existing contacts to a group in one call?
      instructions:
      - text: Add recipients {recipients} to group {group_id}.
        slots:
          recipients: requestBody.recipients
          group_id: path.group_id
      - text: Put these existing recipient IDs {recipients} into mailing group {group_id}.
        slots:
          recipients: requestBody.recipients
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/remove/{group_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove specific recipients from a group
      effect: write
      questions:
      - How can I take a few people out of a mailing group without deleting them?
      - Can I drop selected recipients from one group while keeping the rest?
      instructions:
      - text: Remove recipients {recipients} from group {group_id}.
        slots:
          recipients: requestBody.recipients
          group_id: path.group_id
      - text: Take recipient IDs {recipients} out of mailing group {group_id} but keep their records.
        slots:
          recipients: requestBody.recipients
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/purge'].post
  update:
    x-apievangelist-phrasing:
      intent: Empty all recipients out of a group
      effect: destructive
      questions:
      - How do I clear every recipient out of a group but keep the group itself?
      - When I empty a group, can I also wipe the recipient records it contained?
      instructions:
      - text: Purge all recipients from group {id}.
        slots:
          id: requestBody.id
      - text: Empty group {id} and also delete its recipient records.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/calculate/{group_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Recalculate a group's counts and validity
      effect: write
      questions:
      - Why does my group's recipient count look out of date, and can I refresh it?
      - Can I re-check how many addresses in a group are valid?
      instructions:
      - text: Recalculate recipient counts for group {group_id}.
        slots:
          group_id: path.group_id
      - text: Refresh the address validity totals on mailing group {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a recipient group
      effect: destructive
      questions:
      - How do I delete a mailing group I no longer need?
      - If I remove a group entirely, do its recipients get deleted too?
      instructions:
      - text: Delete recipient group {id}.
        slots:
          id: requestBody.id
      - text: Delete group {id} along with every recipient in it.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'