Create a Nylas application
This guide gets you started building an application for production.
Before you begin, make sure you sign up for a Nylas account, and sign up for a paid account.
Free accounts can only build using the Sandbox application, so to make a new application for production, you must have a paid account.
💡 Not ready to build an application? Learn how to get your developer keys first!
First, create a Nylas application:
- Click the carat icon under the Sandbox application name in the left navigation menu, and click Create new app.
- Name your application. You can also add a description (like "development" or "staging") and a URL.
- Click Save.
The word "application" can mean many different things out in the world. Here in the Nylas docs, there are three types of "applications". We do our best to be clear and specific about which one we're referring to.
- Your application (sometimes "your app") - This is the thing you, our customer, are building. Whether that's a mobile scheduler app, an automated email responder, or something else, this is the overall project and code you are working on.
- Nylas application - A Nylas application is a set of configurations, authentication settings, and user grants used to connect to a specific provider using a specific authentication type.
- Provider application - Large service providers require that you connect to their servers using an application tailored to their platform. For example, Google requires a Google Cloud app to connect to to Gmail, and Microsoft requires an Azure app to connect to Outlook365 and other services.
You should set up separate Nylas applications in your Nylas organization for your development, staging, and production environments. Each application has a unique Client ID and Client Secret which are used to manage and authenticate user accounts.
Client ID and
Client Secret allow account and application management so you should treat them like any other credentials and store them securely. Don't save them in your source code, don't leave them in unencrypted storage, and follow security best practices.
The Client ID and Client Secret cannot be used to access to user account data. Only the access tokens Nylas generates during end-user authentication can access user data.
Each Nylas application has separate configurations for the following:
- API Version - Nylas uses API versioning to make sure that the new feature releases and breaking changes don't impact your production applications. See API versioning for more details.
- Webhooks - Each Nylas application has its own webhook configuration. This allows you to create a development application to test webhook changes with a limited amount of traffic.
- Customized Authentication - Nylas stores customization information, for example your company name and logo, or each Nylas application that uses Hosted Authentication. This means you can have multiple products, each with its own Nylas application and with different customized auth experiences.
- Google and O365 OAuth credentials - You might want a separate provider application for each environment production and staging for Microsoft 365 or Google Cloud application. This way you don't lock yourself out of a development or test environment when you put a provider application in for review.
With Hosted authentication, Nylas handles the authentication process. You start an authentication request, Nylas handles authenticating the user with their provider, then returns an access token for the account. Hosted authentication is faster and easier to implement than Native authentication.
With Native authentication, you create a login page and request authorization, and Nylas generates an access token for the account. Use this method if you want to customize every step of the authentication process.
When you authenticate a user, Nylas stores a record of that user in your Nylas application. These records are not shared among applications, even if they share the same owner. This means you must authenticate each account separately with each Nylas application.
When you're familiar with how to authenticate Nylas accounts, you should review the information for the providers your users connect with. For development purposes, start with the one that's most common among your users.
Nylas connects with every email, contact, and calendar provider. Most integrations are straightforward and only require the IMAP/SMTP settings, but for providers that require a bit more work, check out our guides below:
Google and Microsoft require a provider auth app before you can connect accounts. If you're using another provider such as iCloud, you can skip to Install an SDK.
We recommend creating an provider application for both testing and production.
If you're using one of the languages Nylas supports, you should check out the Nylas SDKs. These give you access to the Nylas API in the language of your choice, and can really speed up development.
If you're not using one of these, you can still use a standard HTTP library to help speed up development.
When you decide on your authentication method and pick a client library, you can download one of the Nylas sample applications to learn how to implement them and authenticate an account.
If you're using both a Nylas production and testing application, remember that you must authenticate each account with each application. After you authenticate an account, Nylas gives you an
access_token which is specific to the Nylas application. You use the access token to make API requests.
Webhooks let you monitor your application's health and listen for events from connected accounts, so your application can react to them appropriately.
At minimum, you should subscribe to account status notifications so you know when a user needs to re-authenticate and can prompt them to do so. To do this, you need a webhook URI where Nylas can leave a
POST message and get an acknowledging response within a certain number of seconds. You then make a request to the Webhooks endpoint to tell Nylas which webhook types to subscribe to, and the URL that Nylas should send notifications to.