Only show these results:
public-beta-v3

Nylas v3 Beta Quickstart guide

The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.

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

This section covers the following steps to get you set up to test API v3:

  1. Create a Nylas v3 application in the v3 Dashboard.
  2. Update or create test provider auth applications.
  3. Set up connectors.
  4. Add a redirect URI.
  5. Create a Grant for testing.

Once you have a Grant set up for testing, check out the Quick examples:

Create a Nylas v3 application in the v3 Dashboard

Once you're in the Beta, go to the Nylas v3 Dashboard and create a new application.

The v3 Dashboard is separate from the existing (v2.x) Nylas Dashboard, and supports v3 applications and APIs only. You cannot create a v3 Nylas application from the v2 Dashboard, and v2 applications are not compatible with v3 APIs.

When you create a new application in the v3 Dashboard, you can set a name and description, and tag the environment as development, staging, or production (we recommend that you stick with development for now). You can also add your application callback URI (if you already know it) and choose to enable authentication testing using the Dashboard.

Update or create test provider auth applications

Next, we'll tackle your provider authentication. You should have separate provider auth applications specifically for testing so you can isolate your production systems. You can either create new ones, or re-use existing test provider auth applications.

Don't use production provider auth applications for Beta testing. Use of a production provider auth application with a v3 Beta application may invalidate your Support SLAs.

To create new provider auth applications, see the v3 provider guides on creating a Google Cloud Platform application and Azure application.

If you choose to use existing provider auth applications, you must make the following changes:

  • For all providers: If your projects use Hosted auth, add https://api.us.nylas.com/v3/connect/callback as an allowed redirect URI. Don't add these if you're using Custom/Native auth, using a Virtual Calendar, or setting up a bulk authentication Grant.
  • For Google provider applications: You can optionally set up PubSub to make sure you get webhooks quickly.
  • For Azure provider applications: Make sure you add Graph scopes. The Nylas v3 APIs support only Microsoft Graph, and adding these scopes to an existing provider auth app might prevent legacy EWS or EAS accounts from re-authenticating. Try this on your test instance first!

Set up connectors

In v3, Nylas uses connectors to store information that lets your Nylas application connect to external services, such as your provider auth applications. You can have only one connector for each provider.

You can either create the connectors from the Connectors page on the Dashboard, or by using the Create connector /v3/connectors API. (You only need to use your application API key to make these API calls.)

For these API calls you need:

  • The client_id and client_secret.
  • The tenant type (if Azure, usually common) or PubSub topic name (if Google).
  • A list of the scopes that your application requires.
curl --location --request POST 'https://api.us.nylas.com/v3/connectors' \
--header 'Authorization: Bearer < Your Nylas application API key >' \
--header 'Content-Type: application/json' \
--data '{
    "name": "My Google Connector",
    "provider": "google",
    "settings": {
        "client_id": "<GOOGLE_OAUTH_CLIENT_ID",
        "client_secret": "<GOOGLE_OAUTH_CLIENT_SECRET>",
        "topic_name": "<GOOGLE_TOPIC_NAME>"
    },
    "scope": [
        "openid",
        "https://www.googleapis.com/auth/userinfo.email",
        "https://www.googleapis.com/auth/userinfo.profile",
        "https://www.googleapis.com/auth/gmail.readonly",
        "https://www.googleapis.com/auth/gmail.send"
        ]
    }'   
curl --location --request POST 'https://api.us.nylas.com/v3/connectors' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer < Your Nylas application API key >' \
--data-raw '{
    "name": "MS Connector",
    "provider": "microsoft",
    "settings": {
        "client_id": "<your client ID>",
        "client_secret": "<your client secret>",
        "tenant": "common"
        },
    "scope": [
        "Mail.ReadWrite",
        "User.Read",
        "offline_access",
        "Calendars.ReadWrite",
        "Mail.Send"
        ]
    }'

Add a redirect URI

Next, add your application's redirect URI, sometimes called a callback_uri, to your v3 Nylas application. This is the URI where Nylas directs the user after authenticating. You can do this from the v3 Dashboard, or use the /v3/applications/redirect-uris API endpoint, as in the cURL example below.

