# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Nylas Messages API
  version: 1.0.0
extends: openapi/nylas-messages-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: 9
- target: $.paths['/v3/grants/{grant_id}/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search a user's email messages
      effect: read
      questions:
      - How do I list the emails in a connected user's mailbox?
      - Can I filter a user's messages to only unread ones that have attachments?
      - Is there a way to find messages received from a specific sender after a certain date?
      instructions:
      - text: List the latest {limit} messages in mailbox {grant_id}.
        slots:
          limit: query.limit
          grant_id: path.grant_id
      - text: Find messages in {grant_id} from {from} with the subject {subject}.
        slots:
          grant_id: path.grant_id
          from: query.from
          subject: query.subject
      - text: Show unread messages in mailbox {grant_id} received after {received_after}.
        slots:
          grant_id: path.grant_id
          received_after: query.received_after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/messages/{message_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a single email message
      effect: read
      questions:
      - How can I fetch the full contents of one email by its message ID?
      - Can I get just the headers or selected fields of a single message?
      instructions:
      - text: Open message {message_id} in mailbox {grant_id}.
        slots:
          message_id: path.message_id
          grant_id: path.grant_id
      - text: Fetch message {message_id} for grant {grant_id} including its {fields}.
        slots:
          message_id: path.message_id
          grant_id: path.grant_id
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/messages/{message_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark, star or move an email message
      effect: write
      questions:
      - How do I mark an email as read or unread through the API?
      - Can I star a message or move it to another folder?
      - What happens to the existing metadata when I update a message's attributes?
      instructions:
      - text: Mark message {message_id} in {grant_id} as unread.
        slots:
          message_id: path.message_id
          grant_id: path.grant_id
      - text: Star message {message_id} for grant {grant_id}.
        slots:
          message_id: path.message_id
          grant_id: path.grant_id
      - text: Move email {message_id} in mailbox {grant_id} into folder {folders}.
        slots:
          message_id: path.message_id
          grant_id: path.grant_id
          folders: requestBody.folders
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/messages/{message_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an email message
      effect: destructive
      questions:
      - Does deleting an email send it to Trash or remove it permanently?
      - How do I permanently delete an email instead of trashing it?
      instructions:
      - text: Delete message {message_id} from mailbox {grant_id}.
        slots:
          message_id: path.message_id
          grant_id: path.grant_id
      - text: Hard delete email {message_id} for grant {grant_id} so it skips the Trash.
        slots:
          message_id: path.message_id
          grant_id: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/messages/clean'].put
  update:
    x-apievangelist-phrasing:
      intent: Clean up email bodies into plain content
      effect: write
      questions:
      - Can I strip signatures, links and images out of email bodies to get clean text?
      - Is there a way to convert an email's HTML into Markdown?
      - Which extra content is always removed when cleaning messages?
      instructions:
      - text: Clean messages {message_id} in mailbox {grant_id} and return them as Markdown.
        slots:
          message_id: requestBody.message_id
          grant_id: path.grant_id
      - text: Clean email {message_id} for {grant_id}, removing links and images.
        slots:
          message_id: requestBody.message_id
          grant_id: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/messages/send'].post
  update:
    x-apievangelist-phrasing:
      intent: Send or schedule an email from a user's mailbox
      effect: write
      questions:
      - How do I send an email on behalf of a connected user?
      - Can I schedule an email to go out at a later time?
      - Is it possible to send a reply to an existing message with open and link tracking?
      instructions:
      - text: Send an email from {grant_id} to {to} with subject {subject}.
        slots:
          grant_id: path.grant_id
          to: requestBody.to
          subject: requestBody.subject
      - text: Schedule a message from mailbox {grant_id} to {to} to be sent at {send_at}.
        slots:
          grant_id: path.grant_id
          to: requestBody.to
          send_at: requestBody.send_at
      - text: Reply to message {reply_to_message_id} from {grant_id}, addressed to {to}.
        slots:
          reply_to_message_id: requestBody.reply_to_message_id
          grant_id: path.grant_id
          to: requestBody.to
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/messages/schedules'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's scheduled emails
      effect: read
      questions:
      - Which emails does this user have scheduled to send later?
      - Can I see scheduled messages that have already gone out as well as pending ones?
      instructions:
      - text: List all scheduled messages for mailbox {grant_id}.
        slots:
          grant_id: path.grant_id
      - text: Show me every send schedule on grant {grant_id}.
        slots:
          grant_id: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/messages/schedules/{scheduleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of one scheduled email
      effect: read
      questions:
      - How can I check whether a specific scheduled email has been sent yet?
      - Can I look up a single scheduled message by its schedule ID?
      instructions:
      - text: Get scheduled message {scheduleId} for mailbox {grant_id}.
        slots:
          scheduleId: path.scheduleId
          grant_id: path.grant_id
      - text: Check the send status of schedule {scheduleId} on grant {grant_id}.
        slots:
          scheduleId: path.scheduleId
          grant_id: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/messages/schedules/{scheduleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a scheduled email before it sends
      effect: destructive
      questions:
      - How do I stop a scheduled email from going out?
      - How close to the send time can I still cancel a scheduled message?
      instructions:
      - text: Cancel scheduled message {scheduleId} in mailbox {grant_id}.
        slots:
          scheduleId: path.scheduleId
          grant_id: path.grant_id
      - text: Unschedule send {scheduleId} for grant {grant_id} so it never goes out.
        slots:
          scheduleId: path.scheduleId
          grant_id: path.grant_id
      method: generated
      generated: '2026-09-26'