Using the Smart Compose endpoints

For many people, writing clear, concise, grammatically correct, and well-structured messages can take a lot of time. Writing isn’t everyone’s superpower — and it doesn’t need to be. With Nylas’ Smart Compose endpoint, users can generate well-written messages in a few seconds, based only on prompts and email context.

Currently, Smart Compose can…

• Generate new messages (for example, “Write an email to Ron with a business brief about Nylas”).
• Respond to messages (for example, “Reply to my friend Emily and RSVP yes to the party”).

Before you begin

Before you start making Smart Compose requests, you need the following prerequisites:

• A Nylas application.
• A provider auth app (Google or Azure), and a connector for that auth app.
• A Google or Microsoft grant.

Make sure your project includes a field where your users can type instructions for the AI. Otherwise, they won’t be able to use Smart Compose.

Generate a new message

To generate a new email message using Smart Compose, make a Generate new message request with a natural language prompt.

cURLNode.js SDKPython SDKRuby SDKJava SDKKotlin SDKCLI

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function composeEmail() {
  try {
    const message = await nylas.messages.smartCompose.composeMessage({
      identifier: "<NYLAS_GRANT_ID>",
      requestBody: {
        prompt: "Tell my colleague how we can use Nylas APIs",
      },
    });

    console.log("Message created:", message);
  } catch (error) {
    console.error("Error creating message:", error);
  }
}

composeEmail();

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
email = "<EMAIL>"

message = nylas.messages.smart_compose.compose_message(
  grant_id,
  request_body={
    "prompt": "Tell my colleague how we can use Nylas APIs",
  }
)

print(message)

require 'nylas'

nylas = Nylas::Client.new(
  api_key: "<NYLAS_API_KEY>"
)

request_body = {
    prompt: 'Let''s talk about Nylas'
}

message, _ = nylasnylas.messages.smart_compose.compose_message(identifier: "<NYLAS_GRANT_ID>",
request_body: request_body)
puts message[:suggestion]

import com.nylas.NylasClient;
import com.nylas.models.*;

public class SmartCompose {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    ComposeMessageRequest requestBody = new ComposeMessageRequest("Let's talk about Nylas");
    Response<ComposeMessageResponse> message = nylas.messages().smartCompose().composeMessage("<NYLAS_GRANT_ID>", requestBody);

    System.out.println(message.getData().getSuggestion());
  }
}

import com.nylas.NylasClient
import com.nylas.models.ComposeMessageRequest

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(
      apiKey = "<NYLAS_API_KEY>"
  )

  val requestBody : ComposeMessageRequest = ComposeMessageRequest("Let's talk about Nylas")
  val message = nylas.messages().smartCompose().composeMessage("<NYLAS_GRANT_ID>", requestBody)

  print(message.data.suggestion)
}

nylas email smart-compose \
  --prompt "Write an email to Ron with a business brief about Nylas"

The Nylas CLI runs commands against your default grant. Run nylas auth list to see your connected accounts and nylas auth switch <email> to change which one commands run against.

The response includes a suggestion field containing the generated message body, which you can then pass to the Send Message endpoint or pre-fill into a draft for the user to review.

Respond to a message

To generate a reply to an existing email, make a Generate reply request that includes the message_id of the email you want to reply to. Nylas uses the original message as context so the reply fits the conversation.

cURLNode.js SDKPython SDKRuby SDKJava SDKKotlin SDKCLI

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function composeEmailReply() {
  try {
    const message = await nylas.messages.smartCompose.composeMessageReply({
      identifier: "<NYLAS_GRANT_ID>",
      messageId: "<MESSAGE_ID>",
      requestBody: {
        prompt: "Respond to the email",
      },
    });

    console.log("Message created:", message);
  } catch (error) {
    console.error("Error creating message:", error);
  }
}

composeEmailReply();

from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
message_id = "<MESSAGE_ID>"

message = nylas.messages.smart_compose.compose_message_reply(
  grant_id,
  message_id,
  request_body={
    "prompt": "Respond to the email",
  }
)

print(message)

require 'nylas'

nylas = Nylas::Client.new(
    api_key: "<NYLAS_API_KEY>"
)

request_body = {
  prompt: 'reply'
}

message, _ = nylas.nylas.messages.smart_compose.compose_message_reply(identifier: "<NYLAS_GRANT_ID>",
    message_id: "<MESSAGE_ID>",
    request_body: request_body)

puts message[:suggestion]

import com.nylas.NylasClient;
import com.nylas.models.*;

public class SmartCompose {
    public static void main(String[] args) throws
            NylasSdkTimeoutError, NylasApiError {

        NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

        ComposeMessageRequest requestBody = new ComposeMessageRequest("Reply");

        Response<ComposeMessageResponse> message =
        nylas.messages().smartCompose().composeMessageReply("<NYLAS_GRANT_ID>",
        "<MESSAGE_ID>", requestBody);
        System.out.println(message.getData().getSuggestion());
    }
}

import com.nylas.NylasClient
import com.nylas.models.ComposeMessageRequest

fun main(args: Array<String>) {

    val nylas: NylasClient = NylasClient(
        apiKey = "<NYLAS_API_KEY>"
    )

    val requestBody : ComposeMessageRequest =
    ComposeMessageRequest("Reply")
    val message = nylas.messages().smartCompose().composeMessageReply("<NYLAS_GRANT_ID>",
    "<MESSAGE_ID>", requestBody)
    print(message.data.suggestion)

}

nylas email smart-compose \
  --prompt "Reply to my friend Emily and RSVP yes to the party" \
  --message-id "<MESSAGE_ID>"

Response options

Nylas’ Smart Compose endpoints support two ways to get AI responses: you can either receive them as a REST response in a single JSON blob, or use SSE (Server-Sent Events) to stream the response tokens as Nylas receives them.

To receive responses using the REST method, either add the Accept: application/json header to your request, or omit the Accept header entirely.

To enable SSE, add the Accept: text/event-stream to your Smart Compose request. Your project must be able to accept streaming events and render them for your user.

Smart Compose limitations

Keep the following limitations in mind as you work with Nylas Smart Compose:

• Latency varies depending on the length and complexity of the prompt. You might want to add a “working” indicator to your UI so your users know to wait for a response.
• Prompts sent to the Nylas LLM can be up to 1,000 tokens long. Longer queries receive an error message.
  • For more information about LLM tokens, see the official Microsoft documentation.

Pair Smart Compose with email signatures. After generating a message body with Smart Compose, pass a signature_id when sending the message to automatically append a professional signature. See Using email signatures to get started.