Only show these results:

Nylas Quickstart guides

👋 We're glad you're here! To start your journey, sign up for access to Nylas v3. A Nylas representative will contact you to help you along the way.

This page covers the steps to get you set up to try out Nylas v3. For your initial exploration we'll create a Sandbox Nylas application.

The Sandbox gives you a pre-configured authentication setup, so you can skip some configuration steps, create a test grant, and move on to trying out the APIs. When you're ready, you can work through the Develop with Nylas guide to set up your development environment.

For a quick start, you just need to...

  1. Create a v3 Sandbox application.
  2. Create an API key for your Sandbox.
  3. Create a test grant.

After you have a grant set up for testing, try out some example requests:

Create a v3 Sandbox application

Now that you have access, go to the Nylas v3 Dashboard and create a new application. You use the same v3 Dashboard for both U.S. and E.U. data centers.

🔍 Nylas v3 contains breaking changes that make v2 applications incompatible with the v3 Dashboard, and vice versa.. You cannot create a v3 Nylas application from the v2 Dashboard, and you can't use v2 applications with v3 APIs or manage v2 applications in the v3 Dashboard.

When you first log in to your v3 Dashboard account, your organization is empty. Click Create new application to get started.

Set a name and description, select the data residency location and tag the environment as sandbox, development, staging, or production. If you're just trying v3 for the first time, choose Sandbox so you can skip setting up authentication.

When you're ready to test on your own development stack, choose Development.

If you choose Production, Nylas limits access to that application to administrators only - this isn't ideal for testing.

Create an API key to authorize requests

Nylas v3 offers two ways to authorize API requests: using an API key for the whole application, or using a grant's access token that is returned at the end of authentication. API requests authorized using an access token can request user data only, but requests using an API key can also use the Nylas Administration APIs that modify objects at the application level.

For the purposes of this walkthrough we'll generate an API key, since that's simpler:

  1. Make sure you're logged in to the v3 Dashboard, and that you're in your Sandbox application.
  2. From the left navigation, click API Keys.
  3. Click Generate new key.
  4. Enter a name for the key (something like "demo" or "test" is a good place to start) and an expiration date.
  5. Click Generate key, then copy the API key secret that appears and save it to your secrets manager.

Create a test grant

Next, create a grant for testing. In Nylas v3, "grants" replace the concept of "connected accounts", and they represent an end user and the scopes that they have granted your application access to.

  1. From the v3 Dashboard, click Grants, then click Add test grant.
  2. In the prompt that appears, enter an email address that uses either Google, Microsoft, or IMAP, and click Add test grant again.
  3. Authenticate with the provider in the following pages, and be sure to accept the requested scopes. When you finish the authentication process, Nylas directs you back to the Grants page in the Dashboard.
  4. On the Grants page, find and copy the grant ID for the account you just connected. (You can also use the /v3/grants endpoint to see all of the grants in your application.)

You'll use the grant ID to identify the connected account you're querying for when you make API requests. Congrats! You're ready to start using the v3 APIs! 🥳

Quick examples

Start using your Nylas APIs! 🥳 The following sections contain quick code samples that you can use to make requests to the Nylas APIs.

Fetch an email message

curl --request GET \
--url '<NYLAS_GRANT_ID>/messages' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'

Create an event

curl --location --request POST '<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>notify_participants=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data-raw '{
"title": "v3 Launch party",
"calendar_id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AukOKMrxuiEq9pQ3c8aJlXwADf8MjWAAA",
"busy": true,
"participants": [{
"name": "John",
"email": "[email protected]",
"status": "yes"
"description": "Come ready to rock n roll",
"when": {
"time": 1679094476,
"timezone": "America/Vancouver"
"location": "Roller Rink"

Send an email message

curl --request POST \
--url<NYLAS_GRANT_ID>/messages/send \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'content-type: multipart/form-data' \
--form 'Message={
"subject": "Hello World",
"body": "Testing API v3 send!",
"to": [{
"name": "John Doe",
"email": "[email protected]"

Set up an Event webhook

To test webhooks, create a webhook listener on localhost and expose the URL to the public using localtunnel, or a free service like Hookdeck

You can either set up a webhook from the v3 Dashboard, edit the example request below to create a webhook, or use the /v3/webhooks endpoint.

curl --location --request POST '' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data-raw '{
"description": "My Super Cool v3 Webhook",
"webhook_url": "",
"trigger_types": [
"notification_email_addresses": ["[email protected]"]

Finally, create an Event or Calendar and wait for the notifications!

Changes to the webhook format

Webhooks in v3 include data about the object (up to 1MB), so you no longer need to re-query to get that data. See Changes to webhooks in v3 for more details, and the v3 Webhooks schemas for examples of each webhook notification payload.

The example below is a response for the Calendar Event webhook in the previous example.

"specversion": "1.0",
"type": "event.updated",
"source": "/nylas/event",
"id": "4b91f93d-d031-11ed-98ae-8606d2449804",
"data": {
"application_id": "1c9a470a-98b7-44dd-aca0-43fde4d0d7ec",
"object": {
"busy": true,
"calendar_id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AspLh7dx5VEmrBrA6-5vE1QAAAA9PEwAA",
"created_at": 1678887236,
"description": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nCome ready to skate\r\n</body>\r\n</html>\r\n",
"grant_id": "a39d3615-1ad5-46b2-bd97-52645be7bc52",
"hide_participants": false,
"html_link": "",
"ical_uid": "040000008200E00074C5B7101A82E00800000000904AD5CA4257D90100000000000000001000000065A301D59CB8874CBF23E071A99D41C9",
"id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AukOKMrxuiEq9pQ3c8aJlXwADf8LW0QAA",
"location": "Roller Rink",
"message_id": null,
"object": "event",
"organizer": {
"email": "[email protected]",
"name": "Nyla"
"owner": "Nylas [email protected]",
"participants": [{
"email": null,
"status": "noreply"
"read_only": false,
"recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO"],
"reminders": {
"reminder_method": "popup",
"reminder_minutes": 15
"status": "confirmed",
"title": "Launch Party",
"updated_at": 1678887360,
"visibility": "public",
"when": {
"end_time": 1679333160,
"end_timezone": "UTC",
"object": "timespan",
"start_time": 1679318700,
"start_timezone": "UTC"

Sandbox authentication scopes

Because Nylas maintains the demo auth apps for the Sandbox connectors, the apps have a limited set of scopes and may not give you access to all of the v3 APIs that you want to try. See the Nylas v3 Scopes documentation for more information about which specific APIs are compatible with which access scopes.

You cannot change the scopes on a Sandbox Nylas application. If you need different or additional scopes, create a separate v3 application.

The test scopes requested by the Sandbox demo auth app are listed below:

  • Google scopes:
    • (required)
    • userinfo.profile (required)
    • openid (required)
    • gmail.modify
    • calendar
    • contacts
  • Microsoft Graph scopes:
    • offline_access (required)
    • openid (required)
    • profile (required)
    • User.Read (required)
    • Mail.ReadWrite
    • Calendars.ReadWrite
    • Contacts.ReadWrite