# 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 Recipients API
  version: 1.0.0
extends: openapi/stannp-recipients-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: 5
- target: $.paths['/recipients/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List recipients
      effect: read
      questions:
      - Who is on my mailing list?
      - Can I list only the recipients that belong to one group?
      instructions:
      - text: List all my recipients.
      - text: Show the recipients in group {group_id}, {limit} at a time.
        slots:
          group_id: query.group_id
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/recipients/get/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a single recipient
      effect: read
      questions:
      - What address do I have on file for a specific recipient?
      - Can I fetch one contact's full record by recipient ID?
      instructions:
      - text: Show the details of recipient {id}.
        slots:
          id: path.id
      - text: Get the name and address saved for recipient {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/recipients/new'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a recipient address
      effect: write
      questions:
      - How do I add one new person's postal address to my mailing list?
      - What happens if I add a recipient who already exists?
      - Can I attach my own reference ID to a new recipient?
      instructions:
      - text: Add {firstname} {lastname} at {address1}, {city} {postcode}, {country} as a recipient.
        slots:
          firstname: requestBody.firstname
          lastname: requestBody.lastname
          address1: requestBody.address1
          city: requestBody.city
          postcode: requestBody.postcode
          country: requestBody.country
      - text: Create a recipient for {company} at {address1}, {postcode} and put them in group {group_id}.
        slots:
          company: requestBody.company
          address1: requestBody.address1
          postcode: requestBody.postcode
          group_id: requestBody.group_id
      - text: Add a new recipient with reference {ref_id} and email {email}.
        slots:
          ref_id: requestBody.ref_id
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/recipients/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a recipient
      effect: destructive
      questions:
      - How do I permanently remove someone's address record?
      - Can a deleted recipient be recovered afterwards?
      instructions:
      - text: Delete recipient {id} permanently.
        slots:
          id: requestBody.id
      - text: Erase the address record for recipient {id}.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/recipients/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk import recipients from a spreadsheet
      effect: write
      questions:
      - Can I upload a CSV or Excel file of addresses instead of adding them one by one?
      - What if my spreadsheet of contacts has no header row?
      - Is there a way to remap spreadsheet columns when bulk importing addresses?
      instructions:
      - text: Import the recipients in {file} into group {group_id}.
        slots:
          file: requestBody.file
          group_id: requestBody.group_id
      - text: Bulk load the CSV at {file} into group {group_id} using column mappings {mappings}.
        slots:
          file: requestBody.file
          group_id: requestBody.group_id
          mappings: requestBody.mappings
      method: generated
      generated: '2026-09-26'