# 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 Postcards API
  version: 1.0.0
extends: openapi/stannp-postcards-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: 3
- target: $.paths['/postcards/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a postcard
      effect: write
      questions:
      - How do I mail a single postcard with my own front and back artwork?
      - Can I get a test PDF of a postcard without being charged?
      - Is there a way to stop a postcard going out if the address can't be verified?
      instructions:
      - text: Send a postcard using template {template} to recipient {recipient}.
        slots:
          template: requestBody.template
          recipient: requestBody.recipient
      - text: Mail a postcard to {recipient} with front {front}, back {back} and message {message}.
        slots:
          recipient: requestBody.recipient
          front: requestBody.front
          back: requestBody.back
          message: requestBody.message
      - text: Create a test postcard preview in {size} for {recipient} without dispatching it.
        slots:
          size: requestBody.size
          recipient: requestBody.recipient
      method: generated
      generated: '2026-09-26'
- target: $.paths['/postcards/get/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a postcard mailpiece
      effect: read
      questions:
      - What's the status of a postcard I already sent?
      - Can I see the details of one postcard by its mailpiece ID?
      instructions:
      - text: Show the details of postcard {id}.
        slots:
          id: path.id
      - text: Check the progress of postcard mailpiece {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/postcards/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a postcard before dispatch
      effect: destructive
      questions:
      - Can I cancel a postcard that hasn't been dispatched yet?
      - Is a postcard still cancellable once it has left for the post?
      instructions:
      - text: Cancel postcard {id} before it goes out.
        slots:
          id: requestBody.id
      - text: Stop postcard mailpiece {id} from being posted.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'