API Evangelist conversational phrasing for Novu Domains API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Novu Domains API
  version: 1.0.0
extends: openapi/novu-domains-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: 15
- target: $.paths['/v1/domains'].get
  update:
    x-apievangelist-phrasing:
      intent: List inbound-email domains
      effect: read
      questions:
      - Which inbound email domains are registered in my current environment?
      - Can I filter my inbound domains by part of the domain name?
      - How do I page through a long list of receiving domains in Novu?
      instructions:
      - text: List all inbound-email domains in this environment.
      - text: Find my inbound domains whose name contains {name}.
        slots:
          name: query.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains'].post
  update:
    x-apievangelist-phrasing:
      intent: Register an inbound-email domain
      effect: write
      questions:
      - How do I set up a new domain so it can receive inbound email?
      - What DNS records do I get back when I register a receiving domain?
      instructions:
      - text: Register {name} as a new inbound-email domain.
        slots:
          name: requestBody.name
      - text: Add receiving domain {name} with metadata {data} and give me the DNS records to add.
        slots:
          name: requestBody.name
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a domain's configuration and DNS records
      effect: read
      questions:
      - How can I see the configuration and required DNS records for one of my domains?
      - Does looking up a domain re-check its DNS, or just show the stored status?
      instructions:
      - text: Show me the configuration for domain {domain}.
        slots:
          domain: path.domain
      - text: List the DNS records {domain} needs to have in place.
        slots:
          domain: path.domain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an inbound-email domain
      effect: destructive
      questions:
      - What happens to a domain's routes when I delete the domain?
      - How do I stop a domain from receiving inbound mail altogether?
      instructions:
      - text: Delete domain {domain} and all of its routes.
        slots:
          domain: path.domain
      - text: Remove {domain} so its inbound mail stops being processed.
        slots:
          domain: path.domain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a domain's metadata
      effect: write
      questions:
      - How do I change the metadata attached to an inbound domain?
      - If I send new data for a domain, does it merge or replace the old metadata?
      instructions:
      - text: Replace the metadata on domain {domain} with {data}.
        slots:
          domain: path.domain
          data: requestBody.data
      - text: Update the optional fields on domain {domain}.
        slots:
          domain: path.domain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a domain's MX records
      effect: write
      questions:
      - I've added the MX records; how do I get Novu to re-check and verify my domain?
      - Can I refresh a domain's verification status from live DNS?
      instructions:
      - text: Verify domain {domain} against live DNS now.
        slots:
          domain: path.domain
      - text: Re-check the MX record status for {domain} and update its verification.
        slots:
          domain: path.domain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/diagnose'].post
  update:
    x-apievangelist-phrasing:
      intent: Diagnose inbound DNS problems
      effect: read
      questions:
      - Why isn't my domain receiving inbound email?
      - Can I check whether my domain's mail host is on a DNS blocklist or has an apex CNAME collision?
      instructions:
      - text: Run inbound DNS diagnostics for {domain} and tell me how to fix any issues.
        slots:
          domain: path.domain
      - text: Troubleshoot the MX setup on {domain}.
        slots:
          domain: path.domain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/routes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a domain's routes
      effect: read
      questions:
      - Which addresses on my domain have inbound routes set up?
      - Can I find every route on a domain that points to a particular agent?
      instructions:
      - text: List all routes on domain {domain}.
        slots:
          domain: path.domain
      - text: Show the routes on {domain} that deliver to agent {agentId}.
        slots:
          domain: path.domain
          agentId: query.agentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/routes'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an inbound mail route
      effect: write
      questions:
      - How do I forward mail sent to an address on my domain to a webhook?
      - Can I route inbound email for one address to an agent instead of a webhook?
      - Is it possible to have two routes for the same address on a domain?
      instructions:
      - text: Create a {type} route for {address}@{domain}.
        slots:
          type: requestBody.type
          address: requestBody.address
          domain: path.domain
      - text: Route mail sent to {address} on {domain} to agent {agentId}.
        slots:
          address: requestBody.address
          domain: path.domain
          agentId: requestBody.agentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/routes/{address}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the route for an address
      effect: read
      questions:
      - Where does mail sent to a specific address on my domain get delivered?
      - How do I look up the wildcard catch-all route for a domain?
      instructions:
      - text: Show the route bound to {address}@{domain}.
        slots:
          address: path.address
          domain: path.domain
      - text: Fetch the catch-all route on {domain} using address {address}.
        slots:
          domain: path.domain
          address: path.address
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/routes/{address}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an inbound mail route
      effect: destructive
      questions:
      - How do I stop processing inbound mail for one address without deleting the domain?
      - Can I remove a single route from my receiving domain?
      instructions:
      - text: Delete the route for {address}@{domain}.
        slots:
          address: path.address
          domain: path.domain
      - text: Stop handling inbound mail to {address} on {domain}.
        slots:
          address: path.address
          domain: path.domain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/routes/{address}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change where a route delivers
      effect: write
      questions:
      - How do I switch an existing address route from a webhook to an agent?
      - Can I rename the address on a route, or do I have to recreate it?
      instructions:
      - text: Point the existing route for {address}@{domain} at agent {agentId}.
        slots:
          address: path.address
          domain: path.domain
          agentId: requestBody.agentId
      - text: Change the route type for {address} on {domain} to {type}.
        slots:
          address: path.address
          domain: path.domain
          type: requestBody.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/routes/{address}/test'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a test email through a route
      effect: write
      questions:
      - How can I test an inbound route with a fake email before going live?
      - Can I preview the payload a route would deliver without actually sending it?
      instructions:
      - text: Send a test email from {from} with subject {subject} through the route for {address}@{domain}.
        slots:
          from: requestBody.from
          subject: requestBody.subject
          address: path.address
          domain: path.domain
      - text: Dry-run the route for {address} on {domain} with subject {subject} from {from}, setting dryRun to {dryRun}.
        slots:
          address: path.address
          domain: path.domain
          subject: requestBody.subject
          from: requestBody.from
          dryRun: requestBody.dryRun
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/auto-configure'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if DNS auto-configuration is available
      effect: read
      questions:
      - Can Novu set up my domain's DNS records automatically through Domain Connect?
      - If automatic DNS setup isn't supported, which records do I have to add by hand?
      instructions:
      - text: Check whether DNS auto-configuration is available for {domain}.
        slots:
          domain: path.domain
      - text: Tell me which DNS records I must add manually for {domain} if Domain Connect is unavailable.
        slots:
          domain: path.domain
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/domains/{domain}/auto-configure/start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start DNS auto-configuration
      effect: write
      questions:
      - How do I get a link that applies Novu's DNS records at my DNS provider for me?
      - Can I choose where my DNS provider sends me back after auto-configuration?
      instructions:
      - text: Start DNS auto-configuration for {domain}.
        slots:
          domain: path.domain
      - text: Generate the Domain Connect redirect for {domain} and return me to {redirectUri} afterwards.
        slots:
          domain: path.domain
          redirectUri: requestBody.redirectUri
      method: generated
      generated: '2026-09-26'