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:
-
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.
🗣️ This page was written by the Nylas Docs Team, and we'd love to hear your feedback. Drop us a line!