Only show these results:

Production Checklist

Integrating with Nylas is a straightforward process, but there are important details you should understand and decisions to make depending on how you want to use Nyals. This guide gives you a checklist of the important steps that every Nylas developer should go through so you'll know that your app is ready to deploy to production with minimal friction.

The basic steps to get started are:

  1. Sign up for your free account to create an account and a new Nylas organization. When you first log in to your account, Nylas creates a new application.
  2. Get your developer API keys and the Client ID/Client Secret for your Nylas application. You need these to authenticate user accounts.
  3. Choose how to integrate Nylas. You can use a third-party HTTP library, one of the Nylas SDKs (Node.js, Python, Ruby or Java), or make API calls on your own.
  4. Choose how to authenticate. You can either use hosted authentication which is faster, or native authentication, which is more complicated to set up, but allows wider configuration options.
  5. Set up authentication. See the provider-specific guides to help you integrate with Google, Microsoft, iCloud, Yahoo, and others.
  6. Generate an access token for a user account, and store the access token securely on your back-end infrastructure. Nylas begins syncing the account as soon as it connects.
  7. Use the account access token as a bearer token to make requests on behalf of the user through the Nylas Email, Calendar, and Contacts APIs.

Enhancements

You should also consider the following when building your integration:

  • Webhooks - If you want to watch for changes to a user's email inbox, calendar, or contacts list, you need a scalable webhook listener and queue manager to handle incoming changes.
  • Access Token Management - You must securely store user access tokens to protect your users' data.
  • User Data Storage - You may want to store user data in your own database to avoid making repeated requests to Nylas.
  • Error Handling and 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.

Application Diagram

Nylas application

Create your organization

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.

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.)

This means that you can complete a full production-ready integration during your trial and start authenticating accounts in production without making any changes to your initial Nylas application. When you become a paid customer, this organization becomes your production organization - so make sure you safeguard passwords and other sensitive information!

Set up your Nylas applications

You should set up separate Nylas applications inside your Nylas organization for your development, staging, and production environments. 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 the accounts they authenticate.

Since they allow account and application management, you should treat the Client ID and Client Secret like any other credentials. Don't save them in your source code, don't leave them in unencrypted storage, and follow security best practices.

Each Nylas application has separate configurations for the following:

  • Webhooks - You can test webhooks with specific triggers on a development application with only a few users. This prevents you from being overwhelmed by the number of triggered webhooks, so you can test and fine-tune your webhook notifications before setting them up on a production-volume app.
  • Custom Authentication - If you use Hosted Authentication, you might want to customize this process with your company’s information and logo. If you have multiple products, you can have a Nylas application for each one, and each one can have a different customized experience.
  • Google and O365 OAuth credentials - You should have a separate Nylas application for each environment (prod, stage, dev) for each Microsoft 365 or Google Cloud applications. This way you aren’t using a production app to test.
    • This is important because when you submit a Google project application for review, Google disables any sensitive or restricted scopes until the app is approved. Essentially, you're locked out of the app until approval, which could stop you from further development and testing.
  • API Version - Nylas uses API versioning to make sure that new features or potentially breaking changes don't impact customers' production applications when they're released. See API versioning for more details.

Choose your SDK or HTTP library

Nylas maintains a variety of SDKs so you can develop in the language you're most familiar with:

There are also community maintained SDKs. If there is not an SDK for your language you can use an HTTP library. Nylas is a standard REST API that accepts and returns JSON objects on every endpoint, so interactions with Nylas are predictable and straightforward. See the Nylas API reference for more details.

Choose an authentication method

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).

Nylas Hosted Authentication

Nylas Hosted Authentication is the simplest and most recommended method. In hosted authentication, Nylas handles the entire process so you can get to market quicker. With hosted authentication, Nylas 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.

The basic hosted authentication flow process is as follows:

  1. You create a custom URL that redirects users to Nylas hosted authentication.
  2. A user clicks the link, and signs in to their account. This gives your application permission to access their account with the scopes you requested.
  3. After authenticating, Nylas redirects the user to your application with a one-time-use code.
  4. Your application exchanges the one-time-use code for an access token that it can use to access the Nylas APIs on the user's behalf.

