# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Sendgrid Lists API
  version: 1.0.0
extends: openapi/sendgrid-lists-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 17
- target: $.paths['/v3/contactdb/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List all legacy recipient lists
      effect: read
      questions:
      - What recipient lists do I have in the legacy contacts database?
      - Does SendGrid return anything if I have no legacy recipient lists yet?
      instructions:
      - text: Show me every recipient list in my legacy contacts database.
      - text: List the legacy contactdb recipient lists on this account.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a legacy recipient list
      effect: write
      questions:
      - How do I create a new recipient list in the old contacts database?
      - Can I make a legacy recipient list with just a name?
      instructions:
      - text: Create a legacy recipient list called {name}.
        slots:
          name: requestBody.name
      - text: Add a new contactdb recipient list named {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several legacy recipient lists
      effect: destructive
      questions:
      - Can I delete several legacy recipient lists in one call?
      - Is there a bulk delete for old contactdb recipient lists?
      instructions:
      - text: Bulk delete multiple legacy recipient lists at once.
      - text: Remove a batch of contactdb recipient lists in a single request.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists/{list_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one legacy recipient list
      effect: read
      questions:
      - How can I look up a single legacy recipient list by its ID?
      - What details come back for one contactdb recipient list?
      instructions:
      - text: Get legacy recipient list {list_id}.
        slots:
          list_id: path.list_id
      - text: Fetch the details of contactdb list {list_id}.
        slots:
          list_id: path.list_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists/{list_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a legacy recipient list
      effect: destructive
      questions:
      - If I delete a legacy recipient list, can the recipients on it be deleted too?
      - How do I remove one specific contactdb recipient list?
      instructions:
      - text: Delete legacy recipient list {list_id}.
        slots:
          list_id: path.list_id
      - text: 'Delete contactdb list {list_id} and also delete its contacts: {delete_contacts}.'
        slots:
          list_id: path.list_id
          delete_contacts: query.delete_contacts
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists/{list_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a legacy recipient list
      effect: write
      questions:
      - Can I rename one of my legacy recipient lists?
      - What can be changed on an existing contactdb list besides its name?
      instructions:
      - text: Rename legacy recipient list {list_id} to {name}.
        slots:
          list_id: path.list_id
          name: requestBody.name
      - text: Change the name of contactdb list {list_id} to {name}.
        slots:
          list_id: path.list_id
          name: requestBody.name
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists/{list_id}/recipients'].get
  update:
    x-apievangelist-phrasing:
      intent: List recipients on a legacy list
      effect: read
      questions:
      - Who are the recipients on a given legacy recipient list?
      - Can I page through the recipients of a contactdb list?
      instructions:
      - text: Show the recipients on legacy list {list_id}.
        slots:
          list_id: path.list_id
      - text: Get page {page} of recipients on contactdb list {list_id}, {page_size} per page.
        slots:
          page: query.page
          list_id: path.list_id
          page_size: query.page_size
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists/{list_id}/recipients'].post
  update:
    x-apievangelist-phrasing:
      intent: Add many recipients to a legacy list
      effect: write
      questions:
      - How do I put several existing recipients onto a legacy list at once?
      - What format do recipient IDs need when adding them in bulk to a contactdb list?
      instructions:
      - text: Add a batch of existing recipients to legacy list {list_id}.
        slots:
          list_id: path.list_id
      - text: Bulk add recipient IDs to contactdb list {list_id}.
        slots:
          list_id: path.list_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists/{list_id}/recipients/{recipient_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add one recipient to a legacy list
      effect: write
      questions:
      - Can I add a single recipient to a legacy recipient list?
      - Which call adds just one contactdb recipient to one list?
      instructions:
      - text: Add recipient {recipient_id} to legacy list {list_id}.
        slots:
          recipient_id: path.recipient_id
          list_id: path.list_id
      - text: Put contactdb recipient {recipient_id} on list {list_id}.
        slots:
          recipient_id: path.recipient_id
          list_id: path.list_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/contactdb/lists/{list_id}/recipients/{recipient_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a recipient from a legacy list
      effect: destructive
      questions:
      - How do I take one recipient off a legacy recipient list?
      - Can I drop a single contactdb recipient from just one list?
      instructions:
      - text: Remove recipient {recipient_id} from legacy list {list_id}.
        slots:
          recipient_id: path.recipient_id
          list_id: path.list_id
      - text: Delete contactdb recipient {recipient_id} from list {list_id} only.
        slots:
          recipient_id: path.recipient_id
          list_id: path.list_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List all Marketing Campaigns contact lists
      effect: read
      questions:
      - What contact lists do I have in Marketing Campaigns?
      - Can I page through my marketing contact lists with a page token?
      instructions:
      - text: List all my Marketing Campaigns contact lists.
      - text: Get my marketing contact lists, {page_size} per page.
        slots:
          page_size: query.page_size
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Marketing Campaigns contact list
      effect: write
      questions:
      - How do I create a new contact list for Marketing Campaigns?
      - Could a new marketing contact list be used to trigger an automation?
      instructions:
      - text: Create a marketing contact list named {name}.
        slots:
          name: requestBody.name
      - text: Make a new Marketing Campaigns list called {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/lists/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Marketing Campaigns contact list
      effect: read
      questions:
      - Can I see a sample of the most recent contacts on a marketing list?
      - What does SendGrid return about a single marketing contact list?
      instructions:
      - text: Get marketing contact list {id}.
        slots:
          id: path.id
      - text: 'Show marketing list {id} with a contact sample: {contact_sample}.'
        slots:
          id: path.id
          contact_sample: query.contact_sample
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/lists/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Marketing Campaigns contact list
      effect: destructive
      questions:
      - When I delete a marketing contact list, are the contacts on it deleted as well?
      - How do I remove a Marketing Campaigns list I no longer use?
      instructions:
      - text: Delete marketing contact list {id}.
        slots:
          id: path.id
      - text: 'Delete marketing list {id} and its contacts too: {delete_contacts}.'
        slots:
          id: path.id
          delete_contacts: query.delete_contacts
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/lists/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a Marketing Campaigns contact list
      effect: write
      questions:
      - Can I change the name of a marketing contact list?
      - Is renaming the only update allowed on a Marketing Campaigns list?
      instructions:
      - text: Rename marketing contact list {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Update the name of Marketing Campaigns list {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/lists/{id}/contacts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove contacts from a marketing list
      effect: destructive
      questions:
      - Can I take contacts off a marketing list without deleting the contacts themselves?
      - How do I remove specific contact IDs from one Marketing Campaigns list?
      instructions:
      - text: Remove contacts {contact_ids} from marketing list {id}.
        slots:
          contact_ids: query.contact_ids
          id: path.id
      - text: Take contact IDs {contact_ids} out of list {id} but keep the contacts.
        slots:
          contact_ids: query.contact_ids
          id: path.id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/lists/{id}/contacts/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count contacts on a marketing list
      effect: read
      questions:
      - How many contacts are on one of my marketing lists?
      - Is there a quick way to get just the contact count for a list?
      instructions:
      - text: Count the contacts on marketing list {id}.
        slots:
          id: path.id
      - text: Tell me how many contacts list {id} holds.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-24'