API Evangelist conversational phrasing for Clerk Com Email Addresses API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Com Email Addresses API
  version: 1.0.0
extends: openapi/clerk-com-email-addresses-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: 10
- target: $.paths['/email_addresses'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an email address to a user (backend)
      effect: write
      questions:
      - How do I attach an extra email address to a user from my backend?
      - Can I add an email to a user already marked verified and primary?
      instructions:
      - text: Add email {email_address} to user {user_id}.
        slots:
          email_address: requestBody.email_address
          user_id: requestBody.user_id
      - text: Add {email_address} to user {user_id} as a verified primary address.
        slots:
          email_address: requestBody.email_address
          user_id: requestBody.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/email_addresses/{email_address_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an email address by ID (backend)
      effect: read
      questions:
      - What are the details and verification state of an email address ID from the backend?
      - Can my server look up any user's email address record by its ID?
      instructions:
      - text: Retrieve email address {email_address_id}.
        slots:
          email_address_id: path.email_address_id
      - text: Show the verification status of email record {email_address_id}.
        slots:
          email_address_id: path.email_address_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/email_addresses/{email_address_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete any user's email address (backend)
      effect: destructive
      questions:
      - How does my backend remove an email address from a user's account?
      - Can a server-side call delete an email address by its ID?
      instructions:
      - text: Delete email address {email_address_id} using the backend API.
        slots:
          email_address_id: path.email_address_id
      - text: Remove email record {email_address_id} from its user server-side.
        slots:
          email_address_id: path.email_address_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/email_addresses/{email_address_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark an email address verified or primary
      effect: write
      questions:
      - How do I mark a user's email address as verified from the backend?
      - Can I make a different email address the user's primary one?
      instructions:
      - text: Mark email address {email_address_id} as verified.
        slots:
          email_address_id: path.email_address_id
      - text: Make {email_address_id} the primary email address of its user.
        slots:
          email_address_id: path.email_address_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/email_addresses'].get
  update:
    x-apievangelist-phrasing:
      intent: List the signed-in user's email addresses
      effect: read
      questions:
      - Which email addresses are on my own account?
      - Can the signed-in user see all their emails and which are verified?
      instructions:
      - text: List the email addresses on my account.
      - text: Show my email addresses for session {_clerk_session_id}.
        slots:
          _clerk_session_id: query._clerk_session_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/email_addresses'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an email address to my own account
      effect: write
      questions:
      - How do I add another email address to my own account?
      - Does a newly added email need to be verified before it's usable?
      instructions:
      - text: Add {email_address} to my account.
        slots:
          email_address: requestBody.email_address
      - text: Attach {email_address} to the signed-in user so I can verify it next.
        slots:
          email_address: requestBody.email_address
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/email_addresses/{email_id}/attempt_verification'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit the code to verify my email address
      effect: write
      questions:
      - I got a verification code by email, how do I confirm my new address?
      - What do I send to complete verification of an email I added to my account?
      instructions:
      - text: Verify my email address {email_id} with code {code}.
        slots:
          email_id: path.email_id
          code: requestBody.code
      - text: Submit code {code} to confirm email {email_id}.
        slots:
          email_id: path.email_id
          code: requestBody.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/email_addresses/{email_id}/prepare_verification'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a verification code or link to my email
      effect: write
      questions:
      - How do I get a verification code sent to an email address I just added?
      - Can I verify my email with a magic link instead of a code?
      instructions:
      - text: Send a verification email to my address {email_id} using {strategy}.
        slots:
          email_id: path.email_id
          strategy: requestBody.strategy
      - text: Email a verification link for {email_id} that returns to {redirect_url}.
        slots:
          email_id: path.email_id
          redirect_url: requestBody.redirect_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/email_addresses/{email_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my email addresses
      effect: read
      questions:
      - Can I check whether one of my own email addresses has been verified?
      - What details are stored for a specific email on my account?
      instructions:
      - text: Get my email address {email_id}.
        slots:
          email_id: path.email_id
      - text: Show the verification status of my email {email_id}.
        slots:
          email_id: path.email_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/email_addresses/{email_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an email address from my account
      effect: destructive
      questions:
      - How do I remove an old email address from my own account?
      - Can the signed-in user delete one of their emails?
      instructions:
      - text: Remove email {email_id} from my account.
        slots:
          email_id: path.email_id
      - text: Delete my own email address {email_id}.
        slots:
          email_id: path.email_id
      method: generated
      generated: '2026-09-26'