To enable OAuth for Google and Microsoft 365 through hosted authentication, youmust first create am application for each provider, and save credentials to that application in the Nylas developer dashboard. See the Google provider integration guide and the Microsoft provider integration guide to learn more.

Single sign-on is automatically supported when you use OAuth to authenticate accounts. Nylas supports all other email providers, including IMAP providers, with no prior configuration.

Native authentication

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 use Nylas on the back-end from your users.

The native authentication guide explains the process of setting up this method.

Nylas token lifecycle

Nylas access tokens don’t expire. You should revoke unused tokens when an account re-authenticates to minimize the number of active tokens.

Security best practices

The Nylas platform handles a lot of sensitive information, and was built from the ground up with security in mind. Nylas implements strict access controls and auditing to make sure we’re doing everything we can to protect sensitive user data and credentials. Nylas does a lot of the work of implementing a secure process for you, especially when you use 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 through Nylas access tokens. These tokens grant access to all of your end users’ account data via the Nylas API, so the security of these tokens is critical for your application. This section lists some recommendations for maintaining a secure environment.

Storing secrets securely

If you operate in a cloud environment, your cloud infrastructure provider probably provides a secret management service that you should use. Some examples would be:

When you use Nylas’ hosted authentication, you should focus on protecting the following secrets:

  • Nylas Client ID and Secret.
  • Nylas access tokens.
  • Google Cloud application OAuth Client ID/Secret.
  • Microsoft 365 application OAuth Client ID/Secret.

If you use native authentication, you need to protect all of the above secrets, and user passwords, and OAuth refresh and access tokens.

If you are not using a secret manager to store these values, you should encrypt them both at rest and in transit. All requests to Nylas must be made over an encrypted TLS connection (HTTPS). You should try to design your application so you don't send secrets outside your infrastructure. If you need to transmit these secrets, use 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 do not recommend integrating Nylas on the client-side of your application, as this gives more opportunities for credentials to be intercepted.

Revoke old tokens

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.

Encrypt stored user data

If your application stores sensitive data from the Nylas API on its servers, you should implement some disk and/or database-level encryption so that all of the data is encrypted at rest. You should also important ensure that the data is encrypted whenever it's in transit. This can usually be done by using TLS connections.

More security resources

These key management and cryptographic storage cheat sheets provide 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 explains 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. Cryptographic 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 how to properly secure any information, contact Nylas support, so we can provide guidance.

Webhooks

Nylas supports multiple ways of tracking changes to accounts in real time, including webhooks. Webhooks use a push notification protocol to notify you of changes, rather than you perodically requesting (polling for) the latest changes from Nylas. This makes webhooks are lightweight and scalable, which makes them the recommended way to receive notifications to objects such as new messages in a mailbox.

Nylas implements webhooks by sending an HTTP POST request to a URL that you specify when you configure your webhook. When a webhook triggers, Nylas sends information about the object that your application can use to get details from the Nylas API about the object that changed.

It’s important to understand that the term "webhook" can refer to both the configuration of the webhook (the data change that triggers the message, and where the message is sent), and the notification that is sent.

You can configure webhooks manually in the Nylas developer dashboard or programmatically using the Webhooks API. The Nylas Webhooks API documentation lists the webhook management endpoints, the available webhook triggers, and how webhooks payloads are structured.

This documentation is the source of truth for different values that Nylas uses, such as the request timeout threshold and retry policy.

Per SDK webhook examples

Nylas maintains code examples in the SDK repositories that demonstrate how to handle webhooks. You can build from these examples, or use them as a reference to get started on your own implementation.

Scalability

It’s important to keep scalability in mind when you build your systems to handle webhooks. If your webhook endpoint takes too long to handle incoming requests, it might hit the timeout threshold and cause requests to fail. If the first send attempt fails, Nylas retries using an exponential backoff. However, after a certain number of failed attempts, the webhook notification is marked as failed and Nylas stops trying to deliver it.

