Version:
Only show these results:

Overview

👋 We're glad you're here! To start your journey, sign up for access to Nylas.

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.

But first, let's sign up

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

💡 For the following curl examples, you can generate both the NYLAS_API_KEY and the NYLAS_GRANT_ID on Nylas dashboard. If you're using one of the Nylas SDKs, see that SDK's instructions for passing your credentials and Grant ID.

Get a list of account's calendars

The return all calendars request fetches information about all of the calendars that the test account has access to, but does not fetch the events the calendar contains.

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'   
{
  "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 use the return all Events endpoint 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.

🔍 Just so you know: JSON examples can get long, so we trimmed out some items on the example response. See the Events API documentation for a full schema.

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' \
  --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": "jane.stevens@example.com",
        "name": "Jane Stevens"
      },
      "participants": [
        {
          "comment": "I'll be there.",
          "email": "aristotle@example.com",
          "name": "Aristotle Williams",
          "phone_number": "+1 23456778",
          "status": "yes"
        },
        {
          "comment": "can't make it, sorry!",
          "email": "belinda@example.com",
          "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": "flowstudios@example.com",
        "name": "Flow Studios scheduler"
      },
      "participants": [{
        "comment": "See you then!",
        "email": "jane.stevens@example.com",
        "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 epoch time, 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' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Annual Philosophy Club Meeting",
    "status": "confirmed",
    "busy": true,
    "participants": [
      {
        "name": "Aristotle",
        "email": "aristotle@example.com"
      },
      {
        "name": "Jane Stephens",
        "email": "jane.stephens@example.com"
      }
    ],
    "resources": [
      {
        "name": "Conference room",
        "email": "conference-room@resources.google.com"
      }
    ],
    "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": "organizer@example.com",
      "name": "Your test account"
    },
    "participants": [
      {
        "email": "aristotle@example.com",
        "name": "Aristotle",
        "phone_number": "+1 23456778",
        "status": "noreply"
      },
      {
        "email": "jane.stephens@example.com",
        "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 Messages reference documentation.

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?limit=2&unread=true' \
  --header 'Accept: application/json' \
  --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": "cooks.clinic@example.com"
      }],
      "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
      "id": "5d3qmne77v32r8l4phyuksl2x",
      "object": "message",
      "reply_to": [{
        "name": "Bad Baker's Cookery Clinic",
        "email": "cooks.clinic@example.com"
      }],
      "snippet": "Reminder! Schedule your appointment...",
      "starred": true,
      "subject": "Thanks for visiting! Schedule your follow up",
      "thread_id": "1t8tv3890q4vgmwq6pmdwm8qgsaer",
      "to": [
        {
          "name": "Your test account",
          "email": "test.account@example.com"
        },
        {
          "name": "Jane Stephens",
          "email": "jane.stephens@example.com"
        },
      ],
      "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": "jane.stephens@example.com"
      }],
      "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
      "id": "5d3qmne77v32r8l4phyuksl2x",
      "object": "message",
      "reply_to": [{
        "name": "Jane Stephens",
        "email": "jane.stephens@example.com"
      }],
      "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": "cooks.clinic@example.com"
        },
        {
          "name": "Your test account",
          "email": "test.account@example.com"
        }
      ],
      "unread": true
    }
  ],
  "next_cursor": "CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4="
}

Send an email message

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

⚠️ Remember: This request sends a real email message, so make sure you're sending it to one of your own accounts.

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": "john.doe@example.com"
    }],
    "cc": [{
      "name": "Jane Stephens"
      "email: "jane.stephens@example.com"
    }]
  }'   
{
  "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": "sender@example.com"
    }],
    "to": [{
      "name": "John Doe",
      "email": "john.doe@example.com"
    }],
    "cc": [{
      "name": "Jane Stephens",
      "email": "jane.stephens@example.com"
    }],
    "reply_to_message_id": "",
    "schedule_id": ""
  }
}

What's next?

✨ Ready to code? We strongly recommend you to check out the Nylas Quickstart guides ! They'll give you a quick tour of Nylas by setting up a simple application including auth by using Nylas SDKs for Node.js, Python, Ruby, Java, or Kotlin.

Here are some alternate paths you can also take:

🗣️ This page was written by the Nylas Docs Team, and we'd love to hear your feedback. Drop us a line!