Quickstart: Email API

The Nylas Email API lets you send, read, and search email across Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP — all through a single API. Instead of building separate integrations for each provider, you write your code once and Nylas handles the differences.

This quickstart walks you through sending and reading email on behalf of a connected user using the Nylas SDKs and API.

Before you begin

You need two things from Nylas to make API calls:

1. An API key — authenticates your application. You’ll pass it as a Bearer token.
2. A grant ID — identifies which user’s email account to act on. You get one when you connect an email account to Nylas.

If you don’t have these yet, follow one of the setup guides first:

• Get started with the CLI — run nylas init to create an account, generate an API key, and connect a test email account in one command.
• Get started with the Dashboard — do the same steps through the web UI.

Then install the Nylas SDK for your language:

Node.jsPythonRuby

npm install nylas

pip install nylas

gem install nylas

For Java and Kotlin, see the Kotlin/Java SDK setup guide.

How grants work. Each connected email account becomes a grant with a unique grant ID. In production, your users authenticate through Nylas OAuth and each gets their own grant. For this quickstart, you’ll use the test grant you created during setup.

Send your first email

Replace <NYLAS_GRANT_ID> and <NYLAS_API_KEY> with the values from setup. Change the to address to your own email so you can see it arrive.

curlNode.jsPythonRubyCLIJavaKotlin

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "Hello from Nylas",
    "body": "Sent using the Nylas Email API",
    "to": [{ "name": "Test", "email": "[email protected]" }]
  }'

import Nylas from "nylas";

const nylas = new Nylas({ apiKey: process.env.NYLAS_API_KEY });

const message = await nylas.messages.send({
  identifier: process.env.NYLAS_GRANT_ID,
  requestBody: {
    to: [{ name: "Test", email: "[email protected]" }],
    subject: "Hello from Nylas",
    body: "Sent using the Nylas Email API",
  },
});

console.log("Sent:", message.data.id);

import os
from nylas import Client

nylas = Client(os.environ["NYLAS_API_KEY"])

message = nylas.messages.send(
    os.environ["NYLAS_GRANT_ID"],
    request_body={
        "to": [{"name": "Test", "email": "[email protected]"}],
        "subject": "Hello from Nylas",
        "body": "Sent using the Nylas Email API",
    },
)

print("Sent:", message.data.id)

require 'nylas'

nylas = Nylas::Client.new(api_key: ENV['NYLAS_API_KEY'])

message, _ = nylas.messages.send(
  identifier: ENV['NYLAS_GRANT_ID'],
  request_body: {
    to: [{ name: 'Test', email: '[email protected]' }],
    subject: 'Hello from Nylas',
    body: 'Sent using the Nylas Email API'
  }
)

puts "Sent: #{message[:id]}"

nylas email send \
  --to [email protected] \
  --subject "Hello from Nylas" \
  --body "Sent using the Nylas Email API"

import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.List;

public class SendEmail {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    SendMessageRequest requestBody = new SendMessageRequest.Builder(
        List.of(new EmailName("[email protected]", "Test"))
    )
        .subject("Hello from Nylas")
        .body("Sent using the Nylas Email API")
        .build();

    Response<Message> message = nylas.messages().send("<NYLAS_GRANT_ID>", requestBody);
    System.out.println("Sent: " + message.getData().getId());
  }
}

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

fun main() {
    val nylas = NylasClient(apiKey = "<NYLAS_API_KEY>")

    val requestBody = SendMessageRequest.Builder(
        listOf(EmailName("[email protected]", "Test"))
    )
        .subject("Hello from Nylas")
        .body("Sent using the Nylas Email API")
        .build()

    val message = nylas.messages().send("<NYLAS_GRANT_ID>", requestBody)
    println("Sent: ${message.data.id}")
}

Check the recipient’s inbox — the message should arrive within a few seconds. That same code works whether the grant is a Gmail account, Outlook, or any other supported provider.

Read a user’s inbox

List the five most recent messages from a connected user’s account.

curlNode.jsPythonRubyJavaKotlinCLIResponse

curl --compressed --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?limit=5" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

import Nylas from "nylas";

const nylas = new Nylas({ apiKey: process.env.NYLAS_API_KEY });

const messages = await nylas.messages.list({
  identifier: process.env.NYLAS_GRANT_ID,
  queryParams: { limit: 5 },
});

messages.data.forEach((msg) => {
  console.log(`${msg.subject} -- from ${msg.from?.[0]?.email}`);
});

import os
from nylas import Client

nylas = Client(os.environ["NYLAS_API_KEY"])

messages = nylas.messages.list(
    os.environ["NYLAS_GRANT_ID"],
    query_params={"limit": 5},
)