curl --location 'https://api.us.nylas.com/v3/applications/redirect-uris' \
--header 'Authorization: Bearer < Your Nylas application API key >' \
--header 'Content-Type: application/json' \
--data '{
    "url": "http://my-callback-uri.example.com:3000",
    "platform": "web"
    }'

Create a Grant for testing

Finally, create a Grant for testing. In 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.

curl --location 'https://api.us.nylas.com/v3/connect/auth' \
--header 'Authorization: Bearer < Your Nylas application API key >' \
--header 'Content-Type: application/json' \
--data '{
    "provider": "google",
    "redirect_uri": "http://localhost:3000",
    "state": "123456"
    }'   
curl --location --request POST 'https://api.us.nylas.com/v3/connect/auth' \
--header 'Authorization: Bearer < Your Nylas application API key >' \
--header 'Content-Type: application/json' \
--data-raw '{
    "provider": "microsoft",
    "redirect_uri": "http://localhost:3000",
    "state": "123456"
}'

When you make this request, Nylas returns a response that includes a URL. Copy the URL and paste it in your browser to log in using your email account with that provider.

After you authenticate, Nylas sends you to the application redirect URI you specified and adds query parameters to track if the authentication succeeded or failed. Your grant_id is also included as one of those query parameters, so look for it!

You can also use the /v3/grants API endpoint to see all of the grants in your application.

curl 'https://api.us.nylas.com/v3/grants' \
--header 'Authorization: Bearer < Access Token or your Nylas application API key >'

Start using your Nylas APIs! 🥳 Now you can start using any of your Nylas API v3 using your Grant ID.

Quick examples

Fetch an Email with API v3 

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <API_KEY_OR_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json'

Create an Event with API v3 

curl --location --request POST 'https://api.us.nylas.com/v3/grants/44fb4b24-0963-4267-844b-dda9d827dfdc/events?calendar_id=AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AukOKMrxuiEq9pQ3c8aJlXwADf8MjWAAA&notify_participants=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer < Access Token or your Nylas application API key >' \
--data-raw '{
    "title": "API 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 with API v3 

curl --request POST \
  --url https://api.us.nylas.com/v3/grants/44fb4b24-0963-4267-844b-dda9d827dfdc/messages/send \
  --header 'Authorization: Bearer HUkdFSzX8i_Jgxu2-5Qs7yEoGaeOv6fuTV7TbuB4Kxn_p8KkVdfBstc_DTh_JkbSDz57uaqO5C7GNDFZX8fbr06cEBW3j6-UfB-VX4oeCGsp8LIsY1J679gibgKLQTTE3WnwP8rP3toOcMsrcM_gzVRNiF5AEmuY_fYAyxJvczM' \
  --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 with API v3

To test webhooks, create a webhook listener on localhost and expose the URL to the public using localtunnel, or a free service like Hookdeck If you use the Nylas SDKs, you can also use the built-in local webhook testing features.

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

curl --location --request POST 'https://api.us.nylas.com/v3/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer < Access Token or your Nylas application API key >' \
--data-raw '{
    "description": "My Super Cool v3 Webhook",
    "callback_url": "https://events.hookdeck.com/e/src_vRYi6wTq6NOW",
    "trigger_types": [
        "grant.created",
        "grant.updated",
        "grant.deleted",
        "grant.expired",
        "calendar.created",
        "calendar.updated",
        "calendar.deleted",
        "event.created",
        "event.updated",
        "event.deleted"
    ],
    "notification_email_addresses": ["[email protected]"]
}'

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

Changes to the webhook format

Webhooks in v3 now include data about the object (up to 1MB), so you no longer need to re-query to get that data. See the v3 Webhooks documentation for more details, and the v3 Webhooks schema documentation 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": "https://outlook.office365.com/owa/?itemid=AAkALgAAAAAAHYQDEapmEc2byACqAC%2FEWg0AukOKMrxuiEq9pQ3c8aJlXwADf8LW0QAA&exvsurl=1&path=/calendar/item",
      "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"
      }
    }
  }
}