API Evangelist conversational phrasing for Twilio SendGrid Marketing Campaigns Contacts API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Twilio SendGrid Marketing Campaigns Contacts API
  version: 1.0.0
extends: openapi/sendgrid-contacts-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: 15
- target: $.paths['/v3/marketing/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a sample of recent contacts
      effect: read
      questions:
      - Can I get a quick look at the 50 most recently added marketing contacts in SendGrid?
      - What does the sample contacts view return besides the contacts themselves?
      instructions:
      - text: Show me a sample of my most recently uploaded marketing contacts.
      - text: Pull the recent-contacts sample sorted by email address.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts'].put
  update:
    x-apievangelist-phrasing:
      intent: Add or update marketing contacts
      effect: write
      questions:
      - How do I add new contacts or update existing ones in Marketing Campaigns?
      - How many contacts can I upsert in a single request?
      - Can I put contacts onto specific lists at the same time I upsert them?
      instructions:
      - text: 'Upsert these contacts: {contacts}.'
        slots:
          contacts: requestBody.contacts
      - text: Add or update {contacts} and attach them to lists {list_ids}.
        slots:
          contacts: requestBody.contacts
          list_ids: requestBody.list_ids
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete marketing contacts
      effect: destructive
      questions:
      - How can I delete several marketing contacts at once by their IDs?
      - Is it possible to wipe every contact in my account in one call?
      instructions:
      - text: Delete the contacts with IDs {ids}.
        slots:
          ids: query.ids
      - text: Delete all of my marketing contacts, setting delete_all_contacts to {delete_all_contacts}.
        slots:
          delete_all_contacts: query.delete_all_contacts
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one contact's full details
      effect: read
      questions:
      - What fields and custom data are stored on a single contact when I look it up by ID?
      - Where do I see every field for one specific contact?
      instructions:
      - text: Get the full record for contact {id}.
        slots:
          id: path.id
      - text: Show all fields stored on contact ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch many contacts by their IDs at once
      effect: read
      questions:
      - Can I fetch up to 100 contacts in one call if I already have their IDs?
      - Is there a faster way than looking up contacts by ID one at a time?
      instructions:
      - text: Fetch the batch of contacts with IDs {ids} in one request.
        slots:
          ids: requestBody.ids
      - text: 'Retrieve these contact IDs together: {ids}.'
        slots:
          ids: requestBody.ids
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/{contact_id}/identifiers'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one identifier from a contact
      effect: destructive
      questions:
      - Can I remove just a phone number or external ID from a contact without deleting the contact?
      - What happens if I try to remove a contact's only identifier?
      instructions:
      - text: Remove the {identifier_type} identifier {identifier_value} from contact {contact_id}.
        slots:
          identifier_type: requestBody.identifier_type
          identifier_value: requestBody.identifier_value
          contact_id: path.contact_id
      - text: Strip identifier {identifier_value} off contact {contact_id} but keep the contact.
        slots:
          identifier_value: requestBody.identifier_value
          contact_id: path.contact_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count all stored contacts
      effect: read
      questions:
      - How many marketing contacts do I have stored in total?
      - What is my current total contact count?
      instructions:
      - text: Tell me the total number of contacts in my account.
      - text: Get my overall marketing contact count.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/exports'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact export jobs
      effect: read
      questions:
      - Which contact exports are currently running or recently finished?
      - Where can I see the export type and status of all my contact export jobs?
      instructions:
      - text: List all of my contact export jobs.
      - text: Show every in-flight or recently completed contact export.
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/exports'].post
  update:
    x-apievangelist-phrasing:
      intent: Export contacts from lists or segments
      effect: write
      questions:
      - How do I export the contacts in a list or segment to a file?
      - Can I get an email with the download link when my contact export is ready?
      - Is there a maximum file size I can set for a contact export?
      instructions:
      - text: Export the contacts in lists {list_ids} as {file_type}.
        slots:
          list_ids: requestBody.list_ids
          file_type: requestBody.file_type
      - text: Start a contact export for segments {segment_ids} and email me when it finishes via {notifications}.
        slots:
          segment_ids: requestBody.segment_ids
          notifications: requestBody.notifications
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/exports/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a contact export's status
      effect: read
      questions:
      - Is my contact export finished, and where are the download URLs?
      - What status does a specific contact export job have right now?
      instructions:
      - text: Check the status of contact export {id}.
        slots:
          id: path.id
      - text: Get the download links for finished contact export {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/imports'].put
  update:
    x-apievangelist-phrasing:
      intent: Import contacts from a CSV file
      effect: write
      questions:
      - Can I bulk import up to a million contacts from a CSV?
      - How do I map my CSV columns to contact fields during an import?
      instructions:
      - text: Start a {file_type} contact import using field mappings {field_mappings}.
        slots:
          file_type: requestBody.file_type
          field_mappings: requestBody.field_mappings
      - text: Import a CSV of contacts into lists {list_ids} with mappings {field_mappings}.
        slots:
          list_ids: requestBody.list_ids
          field_mappings: requestBody.field_mappings
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/imports/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a contact import job's status
      effect: read
      questions:
      - Did my contact import or upsert job finish, and were there any errors?
      - Where do I check progress on a contact job using its job_id?
      instructions:
      - text: Check the status of contact import job {id}.
        slots:
          id: path.id
      - text: Show the results and errors for contact job {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search contacts with an SGQL query
      effect: read
      questions:
      - Can I search my contacts with a query language instead of exact matches?
      - Why does searching contacts by email need the address in lower case?
      instructions:
      - text: Search my contacts with the SGQL query {query}.
        slots:
          query: requestBody.query
      - text: 'Find contacts matching this SGQL filter: {query}.'
        slots:
          query: requestBody.query
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/search/emails'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up contacts by email address
      effect: read
      questions:
      - Can I find contacts by their email addresses, including alternate emails?
      - What is the limit on how many email addresses I can look up at once?
      instructions:
      - text: Look up the contacts with emails {emails}.
        slots:
          emails: requestBody.emails
      - text: Find the contact whose email address is {emails}.
        slots:
          emails: requestBody.emails
      method: generated
      generated: '2026-09-24'
- target: $.paths['/v3/marketing/contacts/search/identifiers/{identifier_type}'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up contacts by an identifier type
      effect: read
      questions:
      - Which identifier types can I use to find contacts, like phone number ID or external ID?
      - Can I look up contacts by their anonymous ID?
      instructions:
      - text: Find contacts whose {identifier_type} matches {identifiers}.
        slots:
          identifier_type: path.identifier_type
          identifiers: requestBody.identifiers
      - text: Look up contacts by {identifier_type} values {identifiers}.
        slots:
          identifier_type: path.identifier_type
          identifiers: requestBody.identifiers
      method: generated
      generated: '2026-09-24'