for msg in messages.data:
    print(f"{msg.subject} -- from {msg.from_[0].email}")

require 'nylas'

nylas = Nylas::Client.new(api_key: ENV['NYLAS_API_KEY'])

messages, _ = nylas.messages.list(
  identifier: ENV['NYLAS_GRANT_ID'],
  query_params: { limit: 5 }
)

messages.each do |msg|
  puts "#{msg[:subject]} -- from #{msg[:from][0][:email]}"
end

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

public class ListMessages {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    ListMessagesQueryParams queryParams = new ListMessagesQueryParams.Builder().limit(5).build();
    ListResponse<Message> messages = nylas.messages().list("<NYLAS_GRANT_ID>", queryParams);

    for (Message msg : messages.getData()) {
      System.out.println(msg.getSubject() + " -- from " + msg.getFrom().get(0).getEmail());
    }
  }
}

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

fun main() {
    val nylas = NylasClient(apiKey = "<NYLAS_API_KEY>")

    val queryParams = ListMessagesQueryParams(limit = 5)
    val messages = nylas.messages().list("<NYLAS_GRANT_ID>", queryParams).data

    for (msg in messages) {
        println("${msg.subject} -- from ${msg.from?.firstOrNull()?.email}")
    }
}

nylas email list --limit 5

{
  "request_id": "d0c951b9-61db-4daa-ab19-cd44afeeabac",
  "data": [
    {
      "starred": false,
      "unread": true,
      "folders": ["UNREAD", "CATEGORY_PERSONAL", "INBOX"],
      "grant_id": "1",
      "date": 1706811644,
      "attachments": [
        {
          "id": "1",
          "grant_id": "1",
          "filename": "invite.ics",
          "size": 2504,
          "content_type": "text/calendar; charset=\"UTF-8\"; method=REQUEST"
        },
        {
          "id": "2",
          "grant_id": "1",
          "filename": "invite.ics",
          "size": 2504,
          "content_type": "application/ics; name=\"invite.ics\"",
          "is_inline": false,
          "content_disposition": "attachment; filename=\"invite.ics\""
        }
      ],
      "from": [
        {
          "name": "Nylas DevRel",
          "email": "[email protected]"
        }
      ],
      "id": "1",
      "object": "message",
      "snippet": "Send Email with Nylas APIs",
      "subject": "Learn how to Send Email with Nylas APIs",
      "thread_id": "1",
      "to": [
        {
          "name": "Nyla",
          "email": "[email protected]"
        }
      ],
      "created_at": 1706811644,
      "body": "Learn how to send emails using the Nylas APIs!"
    }
  ],
  "next_cursor": "123"
}

Search a user’s messages

The search_query_native parameter uses each provider’s native search syntax (Gmail search operators, Microsoft KQL, etc.), so it works the way your users expect regardless of their email provider.

curlNode.jsPythonRubyJavaKotlinCLI

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?search_query_native=from:[email protected]&limit=5" \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

const results = await nylas.messages.list({
  identifier: process.env.NYLAS_GRANT_ID,
  queryParams: {
    search_query_native: "from:[email protected]",
    limit: 5,
  },
});

console.log(`Found ${results.data.length} messages`);

results = nylas.messages.list(
    os.environ["NYLAS_GRANT_ID"],
    query_params={
        "search_query_native": "from:[email protected]",
        "limit": 5,
    },
)

print(f"Found {len(results.data)} messages")

results, _ = nylas.messages.list(
  identifier: ENV['NYLAS_GRANT_ID'],
  query_params: {
    search_query_native: 'from:[email protected]',
    limit: 5
  }
)

puts "Found #{results.length} messages"

ListMessagesQueryParams searchParams = new ListMessagesQueryParams.Builder()
    .searchQueryNative("from:[email protected]")
    .limit(5)
    .build();

ListResponse<Message> results = nylas.messages().list("<NYLAS_GRANT_ID>", searchParams);
System.out.println("Found " + results.getData().size() + " messages");

val searchParams = ListMessagesQueryParams(
    searchQueryNative = "from:[email protected]",
    limit = 5
)

val results = nylas.messages().list("<NYLAS_GRANT_ID>", searchParams).data
println("Found ${results.size} messages")

nylas email search "from:[email protected]" --limit 5

You can also filter by standard fields like from, to, subject, and received_after without relying on provider-specific syntax. See the Messages API reference for all available filters.

What’s next

• Authentication — set up OAuth so your users can connect their accounts
• Webhooks — get notified in real-time when new messages arrive
• Provider-specific guides — Gmail, Microsoft, Yahoo, iCloud, and IMAP deep dives
• Messages API reference — full endpoint documentation
• Send email from the terminal — quick testing with the Nylas CLI