We recommend that you use asynchronous processing on your webhook endpoint, and that you use a queueing system so notifications can be processed by a separate service. This separate service should fetch the data about the objects referred to in the webhook notifications, so the webhook endpoint to remains responsive even when bursts of high volumes of webhook notifications occur, such as when new accounts are connected.

If you expect a large volume of webhook notifications, you can also add new webhook processing servers behind a load balancer as you scale. This enables you to provide high availability on your webhook receiving system.

Ordering

The Webhook specification does not make any guarantees about delivery or delivery order. This allows them to function regardless of internal architecture, external provider behavior, and transient endpoint errors. Most of the time, the webhook events match the order of events on the related objects, and an object is created before it gets updated.

However, your application should be able to handle rare cases when it receives an updated or deleted trigger before it receives 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. <!-- LR: how? queueing until the create arrives?-- >

Historical data

When Nylas first connects and starts syncing an account, it syncs both new data and historical data in parallel. This means you might receive a mix of webhooks for historical data and new data until the account is fully synced.

To identify webhook notifications for new mail and historical mail, use the linked_at field included in the accounts endpoint and compare it to the date field on the message objects. If the date is earlier than the linked_at time, then the message is historical, and you can choose how to handle it.

Message and draft updates

Nylas does not currently offer a webhook trigger to send events when a message is updated, or when a draft is created or updated. You can use delta tracking instread to track this type of change.

Deltas

Deltas allow you to track changes to accounts in real time. In most cases you should use webhooks instead of deltas, because webhooks are easier to scale and don't require a persistent HTTP connection to Nylas.

Deltas from Nylas include the entire object that changed in the response. This means you don't need to make an additional data request like you would with webhooks do, and you send the data on immediately for processing. This also means that a newly-connected or busy account might return a lot of data in the deltas requests.

Nylas provides the following connection options for delta endpoints:

  • Regular HTTP requests: These return immediately, which usually isn't the most efficient way to receive deltas.
  • Streaming: Receives multiple changes in the same request, only finishing the request when it reaches the idle timeout or the connection is closed.
  • Long polling: Receives the latest changes in a single request, holds the request open for a batch of changes, waits until the batch is delivered, then closes the connection. If you use long-polling, you must start a new long poll request every time there are changes, instead of when the timeout is reached.

See the Deltas API reference documentation on our delta endpoints provides an introduction and guide on using this method.

Error handling and monitoring

Even though Nylas has a highly available and robust API, there’s always a chance that you’ll encounter errors. Most errors are transient, and a retry with exponential backoff approach is successful. The Nylas sync engine implements retries and has robust error handling to make sure outage incidents or transient errors from the providers don’t require intervention on your part. The types of errors you will need to handle are below.

  • 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.

Invalid credentials

Users might periodically need to re-authenticate with Nylas to connect to their email provider. When and how often they need to re-authenticate depends entirely on the provider’s policies. It's the same as if you have a Google or Microsoft account that gets signed out of your browser.

When this happens, you can still use the Nylas access token to access data that was already synced, but Nylas cannot retrieve new data from the provider until the account re-authenticates.

You can check if an account’s credentials are invalid using the account.invalid webhook trigger, or by regularly querying the Account Management endpoints. You should prompt the user to re-authenticate as soon as the account is flagged by Nylas as invalid credentials status.

If users originally authenticated by providing a username and password, then they only need to re-authenticate when their password changes.

API errors

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.

Nylas returns 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 that Nylas may return.

Account sync errors

Nylas syncs accounts automatically, but in the rare event that Nylas encounters persistent errors, it can halt changes from the provider. Nylas raises these errors using webhooks or by reporting to the account management endpoints. Accounts that are receiving persistent errors are marked as either account.stopped or account.sync_error.

The steps to fix a stopped account are:

Step 1: Restart the sync

You can create an automation in your app to automatically try to restart a sync process when you get an account.stopped or account.sync_error status. Nylas only keeps logs for two weeks, so it's important to get help quickly if sync issues persist.

You can use the curl command 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.

Step 2: Re-authenticate the account

