Overview

Nylas is a powerful unified API platform that provides developers like you with tools to integrate email, calendar, and contact functionality into your applications across multiple providers like Gmail, Microsoft, IMAP, and others. Nylas also supports webhooks, which allow applications to receive real-time updates on changes in emails, calendars, and contacts.

If you’re a first-time user, sign up for a free Nylas account first! 😎

In free tier, Nylas automatically creates a Sandbox application for you. Sandbox app allows you to connect up to 5 accounts or grants and provides pre-configured Google and Microsoft connector for easy testing.

A grant is a record of a specific user’s account authenticating with their provider, and “granting” Nylas access to parts of the account’s email inbox and calendar (represented by authentication “scopes”). Grants and connected accounts are often used interchangeably.
Connectors are provider integrations that allows your Nylas application to connect to a third party services, such as a provider auth application from Google (GCP), Microsoft (Azure), or to an IMAP provider. You can update the scopes that Nylas requests when connecting to that provider under connector settings.

Make an API request or two

Get a list of account’s calendars

The Get all Calendars request fetches information about all of the calendars that the test account has access to, but doesn’t fetch the events that the calendar contains.

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": [
    {
      "description": "Jane Doe's work calendar",
      "hex_color": "#039BE5",
      "hex_foreground_color": "#039BE5",
      "id": "5d3qmne77v32r8l4phyuksl2x",
      "is_owned_by_user": true,
      "is_primary": true,
      "location": "Los Angeles, CA",
      "metadata": {
        "your-key": "value"
      },
      "name": "Jane Doe (work)",
      "object": "calendar",
      "read_only": false,
      "timezone": "America/Los_Angeles"
    }
  ],
  "next_cursor": "CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4="
}

Return all Events on a calendar

Using the id of a specific calendar, you can make a Get all Events request to see what’s in it. This might be a long list, so you can also include the limit parameter to show only the first few events, or step through several pages of results.

curl --request GET \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID> \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": [
    {
      "busy": true,
      "calendar_id": "7d93zl2palhxqdy6e5qinsakt",
      "created_at": 1661874192,
      "description": "Jane Stevens's personal calendar",
      "hide_participants": false,
      "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
      "html_link": "https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Ef3feD2VuM29fMjAyMjA2MjdUMjIwMDAwWiBoYWxsYUBueWxhcy5jb20",
      "id": "5d3qmne77v32r8l4phyuksl2x",
      "location": "Roller Rink",
      "object": "event",
      "organizer": {
        "email": "[email protected]",
        "name": "Jane Stevens"
      },
      "participants": [
        {
          "comment": "I'll be there.",
          "email": "[email protected]",
          "name": "Aristotle Williams",
          "phone_number": "+1 23456778",
          "status": "yes"
        },
        {
          "comment": "can't make it, sorry!",
          "email": "[email protected]",
          "name": "Belinda Williams",
          "phone_number": "+1 23456778",
          "status": "no"
        }
      ],
      "read_only": false,
      "status": "confirmed",
      "title": "Surprise Birthday Party for John",
      "updated_at": 1661874192,
      "visibility": "private",
      "when": {
        "time": 1661874192,
        "timezone": "America/New_York"
      }
    }
  ],
  [
    {
      "busy": true,
      "calendar_id": "7d93zl2palhxqdy6e5qinsakt",
      "created_at": 1661888882,
      "description": "Jane Stevens's personal calendar",
      "hide_participants": true,
      "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
      "html_link": "https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Ef3feD2VuM29fMjAyMjA2MjdUMjIwMASDDiBoYWxsYUBueWxhcy5jb20",
      "id": "5d3qmne77v32r8l4phyluksl2x",
      "location": "Flow Studios, Los Angeles",
      "object": "event",
      "organizer": {
        "email": "[email protected]",
        "name": "Flow Studios scheduler"
      },
      "participants": [{
        "comment": "See you then!",
        "email": "[email protected]",
        "name": "Jane Stevens",
        "phone_number": "+1 23456778",
        "status": "yes"
      }],
      "read_only": true,
      "status": "confirmed",
      "title": "Flow Studios - Intermediate Vinyassa",
      "updated_at": 1661874192,
      "visibility": "private",
      "when": {
        "time": 1661874192,
        "timezone": "America/New_York"
      }
    }
  ]
  "next_cursor": "CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4="
}

Create an event

Right, we found the calendar and looked at the Events that are already on it. Now it’s time to create a new Event.

You can copy and paste the example request below into your terminal and replace the CALENDAR_ID at the end of the request with the calendar ID from the previous example. If you want, you can also set it to primary to put the Event on the test account’s main calendar.

Remember to change the when parameter to some time in the future. The parameter is in Unix timestamp format, so you might want to use an online tool or software library to convert it.

The participants object lists the people that you’re inviting to the event. By default, Nylas creates the Event on the calendar that you specify for the test account, so you don’t need to add the account’s information to the participants list.

Remember, anyone you put in the participants list gets an event on their calendar! (You could add the ?notify_participants=false parameter string after the calendar ID, but not all providers respect it.)

