# 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 Letters API
  version: 1.0.0
extends: openapi/stannp-letters-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: 4
- target: $.paths['/letters/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a letter from a template or HTML
      effect: write
      questions:
      - How do I mail a single letter built from one of my saved templates?
      - Can I preview a letter as a PDF without it being printed or charged?
      - Is it possible to send a letter first class and double-sided?
      instructions:
      - text: Send a letter using template {template} to recipient {recipient}.
        slots:
          template: requestBody.template
          recipient: requestBody.recipient
      - text: Generate a test preview of a letter with these HTML pages {pages} for {recipient}, no charge.
        slots:
          pages: requestBody.pages
          recipient: requestBody.recipient
      - text: Mail template {template} to {recipient} with the {addons} upgrade.
        slots:
          template: requestBody.template
          recipient: requestBody.recipient
          addons: requestBody.addons
      method: generated
      generated: '2026-09-26'
- target: $.paths['/letters/post'].post
  update:
    x-apievangelist-phrasing:
      intent: Mail a pre-merged PDF letter
      effect: write
      questions:
      - Can I upload a finished PDF with the address already on it and have it posted?
      - What's the page limit on a ready-made PDF letter?
      - Can a pre-merged PDF letter be flagged as transactional because it holds sensitive data?
      instructions:
      - text: Post the pre-merged PDF at {pdf} as a letter to {country}.
        slots:
          pdf: requestBody.pdf
          country: requestBody.country
      - text: Dispatch my already-addressed PDF {pdf} to {country} as a transactional letter.
        slots:
          pdf: requestBody.pdf
          country: requestBody.country
      method: generated
      generated: '2026-09-26'
- target: $.paths['/letters/get/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a letter mailpiece
      effect: read
      questions:
      - What's the current status of a letter I sent?
      - Can I pull up the details of one letter mailpiece by its ID?
      instructions:
      - text: Show the details of letter {id}.
        slots:
          id: path.id
      - text: Check where letter mailpiece {id} is in the process.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/letters/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a letter before dispatch
      effect: destructive
      questions:
      - Can I stop a letter from going out if it hasn't been dispatched yet?
      - Is it too late to cancel a letter once it has been posted?
      instructions:
      - text: Cancel letter {id} before it's dispatched.
        slots:
          id: requestBody.id
      - text: Stop letter mailpiece {id} from being sent.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'