Try even more APIs!
Now that you have your grant set up, you're ready to use the Nylas APIs!
If you're just joining us on this page, you should do the following before you begin:
- Sign up for a Nylas account
- Sign in to the v3 Dashboard and create a Sandbox Nylas application.
- Generate an API key for your Sandbox and save it.
- Connect an email account, create a Grant, and save the Grant ID.
💡 For each of the following examples, you can replace the NYLAS_API_KEY with your API key, and the NYLAS_GRANT_ID with the Grant ID for your test Grant. 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 the test 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.
Most users have access to more than one calendar, and calendars can have different levels of access permissions. One of the calendars is marked by the provider as primary, meaning it's the main calendar associated with that account. Each calendar also has an id, which you can use to refer to it in other API calls.
The request below allows you to see the calendars the user can access. The response shows a pagination cursor which tells you there are more calendars available - we just omitted them for this example.
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
After you find 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 so you didn't have three pages for two events. 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": "[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 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": "[email protected]"
},
{
"name": "Jane Stephens",
"email": "[email protected]"
}
],
"description": "Come ready to talk philosophy!",
"when": {
"time": 1700060400
},
"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.
Even test accounts can receive a lot of email, so let's start with a tightly scoped request that gets only two 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": "[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.
⚠️ 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": "[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": ""
}
} 💡 For bonus points: Re-query the messages endpoint to see this new message!
Ready to move on and see what else we've got in store?