# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Recipients API
  version: 1.0.0
extends: openapi/optimizely-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: 20
- target: $.paths['/{clientId}/recipients/{recipientListId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List recipients in a recipient list
      effect: read
      questions:
      - Who is on one of my Optimizely Campaign recipient lists?
      - Can I pull every recipient stored in a particular mailing list?
      instructions:
      - text: List the recipients in recipient list {recipientListId} for client {clientId}.
        slots:
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Show me everyone on list {recipientListId}.
        slots:
          recipientListId: path.recipientListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Bulk add recipients to a list
      effect: write
      questions:
      - How do I import a batch of recipients into a recipient list in one request?
      - Can I attach an opt-in process when adding many recipients at once?
      instructions:
      - text: Bulk add these recipients {recipients} to list {recipientListId} in client {clientId}.
        slots:
          recipients: requestBody.recipients
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Add multiple recipients to list {recipientListId} using opt-in process {optinProcessId}.
        slots:
          recipientListId: path.recipientListId
          optinProcessId: requestBody.optinProcessId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a single recipient to a list
      effect: write
      questions:
      - How can I subscribe one new email address to a recipient list?
      - Can I set a first and last name when adding a single recipient?
      instructions:
      - text: Add {email} as a new recipient on list {recipientListId} in client {clientId}.
        slots:
          email: requestBody.email
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Add recipient {email} named {first_name} {last_name} to list {recipientListId}.
        slots:
          email: requestBody.email
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          recipientListId: path.recipientListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove many recipients from a list
      effect: destructive
      questions:
      - Can I remove several recipients from a list by their IDs in one call?
      - What happens if I bulk-delete from a list without giving recipient IDs or a removal type?
      instructions:
      - text: Remove recipients {recipientIds} from list {recipientListId} in client {clientId}.
        slots:
          recipientIds: query.recipientIds
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Bulk-remove recipients from list {recipientListId} by removal type {removalType}.
        slots:
          recipientListId: path.recipientListId
          removalType: query.removalType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/{recipientId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one recipient's details
      effect: read
      questions:
      - What details are stored for a specific recipient on a list?
      - Can I look up a single subscriber record by recipient ID?
      instructions:
      - text: Get recipient {recipientId} from list {recipientListId}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
      - text: Show the record for {recipientId} on list {recipientListId} under client {clientId}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/{recipientId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a recipient's email and name
      effect: write
      questions:
      - How do I correct a subscriber's first or last name on a list?
      - Can I change the stored email address of an existing recipient record?
      instructions:
      - text: Update recipient {recipientId} on list {recipientListId} to email {email} in client {clientId}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
          email: requestBody.email
          clientId: path.clientId
      - text: Rename recipient {recipientId} on list {recipientListId} to {first_name} {last_name}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
          first_name: requestBody.first_name
          last_name: requestBody.last_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/{recipientId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update attribute values of one recipient
      effect: write
      questions:
      - Can I append text to one recipient's string field instead of overwriting it?
      - How do I change a single subscriber's list field values like city or segment?
      instructions:
      - text: Set attribute values {data} on recipient {recipientId} in list {recipientListId} in client {clientId}.
        slots:
          data: requestBody.data
          recipientId: path.recipientId
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Apply {data} to recipient {recipientId} on list {recipientListId} in {mode} mode.
        slots:
          data: requestBody.data
          recipientId: path.recipientId
          recipientListId: path.recipientListId
          mode: requestBody.mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/{recipientId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one recipient from a list
      effect: destructive
      questions:
      - How do I take a single subscriber off a recipient list?
      - Can I delete just one recipient by ID without affecting the rest of the list?
      instructions:
      - text: Delete recipient {recipientId} from list {recipientListId}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
      - text: Remove {recipientId} from recipient list {recipientListId} for client {clientId}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count recipients in a list
      effect: read
      questions:
      - How many recipients are on my recipient list right now?
      - Can I count only the recipients that match a target group?
      - Is there a limit on simultaneous recipient count requests per client?
      instructions:
      - text: Count the recipients on list {recipientListId} in client {clientId}.
        slots:
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Count recipients on list {recipientListId} in target group {targetGroup}.
        slots:
          recipientListId: path.recipientListId
          targetGroup: query.targetGroup
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/distinctvalues/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count recipients per distinct field value
      effect: read
      questions:
      - How many recipients share each value of a field like country?
      - Can I get a breakdown of subscriber counts per distinct attribute value?
      instructions:
      - text: Count recipients per distinct {attributeName} value on list {recipientListId} in client {clientId}.
        slots:
          attributeName: query.attributeName
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Break down target group {targetGroup} on list {recipientListId} by {attributeName} with counts.
        slots:
          targetGroup: query.targetGroup
          recipientListId: path.recipientListId
          attributeName: query.attributeName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/distinctvalues'].get
  update:
    x-apievangelist-phrasing:
      intent: Get distinct values of a recipient field
      effect: read
      questions:
      - What unique values appear in a given field across my recipient list?
      - Can I only examine the first few characters when collecting distinct field values?
      instructions:
      - text: List the distinct values of field {attributeName} on list {recipientListId} in client {clientId}.
        slots:
          attributeName: query.attributeName
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Get unique {attributeName} values on list {recipientListId} using the first {threshold} characters.
        slots:
          attributeName: query.attributeName
          recipientListId: path.recipientListId
          threshold: query.threshold
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/modify'].put
  update:
    x-apievangelist-phrasing:
      intent: Update attributes for several named recipients
      effect: write
      questions:
      - How do I change field values for a batch of specific recipients at once?
      - Can I update attributes of many listed subscribers in a single request?
      instructions:
      - text: Update attribute values for recipients {recipients} on list {recipientListId} in client {clientId}.
        slots:
          recipients: requestBody.recipients
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Batch-modify recipients {recipients} on list {recipientListId} with update mode {updateMode}.
        slots:
          recipients: requestBody.recipients
          recipientListId: path.recipientListId
          updateMode: requestBody.updateMode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/modify'].post
  update:
    x-apievangelist-phrasing:
      intent: Update attributes for a target group
      effect: write
      questions:
      - Can I set a field value for every recipient that matches a target group?
      - How do I mass-update subscribers selected by a segment rather than by ID?
      instructions:
      - text: Set {data} for all recipients in target group {targetGroup} on list {recipientListId} in client {clientId}.
        slots:
          data: requestBody.data
          targetGroup: requestBody.targetGroup
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Prepend or append values in target group {targetGroup} of list {recipientListId} using mode {mode}.
        slots:
          targetGroup: requestBody.targetGroup
          recipientListId: path.recipientListId
          mode: requestBody.mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/{recipientId}/optinstatus'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a recipient's opt-in status
      effect: read
      questions:
      - Has this subscriber confirmed their opt-in on the list?
      - Can I check whether one email address is opted in before mailing it?
      instructions:
      - text: Check the opt-in status of {recipientId} on list {recipientListId} in client {clientId}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Tell me if {recipientId} is opted in to list {recipientListId}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/{recipientListId}/{recipientId}/valid'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a recipient can receive mailings
      effect: read
      questions:
      - Is this recipient blacklisted, unsubscribed or over the bounce limit on one list?
      - Can I check mailing eligibility for SMS rather than email on a single list?
      instructions:
      - text: Check whether {recipientId} is valid to mail on list {recipientListId} in client {clientId}.
        slots:
          recipientId: path.recipientId
          recipientListId: path.recipientListId
          clientId: path.clientId
      - text: Verify {recipientId} can receive {mediaType} on list {recipientListId}.
        slots:
          recipientId: path.recipientId
          mediaType: query.mediaType
          recipientListId: path.recipientListId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/trackingoptout'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop tracking a recipient's opens and clicks
      effect: write
      questions:
      - How do I stop recording email opens and clicks for one recipient?
      - Can a subscriber opt out of action-based tracking but stay on the list?
      instructions:
      - text: Create a tracking opt-out for {recipientId}.
        slots:
          recipientId: requestBody.recipientId
      - text: Turn off open and click tracking for recipient {recipientId} under client {clientId}.
        slots:
          recipientId: requestBody.recipientId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/trackingoptout'].delete
  update:
    x-apievangelist-phrasing:
      intent: Resume tracking a recipient's opens and clicks
      effect: destructive
      questions:
      - How do I turn open and click tracking back on for a recipient who opted out?
      - Can I remove an existing tracking opt-out?
      instructions:
      - text: Delete the tracking opt-out for {recipientId} in client {clientId}.
        slots:
          recipientId: query.recipientId
          clientId: path.clientId
      - text: Reactivate open and click tracking for recipient {recipientId}.
        slots:
          recipientId: query.recipientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a recipient's validity across lists
      effect: read
      questions:
      - Can one recipient receive mailings on several of my lists at once?
      - What happens if I check recipient validity without naming any lists?
      instructions:
      - text: Check if {recipientId} is valid on recipient lists {recipientListIds} in client {clientId}.
        slots:
          recipientId: query.recipientId
          recipientListIds: query.recipientListIds
          clientId: path.clientId
      - text: Check {recipientId}'s mailing eligibility across all my recipient lists.
        slots:
          recipientId: query.recipientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a recipient's action history
      effect: destructive
      questions:
      - How do I erase all the open and click history stored for one recipient?
      - Can I record a reason when wiping a subscriber's action data?
      instructions:
      - text: Wipe all action data for recipient {recipientKey} in client {clientId}.
        slots:
          recipientKey: query.recipientKey
          clientId: path.clientId
      - text: Delete the history of recipient {recipientKey} with reason {reason}.
        slots:
          recipientKey: query.recipientKey
          reason: query.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/recipients/updaterecipientid'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a recipient's ID
      effect: write
      questions:
      - A subscriber changed their email; how do I rename their recipient ID?
      - Can I swap an existing recipient ID for a new one?
      instructions:
      - text: Change recipient ID {recipientId} to {newRecipientId}.
        slots:
          recipientId: requestBody.recipientId
          newRecipientId: requestBody.newRecipientId
      - text: Rename recipient {recipientId} to new ID {newRecipientId} for client {clientId}.
        slots:
          recipientId: requestBody.recipientId
          newRecipientId: requestBody.newRecipientId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'