Nylas Smart compose API

openapi: 3.2.0
info:
  title: Nylas Smart compose API
  version: v3
  summary: The complete Nylas v3 API — Email, Calendar, Contacts, Notetaker, Scheduling, Administration, and Migration.
  description: The Nylas API is designed using the REST ideology to provide simple and predictable URIs to access and modify objects. Requests support standard HTTP methods like `GET`, `PUT`, `POST`, and `DELETE`, and standard status codes. Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise. You can use the Nylas Postman collection to quickly start using the Nylas APIs. For more information, check out the Nylas Postman collection documentation.
  contact:
    url: https://www.nylas.com/
servers:
- url: https://api.us.nylas.com
  description: U.S.
- url: https://api.eu.nylas.com
  description: E.U.
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
tags:
- name: Smart compose
  description: 'The Smart Compose endpoints extend the Nylas Messages API. Currently, Smart Compose supports only two methods of getting AI responses: you can either receive them as a REST response in a single JSON blob, or use server-sent events (SSE) to stream the response tokens as Nylas receives them.


    If you want to receive responses using the REST method, add the `Accept: application/json` header. Nylas will return a single JSON blob. If you use this method, you might want to add a "working" indicator to your UI, as response times may vary.


    To enable SSE for a request, add the `Accept: text/event-stream` header.


    For more information, see the Smart Compose documentation.


    ## Smart Compose scopes


    The table below lists the Smart Compose endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.


    The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you''re already using one of the permissive scopes, you don''t need to add the more restrictive scope.


    | Endpoint | Google Scopes

    `https://www.googleapis.com/auth/...` | Microsoft Scopes

    `https://graph.microsoft.com/...` |

    | :------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------- |

    | **POST** `/messages/smart-compose`

    **POST** `/messages//smart-compose` | `/gmail.readonly` ☑️

    `/gmail.modify` | `Mail.Read` ☑️

    `Mail.ReadWrite`

    `Mail.ReadWrite.Shared`

    `Mail.Read.Shared` |


    For more information about scopes, see Using scopes to request user data.'