You can also create an automation to immediately ask the user to reauthenticate when you get a Stopped Sync status. You might do this as second step if your restart automation doesn't work.

  1. Ask the customer to re-authenticate their account using one or both of the following methods:
    • Send them an email asking to re-authenticate.
    • Send them an in-app message asking them to reauthenticate.
  2. Revoke their token as a good security practice.
  3. Wait for the user to re-authenticate.
  4. Once the user re-authenticates, check the account status again:
    • If it's in Running, then the issue is fixed.
    • If it's in Partial, try again later - "Partial" is temporary and transitions to either Running or Stopped.
    • If it's in Stopped even after the user re-authenticates, contact Nylas Support.

Contact Nylas Support

If restarting and reauthenticating do not solve the issues, contact Nylas Support or your sales representative.

  1. Check your sync logs: From the Nylas Dashboard, click Accounts, and select the account that's having the sync issue. View the Sync Logs and note the error. If the error suggests additional fixes or troubleshooting steps, please do so.
  2. Ask the end user if they changed any settings, and for the exact error they see.
  3. Include the following details in your email to [email protected] to speed up the troubleshooting:
    • Account-ID
    • Message-ID (if applicable)
    • Timestamps (if applicable)
    • Any errors you see in the sync log
    • Any troubleshooting you've done so far
    • Information about the error the end-user sees
    • Include any code (if applicable)
    • Any details that can help us reproduce the error (if applicable)

Rate limiting

Nylas rate limiting prevents a single account from affecting the reliability or performance of other accounts on the platform. The Nylas rate limits are generous so the API can accomodate any use case you can think of.

The Nylas API returns a 429 HTTP status code when you hit rate limiting, which prevents additional requests from completing. You should implement an exponential backoff strategy so that accounts can recover and continue operating if it hits a rate limit. See the developer guide on rate limiting for more information.

Nylas is also subject to rate limiting from the providers in the following activities.

  • Sending email - Nylas uses the authenticated email account to send email through the provider. Different providers have different send limits, but most people never hit these limits.
  • Updating and Creating objects - While these rate limits exist, you are unlikely hit them, because create and update actions are very rate.
  • /search endpoint - Nylas proxies requests to its search endpoint to the provider, so they are subject to provider limits. However, the activity is read-only and unlikely to hit rate limits.
  • Message attachments, raw mime, contact pictures - Nylas caches these items for seven days internally in Amazon S3. Requests for this data after this period require Nylas to fetch the data from the provider.

Nylas status

Nylas follows industry best practices to report on outage incidents as soon as a problem is identified. See the Nylas status page to track ongoing incidents and get real-time updates on progress.

Instrumentation

Instrumentation on a production application can track the health and status, and help you be proactive so you can detect and resolve issues before them impact end-users. Nylas constantly tracks different metrics across the platform, and alerts an on-call engineer in the event of irregularities.

Nylas is a core part of many applications, and it's a good practice to track errors both coming from your application, and from the Nylas integration to detect any problems. For example, you could tracking the success rate of requests to Nylas, and alert if a certain percentage of requests fail.

You should also keep logs of errors you encounter to help with troubleshooting and resolving issues.

Missed webhooks

If your webhook server fails for long periods of time, Nylas marks your webhook as failed. This means that Nylas stops trying to send webhooks for your entire application until the problem is fixed. See the Retry attempt documentation for more information about failure limits, and how Nylas sends failure notifications.

If you experience an outage, you can re-run missed webhooks from the outage period (with 14 days) using the Nylas delta endpoints.

Client-side integration

Nylas doesn’t recommend integrating to our API from the client-side (for example through a web browser) because integration needs your Nylas 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 more about Where to Store your JWTs – Cookies vs HTML5 Web Storage.

Browsers also maintain what's considered "ephemeral" state. This means that if your client application loses the Nylas access token, the end users must re-authenticate to get a new Nylas access token. Aside from being a poor user experience, this also leads to having a lot of unused but still active tokens with access to the user’s account floating around.

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.

Account lifecycle

Accounts in Nylas all have a sync status to indicate whether Nylas was able to get the latest changes from the provider. Nylas tracks these account states internally so the team can fix errors before customers notice, but you should also monitor your connected accounts, and escalate any issues to support.

For more information on sync statuses, read the following guide: