Developing with Nylas
Developing an app with a Nylas integration can be divided into a few phases, and this guide is here to help you along the way.
- Set up your Nylas account and organization, create a development application.
- Plan your application and authentication method.
- Set up authentication including integration apps with your service providers.
- Set up end-user account status monitoring using webhooks.
- Develop your application using the Nylas APIs.
- Set up webhooks and systems for handling them at scale.
- Set up error monitoring and handling.
Once you're happy with the state of your application, move on to the Production Checklist to get your app through security review, published, and launched!
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.
Your application will use Nylas APIs to access your end user accounts on their behalf, and use webhooks to monitor activity that your application needs to know about. Before you start integrating with Nylas, you should list the activities that you want to do in your app that require access to the service provider, and the results and changes you want to monitor to inform how your app responds.
For example, if you are building a calendaring app, you know you want to be able to read a user's calendar so you can pick an available time slot. You also know you want to write to the calendar so you can create new events. Perhaps you also want to choose from a list of the user's contacts when inviting people to the event, which requires read access to their contacts.
But what happens if the person you invite to the event declines? Or if the creator cancels the event from outside your app? You'll want to monitor for these changes using Nylas webhooks, so your app can respond helpfully.
Once you have a working list of what objects you want to interact with and get notifications about, you can review the list of access scopes for each provider, the list of available webhooks, and build the list for your application.
When you're ready to start, create a new Nylas account.
If you're the first person on your team to create an account, you can make your account the "organization", and invite colleagues who are helping with development and testing. The account that hosts the organization is the one that has the billing details attached to it, so decide among yourselves which account should "host" the organization.
When you first sign up with Nylas, your account is on an unpaid trial. Nylas trial environments are limited to 10 linked accounts and do not include message tracking (analytics) features, but are otherwise the same as a paid account. (If you need to test message tracking, contact your Nylas sales representative.)
An organization is how Nylas identifies a company. An organization is a collection of Nylas applications and Nylas dashboard accounts that are linked together and paid for in the same way. Billing, support, data usage, and feature enablement are handled at the organization level.
To invite team members, log in to the Nylas Dashboard, click Org settings in the left navigation, then click Add a team member. Enter a name and email address for the team member, and choose if you want to make them an administrator of your organization.
If you aren't the first person to make a Nylas account, have the other person add you to their organization using the steps above.
If you or a teammate created a Nylas account without clicking an invitation link, contact Nylas Support to add the account to the organization.
Each organization can have multiple Nylas applications registered to it. When you first create your account, Nylas creates a Quickstart or Sandbox applications for you to use to test out the services. When you're ready, create an application to use for testing.
An application is a Nylas term for a set of authentication configuration, and logical collections of "accounts", which are permissions to connect to email and calendar accounts.
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.
Nylas saves you time by simplifying the process of securely authenticating different types of email accounts, and with minimum effort for end users. Nylas offers two different ways to authenticate accounts based on your application’s requirements: hosted authentication (Nylas handles the entire process) and native authentication (full customization with authentication information submitted to Nylas).
For most developers this choice is easy, and you'll use Nylas hosted authentication. When you use hosted authentication, Nylas detects which email provider the end user has, passes the user through authentication with that provider, and returns the now-authenticated user to your app. The work required to integrate is minimal.
If you want to completely hide Nylas and the email provider details from the user, you might want to use Nylas native authentication, however this can require a lot of development work. See the Authentication documentation to learn more about choosing an authentication type.
If you expect to connect to Google or Microsoft, you must create a provider application to connect to their servers. Once created, you can use the provider application with internal company accounts for development and testing, but you must get it reviewed by the provider before you can distribute or "go live" with your application.
Creating the provider application is straightforward, and you can create one (or several) quickly so you can start developing. However, the provider review can take several weeks, and depends entirely on the provider's review process and which scopes your app uses. You'll want to plan this into your development timeline!
Tip! You can have multiple provider applications, for example one for development which has not been security reviewed, and one for production, which has been. When your application is ready to go live, you can swap in the production provider application credentials for the dev ones, as long as the application uses the same scopes.
In the previous section you reviewed the two types of authentication - now you get to implement your choice. See the documentation on Hosted authentication and Native authentication for more details. Nylas also maintains tailored guides for connecting to Google accounts or connecting to Microsoft accounts.
You might find it helpful to refer to the list you made during the planning step when determining what scopes you need to include.
If you need to create a provider application to complete the authentication process, you should start that now. See the information on creating an Azure provider application and creating a Google provider application.
Other topics on this documentation site cover this at length, including the authentication documentation, the provider guides, and the security best practices page, but this can't be emphasized enough.
During the authentication process, Nylas passes your app a user access token that your app needs so it can make requests on the user's behalf. You must store this token in your app, and you may wish to cache or store other user data to prevent making unnecessary API calls.
This information should be encrypted using a modern algorithm, both in transit and at rest, and if at all possible you should use a secrets manager from your infrastructure provider.
See the security best practices for more information. Failure to follow security best practices might prevent your app from passing the verification process with the provider(s).
Your end-users are your application's life, so it makes sense to keep a close eye on the status of your connected accounts. Once you have authentication set up, you should make sure you subscribe to the account state webhooks for your application, so you can get alerts when end-users run into problems, and take appropriate action.
This could be re-authenticating the user, sending them a prompt to re-authenticate themselves or accept changed scopes, using an incremental backoff approach or pausing their data sync, or other actions specific to your application and use case. In addition, the timestamps on receipt of these account status webhooks can be valuable for checking the user's data once their account problem is resolved.
Tip! If you're authenticating using a Google provider integration app, make sure you have PubSub set up for your application, to ensure timely webhook delivery.
After you get authentication set up, authenticate with a test account or two so you can work with the Nylas APIs. Nylas maintains SDKs in Node.js, Python, Ruby, and Java, but you can also interact with the APIs using a plain HTTP library.
If you already know what you want to build, or if your app is already mostly finished, you can read through the Nylas API documentation, or the guides for working with Email, Calendar, and Contacts APIs.
If you're just starting out and not sure where to begin, Nylas also maintains a repository of sample code, and a set of fully functioning sample and demonstration applications for inspiration.
Once you have an account or two authenticated, and have made API calls to interact with email or calendars, you should think about what Nylas events you want to know about, so your app can respond to them.
If you completed the planning exercise at the beginning of this page and compiled a list of ideas, that's a great place to start. If you're building as you go, see the list of available webhooks for ideas.
Webhooks can be used both to run core functionality in your app, and to monitor for undesirable events (errors!) so you can handle them gracefully.
You should also consider the volume of webhooks you're likely to get from your app, and plan for scaling them appropriately. See the Webhooks best practices guide for important tips and considerations to help your integration run smoothly and scale easily.
Although Nylas access tokens don't expire, you can assume that you will need to plan for authentication changes due to the user's actions, and the provider's policies. See the section on Managing accounts for more information.
For example, if a user explicitly disconnects or logs out of your application, you should revoke their Nylas access token to minimize the number of active tokens. You should also revoke unused tokens when an account re-authenticates.
You should also think about how you want to handle changes in permission scopes, for example if your application adds new functionality that requires more access. Scope changes require re-authentication to let the user explicitly confirm they grant access to these scopes.
You might also want to monitor your user accounts with webhooks to detect when they're in an error state, so you can prompt the user to re-authenticate.
You may want to store user data in your own database to avoid making repeated requests to Nylas. You must securely store user access tokens to protect your users' data.
Nylas has robust built-in strategies for handling provider errors and other network weather. However, there are situations you should monitor and decide how to handle in your app.
- Invalid Credentials - when an accounts' OAuth token is expired, was revoked, or their password was changed.
- API errors - when your application makes a request to the Nylas API and you get a non-200 HTTP status code response or a network error.
- Account sync errors - persistent errors that prevent the Nylas sync engine from getting the latest changes from the provider or writing new changes to the provider.
See the Monitoring and error handling for a list of common error states and best practices on how to handle them.
You might also want to monitor your webhooks for errors and implement retry, backoff, and restart logic based on their status.
Once you feel like your application is complete, move on to the Production checklist for the last steps before you go live!