paths:
  /v3/grants/{grant_id}/messages/smart-compose:
    parameters:
    - schema:
        type: string
      name: grant_id
      in: path
      required: true
      description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
    post:
      summary: Compose a message
      tags:
      - Smart compose
      x-scopes:
        google:
          min: https://www.googleapis.com/auth/gmail.readonly
          others: https://www.googleapis.com/auth/gmail.modify
        microsoft:
          min: https://graph.microsoft.com/Mail.Read
          others:
          - https://graph.microsoft.com/Mail.ReadWrite
          - https://graph.microsoft.com/Mail.ReadWrite.Shared
          - https://graph.microsoft.com/Mail.Read.Shared
        yahoo:
          min: email, mail-r, mail-w
      responses:
        '200':
          $ref: '#/components/responses/smart_compose_200'
        '400':
          $ref: '#/components/responses/smart_compose_400'
        '401':
          $ref: '#/components/responses/401'
        '422':
          $ref: '#/components/responses/smart_compose_422'
        '500':
          $ref: '#/components/responses/smart_compose_500'
      operationId: post-smart-compose
      description: Generates a message based on a prompt.
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
      requestBody:
        $ref: '#/components/requestBodies/smart_compose'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request POST \\\n  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n  --header 'Content-Type: application/json'"
      - lang: javascript
        label: Node.js SDK
        source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n  apiKey: \"<NYLAS_API_KEY>\",\n  apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function composeEmail() {\n  try {\n    const message = await nylas.messages.smartCompose.composeMessage({\n      identifier: \"<NYLAS_GRANT_ID>\",\n      requestBody: {\n        prompt: \"Tell my colleague how we can use Nylas APIs\",\n      },\n    });\n\n    console.log(\"Message created:\", message);\n  } catch (error) {\n    console.error(\"Error creating message:\", error);\n  }\n}\n\ncomposeEmail();\n"
      - lang: python
        label: Python SDK
        source: "from nylas import Client\n\nnylas = Client(\n    \"<NYLAS_API_KEY>\",\n    \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nemail = \"<EMAIL>\"\n\nmessage = nylas.messages.smart_compose.compose_message(\n  grant_id,\n  request_body={\n    \"prompt\": \"Tell my colleague how we can use Nylas APIs\",\n  }\n)\n\nprint(message)"
      - lang: ruby
        label: Ruby SDK
        source: "require 'nylas'\n\nnylas = Nylas::Client.new(\n  api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n  prompt: \"Let's talk about Nylas\"\n}\n\nmessage, _ = nylas.messages.smart_compose.compose_message(\n  identifier: \"<NYLAS_GRANT_ID>\",\n  request_body: request_body\n)\n\nputs message[:suggestion]\n"
      - lang: java
        label: Java SDK
        source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class SmartCompose {\n  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n    NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n    ComposeMessageRequest requestBody = new ComposeMessageRequest(\"Let's talk about Nylas\");\n    Response<ComposeMessageResponse> message = nylas.messages().smartCompose().composeMessage(\"<NYLAS_GRANT_ID>\", requestBody);\n    \n    System.out.println(message.getData().getSuggestion());\n  }\n}\n"
      - lang: kotlin
        label: Kotlin SDK
        source: "import com.nylas.NylasClient\nimport com.nylas.models.ComposeMessageRequest\n\nfun main(args: Array<String>) {\n  val nylas: NylasClient = NylasClient(\n      apiKey = \"<NYLAS_API_KEY>\"\n  )\n\n  val requestBody : ComposeMessageRequest = ComposeMessageRequest(\"Let's talk about Nylas\")\n  val message = nylas.messages().smartCompose().composeMessage(\"<NYLAS_GRANT_ID>\", requestBody)\n  \n  print(message.data.suggestion)\n}\n"
  /v3/grants/{grant_id}/messages/{message_id}/smart-compose:
    parameters:
    - schema:
        type: string
      name: grant_id
      in: path
      required: true
      description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
    - schema:
        type: string
      name: message_id
      in: path
      required: true
      description: 'ID of the message to access. Nylas recommends you URL-encode this field, or you might receive

        a [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for

        example, `#`).'
    post:
      summary: Compose a reply
      tags:
      - Smart compose
      x-scopes:
        google:
          min: https://www.googleapis.com/auth/gmail.readonly
          others: https://www.googleapis.com/auth/gmail.modify
        microsoft:
          min: https://graph.microsoft.com/Mail.Read
          others:
          - https://graph.microsoft.com/Mail.ReadWrite
          - https://graph.microsoft.com/Mail.ReadWrite.Shared
          - https://graph.microsoft.com/Mail.Read.Shared
        yahoo:
          min: email, mail-r, mail-w
      responses:
        '200':
          $ref: '#/components/responses/smart_compose_200'
        '400':
          $ref: '#/components/responses/smart_compose_400'
        '401':
          $ref: '#/components/responses/401'
        '422':
          $ref: '#/components/responses/smart_compose_422'
        '500':
          $ref: '#/components/responses/smart_compose_500'
      operationId: post-smart-compose-reply
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
      requestBody:
        $ref: '#/components/requestBodies/smart_compose'
      description: Generates a reply to the specified message based on a prompt.
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request POST \\\n  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n  --header 'Content-Type: application/json'"
      - lang: javascript
        label: Node.js SDK
        source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n  apiKey: \"<NYLAS_API_KEY>\",\n  apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function composeEmailReply() {\n  try {\n    const message = await nylas.messages.smartCompose.composeMessageReply({\n      identifier: \"<NYLAS_GRANT_ID>\",\n      messageId: \"<MESSAGE_ID>\",\n      requestBody: {\n        prompt: \"Respond to the email\",\n      },\n    });\n\n    console.log(\"Message created:\", message);\n  } catch (error) {\n    console.error(\"Error creating message:\", error);\n  }\n}\n\ncomposeEmailReply();\n"
      - lang: python
        label: Python SDK
        source: "from nylas import Client\n\nnylas = Client(\n    \"<NYLAS_API_KEY>\",\n    \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nmessage_id = \"<MESSAGE_ID>\"\n\nmessage = nylas.messages.smart_compose.compose_message_reply(\n  grant_id,\n  message_id,\n  request_body={\n    \"prompt\": \"Respond to the email\",\n  }\n)\n\nprint(message)\n"
      - lang: ruby
        label: Ruby SDK
        source: "require 'nylas'\n\nnylas = Nylas::Client.new(\n  api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n  prompt: 'reply'\n}\n\nmessage, _ = nylas.messages.smart_compose.compose_message_reply(\n  identifier: \"<NYLAS_GRANT_ID>\",\n  message_id: \"<MESSAGE_ID>\",\n  request_body: request_body\n)\n\nputs message[:suggestion]\n"
      - lang: java
        label: Java SDK
        source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class SmartCompose {\n    public static void main(String[] args) throws\n            NylasSdkTimeoutError, NylasApiError {\n\n        NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n        ComposeMessageRequest requestBody = new ComposeMessageRequest(\"Reply\");\n\n        Response<ComposeMessageResponse> message = \n        nylas.messages().smartCompose().composeMessageReply(\"<NYLAS_GRANT_ID>\", \n        \"<MESSAGE_ID>\", requestBody);\n        System.out.println(message.getData().getSuggestion());\n    }\n}\n"
      - lang: kotlin
        label: Kotlin SDK
        source: "import com.nylas.NylasClient\nimport com.nylas.models.ComposeMessageRequest\n\nfun main(args: Array<String>) {\n\n    val nylas: NylasClient = NylasClient(\n        apiKey = \"<NYLAS_API_KEY>\"\n    )\n\n    val requestBody : ComposeMessageRequest = \n    ComposeMessageRequest(\"Reply\")\n    val message = nylas.messages().smartCompose().composeMessageReply(\"<NYLAS_GRANT_ID>\", \n    \"<MESSAGE_ID>\", requestBody)\n    print(message.data.suggestion)\n\n}\n"
components:
  responses:
    smart_compose_422:
      description: Validation Error
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: ID of the request
              error:
                type: object
                description: Response error object.
                properties:
                  type:
                    type: string
                    description: Error Type
                  message:
                    type: string
                    description: Error Message
                  details:
                    type: array
                    items:
                      type: object
                      properties:
                        loc:
                          title: Location
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: integer
                        msg:
                          title: Message
                          type: string
                        type:
                          title: Error Type
                          type: string
          examples:
            Validation Error:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: validation_error
                  message: validation error
                  details:
                  - loc:
                    - path
                    - item_id
                    msg: value is not a valid integer
                    type: type_error.integer
    smart_compose_400:
      description: Bad Request
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: ID of the request
              error:
                type: object
                description: Response error object.
                properties:
                  type:
                    type: string
                    description: Error Type
                  message:
                    type: string
                    description: Error Message
          examples:
            Invalid Request:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: invalid_request_error
                  message: invalid request
            Prompt Required:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: prompt_required_error
                  message: prompt is required
            Prompt Not Allowed:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: prompt_not_allowed_error
                  message: prompt is not allowed
            Message ID Required:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: message_id_required_error
                  message: message ID is required
            Grant ID Required:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: grant_id_required_error
                  message: grant ID is required
            Unknown Message Sender Error:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: unknown_message_sender_error
                  message: could not determine message sender
    smart_compose_200:
      description: Returns a suggestion for a message
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/common_response'
            - properties:
                data:
                  $ref: '#/components/schemas/smart_compose_suggestion'
          example:
            request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
            data:
              suggestion: 'Dear John,


                I hope this email finds you well. I wanted to reach out and inform you about an exciting upcoming project that we will be working on together. This project has the potential to be a game-changer for our company, and I believe your expertise and skills will be invaluable to its success. I look forward to discussing the project with you further and hearing your input and ideas. Let''s make this project a resounding success!


                Best regards,

                [Your Name]'
        text/event-stream:
          schema:
            type: object
            format: event-stream
            properties:
              suggestion:
                type: string
    smart_compose_500:
      description: Unexpected Error
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: ID of the request
              error:
                type: object
                description: Response error object.
                properties:
                  type:
                    type: string
                    description: Error Type
                  message:
                    type: string
                    description: Error Message
          examples:
            Unexpected Error:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: unexpected_error
                  message: an unexepcted error has occurred
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The error from the provider.
          examples:
            Unauthorized:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: unauthorized
                  message: Unauthorized
                  provider_error:
                    code: 401
                    message: Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
  schemas:
    smart_compose_suggestion:
      title: PromptSuggestion
      required:
      - suggestion
      type: object
      properties:
        suggestion:
          title: Suggestion
          type: string
    common_response:
      properties:
        request_id:
          type: string
          description: The request ID.
        data:
          type: object
          description: The response object.
      example:
        request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
  requestBodies:
    smart_compose:
      content:
        application/json:
          schema:
            title: Smart Compose
            type: object
            description: A Smart Compose request.
            properties:
              prompt:
                title: Prompt
                description: The prompt that Smart Compose uses to generate a message suggestion.
                maxLength: 1000
                type: string
                example: Reply to John Doe about the upcoming project.
  securitySchemes:
    IAM_API_KEY:
      type: http
      scheme: bearer
      bearerFormat: IAM API key
      description: An active, unexpired IAM credential of type `api_key` whose principal is active, has an Organization resource binding, and has the required IAM management permission. Use an existing IAM credential with these permissions, or [create your first management credential in the Dashboard](/docs/v3/auth/nylas-iam/manage-principals-with-api/#create-a-management-credential-in-the-dashboard). Application API keys (including legacy API keys) and provider OAuth tokens cannot authorize IAM management endpoints.
    ACCESS_TOKEN:
      scheme: bearer
      type: http
      bearerFormat: NYLAS_ACCESS_TOKEN
      description: 'The Nylas **access token** for a specific grant. Issued as part of OAuth 2.1 flow token

        exchange.'
    NYLAS_API_KEY:
      scheme: bearer
      type: http
      bearerFormat: NYLAS_API_KEY
      description: 'The Nylas **API key** provides application-level access to APIs and all grants. You can

        generate these from the Dashboard. Learn more about [authorizing requests](/docs/v3/auth/).'
    SCHEDULER_SESSION_TOKEN:
      scheme: bearer
      type: http
      bearerFormat: Session ID
      description: The Nylas Scheduler **session ID** that Scheduler UI Components use to authorize API requests.
x-provenance:
  method: harvested
  publisher: Nylas
  source: https://developer.nylas.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)