Integrating with Nylas is a straightforward process, but there are key considerations you must make depending on your specific use case. This guide provides a comprehensive checklist of the essential components that every Nylas integration needs. After completing this guide, you'll feel comfortable knowing that you've added rock solid features to your app that are ready to deploy to production with minimal friction.
The basic steps to get started are:
Sign up for your free account to create a new Nylas organization.
When you first log in to your account, Nylas creates a new app. Follow our guide to get your developer API keys and the Client ID/Client Secret for your Nylas application. You'll need these to authenticate user accounts.
Decide on if you'll use a separate third-party HTTP library or one of the following SDKs:
Authenticate an account using either Nylas Hosted Authentication or Native Authentication to generate an access token for the user account. Store this access token securely on your back-end infrastructure. Nylas will begin syncing the account the moment it's connected. Take a look at our provider-specific guides if you need to integrate the following account types:
Use the account access token as a bearer token to make requests for user data and functionality via the Nylas Email, Calendar, and Contacts APIs.
You should also consider the following when building your integration:
- Webhooks - If you want to watch for changes to your user's email inbox, calendar, or contacts list, you'll need to set up a scalable webhook listener and queue manager to handle incoming changes.
- Access Token Management - Your app needs to securely store user access tokens to protect user data.
- User Data Storage - You may want to store user data in your own database to avoid making repeated requests to Nylas.
- Error Handling & Monitoring - Changes to third-party user accounts can cause authorization issues that you'll need to account for in your app design.
This guide covers all of these topics.
An organization in the Nylas platform is how we identify your company. Billing, support, data usage, and feature enablement are handled at the organization level.
When you first sign up with Nylas, you’ll be on an unpaid trial. Nylas trial environments are almost identical to production, with only a few differences:
- You're limited to 10 linked accounts.
- Message tracking features (analytics) are turned off for trial accounts. If you need to test message tracking, contact your Nylas sales representative.
This means that you can complete a full production-ready integration during your trial and start authenticating accounts in production without any changes. When you become a paid customer, this organization will be your production organization so make sure you safeguard passwords and other sensitive information.
Nylas applications are a good way to separate your development, staging, and production environments inside a Nylas organization. Each application has a unique Client ID and Client Secret. The Client ID and Secret are used to manage and authenticate accounts but don’t provide access to data for accounts you authenticate.
Since they allow account and application management, you should treat these like any other credentials. Don't store them in your source code or unencrypted storage and follow security best practices.
Each Application has separate configurations for the following:
- Webhooks - You can enable webhooks with specific triggers for development applications to test them before enabling them on your production app. This is useful because the volume of webhooks on a production application with lots of accounts can be too high to test effectively.
- Custom Authentication - If you’re using Hosted Authentication, you may want to customize this process with your company’s information and logo. If you have multiple products, you can have an application for each one and each one can have a different customized experience.
- Google & O365 OAuth credentials - Different environments should have different Microsoft 365 or Google Cloud applications so that you aren’t using a production app to test.
- This is critical to ensure continued testing access for Google accounts. When you submit a Google project application for verification, it disables any sensitive or restricted scopes you had enabled until your app is approved, which could block development.
- API Version - Nylas uses API versioning to make sure we don't impact customers' production applications when we release new features or potentially breaking changes. See API versioning for more details.
If your language doesn’t have a Nylas SDK, we recommend using an HTTP library. Since Nylas is a standard REST API that accepts and returns JSON objects on every endpoint, interactions with Nylas will be straightforward.
One of the key values that Nylas provides is offloading the burden of authenticating different types of email accounts securely and easily for end users. We offer 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).
Nylas Hosted Authentication is the recommended method to implement authentication because it offloads the entire process to Nylas and allows you to get to market quicker. This method handles the entire authentication flow, including provider detection, server settings detection, OAuth, Single sign-on, credential collection, and credential storage. Nylas also offers options to customize the hosted authentication experience to brand it as your own.
Below is the basic flow of Nylas Hosted Authentication:
- You create a custom URL that redirects your users to Nylas hosted authentication.
- The user clicks the link, signs in to their account, and gives your application permission to access their account with the requested scopes.
- After authenticating and granting permission, the user is redirected back to your application with a one-time use code.
- The code is exchanged for an access token that provides all of the requested data and functionality.
To enable OAuth for Google and Microsoft 365 through hosted authentication, you'll need to create an application for each provider and provide the necessary credentials to Nylas through the developer dashboard. Take a look at our provider integration guides to learn more:
Single sign-on is automatically supported when using OAuth flows to authenticate accounts. All other email providers, including IMAP providers, are supported with no prior configuration.
Native authentication is for developers who want to customize the login experience through Nylas to match their application. This method can completely hide that you’re using Nylas on the back-end from your users.
The native authentication guide walks you through how to get started with this method.
Nylas access tokens don’t expire. We recommend that you revoke unused tokens whenever you re-authenticate an account to minimize the number of active tokens.
Since Nylas handles a lot of sensitive information, we’ve built our platform from the ground up with security in mind. We implement strict access controls and auditing to make sure we’re doing everything we can to protect sensitive user data and credentials. A lot of the heavy lifting is handled by us, especially when using Hosted Authentication. This prevents you from directly handling and storing either credentials or OAuth tokens for accounts.
When you integrate with Nylas, you gain access to some of this sensitive data via Nylas access tokens. The security of Nylas access tokens is critical for your application because the tokens grant access to all of your end users’ account data via the Nylas API.
If you’re operating in a cloud environment, there is likely some sort of secret management service available to you. Some examples would be:
When using Nylas’ Hosted Authentication, the secrets you should focus on protecting are:
- Nylas Client ID and Secret.
- Nylas access tokens.
- Google Cloud application OAuth Client ID/Secret.
- Microsoft 365 application OAuth Client ID/Secret.
If you’re using Native Authentication, you need to protect all of the above secrets, as well as:
- User passwords.
- OAuth refresh and access tokens.
If you aren’t using a secret manager to store these values, make sure you're encrypting them at rest and in transit. All requests to Nylas must be made over an encrypted TLS connection (HTTPS). We also don’t recommend sending these outside your infrastructure. If you need to transmit these secrets, make sure you’re using an encrypted connection.
Many databases have encryption options built in, so you don’t have to encrypt these secrets on your own. If you do decide to encrypt the secrets in your application code, use a well-known library such as libsodium or a secure library included in your programming language’s standard library.
We also don’t recommend integrating Nylas on the client side of your application.
It's good practice when re-authenticating or cancelling accounts to revoke the existing Nylas access tokens using our revoke tokens endpoint to reduce your attack surface. At any given time, your application should only hold one access token per account.
If your application will store sensitive data from the Nylas API on your servers, you should implement some disk and/or database-level encryption so that all of this data is encrypted at rest. It’s also important to ensure the data is encrypted whenever it's in transit. This can usually be done by using TLS connections.
These key management and cryptographic storage cheat sheets will give you a good overview of how you can protect Nylas client secrets and access tokens:
The guide to encryption key management is an easy to follow high-level guide on the basics of encryption that will help you understand the concepts required to build a secure application.
Some general security advice we can give is that you should double-check any libraries or encryption algorithms you use to make sure they’re actually secure. Cryptography libraries can have vulnerabilities in their implementations, even though they’re based on a secure algorithm. This applies to bindings for different languages as well because most encryption libraries are implemented in low-level languages such as C or C++.
If you’re unsure of how to properly secure any information, let us know and we can provide guidance.
Nylas supports multiple ways of tracking changes to accounts in real time. Webhooks are the recommended way to receive notifications of changes to any objects such as new messages in a mailbox, because they're lightweight and scalable. Webhooks use a push notification protocol to notify you of changes, rather than you requesting the latest changes from Nylas.
Nylas implements webhooks by sending an HTTP POST request to a URL that you specify when creating your webhook configuration. When you receive a webhook notification, your application then fetches details of the object that changed from the Nylas API.
It’s important to understand that the term webhook is used for both:
- The configuration representing what data changes send webhooks and where to send the data.
- The notification that is sent to the configured location when a change is detected on an account.
Webhooks can be configured manually in the Nylas developer dashboard or programmatically via the Webhooks API. The reference docs cover the endpoints to manage webhooks, the webhook triggers available, and the structure of webhooks payloads. This is also the single source of truth for different values that Nylas uses, such as our request timeout threshold or our retry policy.
We have code examples in our SDK repositories for handling webhooks. You can build off these examples, or use them as a reference to get started on your own implementation.
It’s important to keep scalability in mind when building infrastructure to handle webhooks. If your webhooks endpoint takes too long to handle incoming requests, it will hit the timeout threshold and the request will fail. Nylas uses exponential backoff to retry sends if the first attempt fails, but after a certain number of attempts, the webhook notification will be marked as failed and no further attempts will be made.
We recommending implementing asynchronous processing on your webhooks endpoint and using a queueing system that you can send the notifications through to be processed by a separate service. This will allow the endpoint to remain responsive and gracefully handle bursts of webhooks that can occur when a large number of changes are made, or when new accounts are connected. Fetching data for the object referred to in the webhook notification would be done in the service consuming events from this queue, so it doesn’t block your endpoint response.
Another thing to keep in mind is the ability to add new webhooks servers behind a load balancer as you scale. This also opens the door to providing high availability on your webhooks receiving system.
Webhooks aren’t guaranteed to be delivered in order. This is for several reasons including internal architecture, external provider behavior, and transient endpoint errors. Most of the time, the order of webhook events will be consistent with the order of events on the related objects and you’ll see an object be created before it gets updated.
However, your application should be able to handle the rare cases where you receive an
deleted trigger before you receive a
created trigger for an object. Since the webhook notifications don’t send the actual objects, you can handle this logic when fetching the latest data from our API.
When Nylas starts syncing an account, we sync new data and historical in parallel. This means you'll receive webhooks for historical and new data at the same time until the account is fully synced. If you want to differentiate between new mail and past mail, the
linked_at field included in the accounts endpoint can be compared to the
date field on the message objects. If the
date is less than the
linked_at time, then the message is historical.
Nylas currently doesn't have a trigger available to send webhook events when drafts are created or updated, or when messages are updated. To track this type of change, we recommend adding delta tracking to your application.
Deltas are another way of tracking changes to accounts in real time. We recommend using webhooks over deltas because deltas are slightly harder to scale and require you to keep persistent HTTP connections to Nylas.
The Deltas reference on our delta endpoints provides an introduction and guide on using this method.
In addition to regular HTTP requests that return immediately (which usually aren't the most efficient for deltas), there are two other connection options supported by Nylas for delta endpoints:
- Streaming: receive multiple changes in the same request, only finishing the request when the timeout is reached or the connection is closed.
- Long polling: receive the latest changes in a single request, holding the request open until a batch of changes is delivered, and then closing it. When using long-polling, you need to start a new long poll request every time there are changes, instead of when the timeout is reached.
Deltas from Nylas include the entire objects that changed in the response, rather than requiring a subsequent fetch of data as webhooks do, so you can send them somewhere to be processed immediately. This also means that a newly-connected or busy account will result in a lot of data being returned over deltas.
Even though Nylas has a highly available and robust API, there’s always a chance that you’ll encounter errors. The majority of errors are most likely transient and retrying with exponential backoff will be successful. The Nylas sync engine implements retries and has robust error handling behind the scenes to ensure incidents or transient errors on the providers don’t require any intervention on your part.
The different types of errors to be aware of with your Nylas integration are:
- 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 our sync engine from getting the latest changes from the provider or writing new changes to the provider.
Once in a while, users need to be re-authenticated to Nylas in order for us to connect to their email provider. When and how often this happens is out of our control because it depends on the provider’s policies. The best way to think about how often or randomly this can happen is if you have a Google or Microsoft account that gets signed out of your browser. If users authenticated using their username and password, this will only be required if their password changed.
When this happens, you can still use the Nylas access token to access data already synced, but no new data can be retrieved from the provider until they are re-authenticated.
You can determine an account’s credentials are invalid via the
account.invalid webhook trigger or by regularly querying our Account Management endpoints. You should prompt the user to re-authenticate as soon as the account is flagged by Nylas as invalid credentials status.
Nylas follows the HTTP standard for status codes and we return a 200 success when requests complete without error. Other status codes, such as 4xx or 5xx indicate there was an error. Our SDKs will raise exceptions when requests aren’t successful, but if you’re making your own HTTP requests, you may need to check status codes in your code.
We return a consistent JSON object on errors with a
message field that provides details about the error. You can also view more information about API errors in the developer dashboard. The majority of errors are most likely transient and retrying with exponential backoff will be successful. For more information, see our reference on different errors we may return.
Nylas syncs accounts automatically behind the scenes, but there are rare times where we’ll encounter persistent errors that prevent us from getting the latest changes from the provider. We surface these errors through webhooks or the account management endpoints. The status of these accounts will be either
The steps to fix a stopped account are:
When you get an
account.sync_errorstatus, create automation to immediately restart the customer's sync. We only keep logs for two weeks, so it's important we are made aware asap if reauth and troubleshooting do not solve sync issues.
You can use the code below:
curl -X POST -u YOUR_APP_SECRET https://api.nylas.com/a/YOUR_APP_ID/accounts/ACCOUNT_ID/downgrade
curl -X POST -u YOUR_APP_SECRET https://api.nylas.com/a/YOUR_APP_ID/accounts/ACCOUNT_ID/upgrade
If you tried this and it didn't work, go to Step 2.
- When you get a Stopped Sync status, create automation to immediately ask the customer to re-authenticate their account:
- Send them an email asking to re-authenticate.
- Send them an in-app message asking them to reauthenticate.
- We recommend revoking their token.
- Wait for the user to re-authenticate.
- Once the user has re-authenticated, check to see if the account is in Running or Partial:
- If it's in running, then the issue is fixed.
- If it's in partial, wait to see what happens. Partial is temporary and will transition to either Running or Stopped.
If the user re-authenticated but the stopped sync persists, go to Step 3.
If steps one and two are unsuccessful, contact support (or your sales rep if you aren’t a customer yet).
- Check Sync logs within your Nylas Dashboard:
- Go to dashboard.nylas.com.
- Click on Accounts on the left and select the account that is experiencing the sync issue.
- Look at the Sync Logs and take note of what the error is. If the error indicates anything you can try on your side, then do so.
- Ask the customer if they changed any settings on their end.
[email protected]with the information you got from the customer and any troubleshooting you did on your end.
- Please including the following details in your email to [email protected] to speed up the troubleshooting on our end:
- Message-ID (if applicable)
- Timestamps (if applicable)
- Any errors you're seeing
- Any errors your end-user is seeing
- Include any code (if applicable)
- Any troubleshooting you've done so far
- Any details that can help us reproduce the error (if applicable)
Nylas implements rate limiting solely to protect the platform from single accounts affecting the reliability or performance of other accounts. We have generous rate limits so that our API will handle any use case our customers can think of. Our API returns a 429 HTTP status code when you hit our rate limiting, so it’s important to implement exponential backoff for each account if you encounter these.
For more information, see our reference guide on Nylas’ rate limiting.
There are some scenarios where we are subject to the providers’ rate limits:
- Sending email - Nylas uses the provider to send email using the authenticated email account, so different accounts have different sending limits. Most people don’t hit these limits.
- Updating/Creating objects - these are unlikely to get hit because they are in the ten seconds of thousands per-account daily.
/searchendpoint - Nylas proxies searches on this endpoint to the provider, but it’s highly unlikely you’ll hit these limits since they are read-only requests.
- Message attachments, raw mime, contact pictures - Nylas caches these items for 7 days internally in Amazon S3. Any requests for this data after this period will require Nylas to fetch the data from the provider.
Nylas follows industry best practices with regards to reporting on incidents as soon as we identify problems. We do this through our status page where you can track ongoing incidents and get real-time updates on the progress.
Having instrumentation for a production application to track the health and status helps you be proactive to detect and resolve issues before it impacts your customers. Nylas tracks many different metrics across our platform 24/7 and alerts an on-call engineer in case of any irregularities.
Nylas is a core part of many of our customers’ applications, so we recommend tracking any errors with your Nylas integration as well as with your own application to detect any problems. An example would be tracking the success rate of your requests to Nylas and alerting in case you fall below a certain threshold.
We recommend keeping logs of any errors you encounter with Nylas to help debug issues.
In the case that your webhooks server is failing for long periods of time, Nylas will mark your webhook as failed. Check out our guide on receiving webhooks for details of these periods and how we notify you. This means that we'll stop attempting to send webhooks for your application until the problem is remediated.
Any missed webhooks during this period can be caught up (within 14 days) using our delta endpoints.
Nylas doesn’t recommend integrating to our API from the client-side (i.e. a web browser) because you need your Client ID, Client secret, and Nylas access token to make requests. These are very sensitive secrets, especially the Nylas access token, because it grants access to an account’s email, calendar, or contact data. Protecting these secrets from attackers is hard to do and you could be vulnerable to Cross-Site Request Forgery (CSRF) or Cross Site Scripting (XSS) attacks.
For more information on the complexity of this topic, we recommend reading the following:
Another reason we recommend against integrating client-side is because browsers have ephemeral state. This means that if your client application loses the Nylas access token, they’ll be required to re-authenticate to get a new Nylas access token. This leads to having a lot of tokens with access to the user’s account data in limbo, as well as a poor user experience.
A final reason not to implement your Nylas integration from the client-side is that it’s virtually impossible to receive webhooks to stay up-to-date on the latest changes to accounts.
Accounts in Nylas all have a sync status to indicate whether we’re able or unable to get the latest changes. Nylas tracks these account states internally so that our engineering team can track down errors before customers notice, but it’s also important for you to monitor the accounts you have connected to Nylas to escalate any issues to support.
For more information on sync statuses, read the following guide: