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!
Before we begin: What's an "application"?
"Application" can mean three different things in the Nylas documentation:
- 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 that you are working on.
- Nylas application: A set of configurations, authentication settings, and end user accounts 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 application to connect to Gmail.
We do our best to be clear and specific about which type of application we're referring to, in order to avoid confusion.
Planning your application
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 Webhooks API reference, and build the list for your application.
Create a Nylas account and organization
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 represents a company within the Nylas platform. It's a collection of Nylas applications and 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 teammates to v3 Nylas organizations, follow these steps:
- Log in to the v3 Nylas Dashboard.
- Click the organization menu at the top-right of the page, and select Members.
- Click Invite members.
- Enter your teammates' email addresses, and choose if you want to make them administrators for the organization.
- Click Invite members.
For v2 Nylas organizations, follow these steps:
- Log in to the v2 Nylas Dashboard.
- Select Org settings from the left navigation menu.
- Click Add a team member.
- Enter the teammate's name and email address, and choose if you want to make them an administrator for the organization.
- Click Add a team member.
- Repeat steps 3–5 for each teammate you want to add to the organization.
Nylas sends an email message containing an invitation link. When your teammate clicks the link, they can create their own Nylas account, and it's automatically associated with your organization.
🔍 If you or a teammate created a Nylas account without clicking an invitation link, contact Nylas Support to add the account to your organization.
Create a Nylas application for development
Each organization can have multiple Nylas applications registered to it. When you first create your account, Nylas creates a Sandbox application 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.
Nylas strongly recommends you set up separate Nylas applications for your development, staging, and production environments. Each application has a unique client ID and client secret which you use to manage and authenticate your end users.
The 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, and don't leave them in unencrypted storage. Follow Nylas' security best practices to store important credentials.
🔍 You cannot use the client ID and client secret to access your end users' account data. You must use the access tokens Nylas generates during the authentication process.
Each Nylas application has separate configurations for the following settings:
- Notifications: Each Nylas application has its own notification settings for both webhooks and notification channels. This allows you to create a development application to test notification changes with a limited amount of traffic without impacting end users in your production environment.
- Customized authentication: Nylas stores customization information (for example, your company's name and logo) for each Nylas application that uses Hosted auth. This means you can have multiple projects, each with its own Nylas application, and each with a different customized auth experience.
- Google and Office365 OAuth credentials: Nylas suggests you create separate provider applications for each environment. This way, you won't lock yourself out of a development or test environment when you submit a provider application for review.
Choose how to authenticate users
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.
You might also want to read more about the requirements from individual service providers: See the guides for Google, Microsoft, iCloud, Yahoo, and others.
Planning for service provider application(s)
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.
Google application review
Before you can publish your GCP project, you might have to take extra steps to comply with Google's OAuth 2.0 policies and complete their verification process. Be sure to request the most restrictive scopes that you need for your GCP application. If you request any of Google's restricted scopes, Google will require your application to complete a security assessment. This could extend your verification timeline significantly, or cause Google to fail your review.
For more information, see the Google verification and security assessment guide.
Set up authentication
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.
Store user access tokens and user data securely
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).
Set up end-user account status monitoring
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 notifications 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.
You can subscribe to these account state notifications either from the Nylas Dashboard using the Webhooks APIs, or using the Nylas SDKs.
💡 Tip! If you're authenticating using a Google provider auth app, make sure you have Pub/Sub set up for your application to ensure timely webhook delivery.
Develop with the Nylas APIs
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.
There is also a Nylas Postman collection for you to explore, and the Nylas CLI for interacting with the APIs through your terminal.
Set up notifications
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 notification schemas for ideas.
Nylas allows you to subscribe to notifications using webhooks, Google Pub/Sub queues, or mix of both. You can use notifications 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 notifications 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.
User data and auth lifecycle management
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 grants 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.
Monitoring and error handling
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.
Ready to go?
Once you feel like your application is complete, move on to the Production checklist for the last steps before you go live!