curl --request POST \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID> \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Annual Philosophy Club Meeting",
    "busy": true,
    "participants": [
      {
        "name": "Aristotle",
        "email": "[email protected]"
      },
      {
        "name": "Jane Stephens",
        "email": "[email protected]"
      }
    ],
    "resources": [
      {
        "name": "Conference room",
        "email": "[email protected]"
      }
    ],
    "description": "Come ready to talk philosophy!",
    "when": {
        "start_time": 1674604800,
        "end_time": 1722382420,
        "start_timezone": "America/New_York",
        "end_timezone": "America/New_York"
    },
    "location": "New York Public Library, Cave room",
    "recurrence": [
      "RRULE:FREQ=WEEKLY;BYDAY=MO",
      "EXDATE:20211011T000000Z"
  ],
}'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "title": "Annual Philosophy Club Meeting",
    "status": "confirmed",
    "busy": true,
    "calendar_id": "7d93zl2palhxqdy6e5qinsakt",
    "created_at": 1699488370,
    "description": "Come ready to talk philosophy!",
    "hide_participants": false,
    "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
    "html_link": "https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Efasdfa2VuM29fMjAyMjA2MjdUMjIwMDAwWiBoYWxsYUBueWxhcy5jb20",
    "id": "5d3qmne77v32r8l4phyuksl2x",
    "location": "New York Public Library, Cave room",
    "object": "event",
    "organizer": {
      "email": "[email protected]",
      "name": "Your test account"
    },
    "participants": [
      {
        "email": "[email protected]",
        "name": "Aristotle",
        "phone_number": "+1 23456778",
        "status": "noreply"
      },
      {
        "email": "[email protected]",
        "name": "Jane Stephens",
        "phone_number": "+1 23456778",
        "status": "noreply"
      }
    ],
    "read_only": false,
    "reminders": {
      "use_default": false,
      "overrides": [
        {
          "reminder_minutes": 10,
          "reminder_method": "email"
        }
      ]
    },
    "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO", "EXDATE:20211011T000000Z"],
    "updated_at": 1699661170,
    "visibility": "private",
    "when": {
      "time": 1700060400,
      "timezone": "America/New_York"
    }
  }
}

Get unread email messages

Moving out of calendar land, let’s take a look at email.

Let’s fetch the two most recent unread email messages. You can specify these limits using the ?limit=2&unread=true query string parameters, as in the example request below.

There are lots of other limits and filters available. For a full list, see the Get all Messages references.

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?limit=2&unread=true' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": [
    {
      "body": "Remember to schedule your followup appointment at the cookery clinic.",
      "date": 1635355739,
      "from": [{
        "name": "Bad Baker's Cookery Clinic",
        "email": "[email protected]"
      }],
      "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
      "id": "5d3qmne77v32r8l4phyuksl2x",
      "object": "message",
      "reply_to": [{
        "name": "Bad Baker's Cookery Clinic",
        "email": "[email protected]"
      }],
      "snippet": "Reminder! Schedule your appointment...",
      "starred": true,
      "subject": "Thanks for visiting! Schedule your follow up",
      "thread_id": "1t8tv3890q4vgmwq6pmdwm8qgsaer",
      "to": [
        {
          "name": "Your test account",
          "email": "[email protected]"
        },
        {
          "name": "Jane Stephens",
          "email": "[email protected]"
        },
      ],
      "unread": true
    }
  ],
  [
    {
      "body": "Please unsubscribe me from this list. My pie baking is exceptional, and I don't know how you got my email address.",
      "date": 1635355739,
      "from": [{
        "name": "Jane Stephens",
        "email": "[email protected]"
      }],
      "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
      "id": "5d3qmne77v32r8l4phyuksl2x",
      "object": "message",
      "reply_to": [{
        "name": "Jane Stephens",
        "email": "[email protected]"
      }],
      "snippet": "Please unsubscribe me",
      "starred": true,
      "subject": "Re: Thanks for visiting! Schedule your follow up",
      "thread_id": "1t8tv3890q4vgmwq6pmdwm8qgsaer",
      "to": [
        {
          "name": "Bad Baker's Cookery Clinic",
          "email": "[email protected]"
        },
        {
          "name": "Your test account",
          "email": "[email protected]"
        }
      ],
      "unread": true
    }
  ],
  "next_cursor": "CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4="
}

Send an email message

Next, you’ll send an email message to yourself using the Send Message API.

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 World! Sent with Nylas",
    "body": "Hello and welcome! You just sent your first email with Nylas!",
    "to": [{
      "name": "John Doe",
      "email": "[email protected]"
    }],
    "cc": [{
      "name": "Jane Stephens"
      "email: "[email protected]"
    }]
  }'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "grant_id": "your grant_id",
  "data": {
    "subject": "Hello World! Sent with Nylas",
    "body": "Hello and welcome! You just sent your first email with Nylas!",
    "from": [
      {
        "name": "Sender name appears here",
        "email": "[email protected]"
      }
    ],
    "to": [
      {
        "name": "John Doe",
        "email": "[email protected]"
      }
    ],
    "cc": [
      {
        "name": "Jane Stephens",
        "email": "[email protected]"
      }
    ],
    "reply_to_message_id": "",
    "schedule_id": ""
  }
}

What’s next?

Here are some alternate paths you can also take:

Use the Nylas AI Prompts to get started with Nylas using AI tools like Cursor, GitHub Copilot, Windsurf, or Zed.
Visit the Tutorials section for follow-along tutorials that cover basic API use cases for the Nylas Node.js, Python, Ruby, and Kotlin/Java SDKs.
If you’re ready to start integrating Nylas into your project, check out Developing with Nylas for a start-to-finish guide. You’ll pick a Nylas plan, create a new application, and set up authentication so you can start building your real project.
Try out the Nylas Postman collection. For more information, read Nylas’ Postman collection documentation.
Join Nylas’ developer forums to learn about Nylas APIs, get help, attend events, and support others in the community.

But first, let’s sign up