&metadata_pair=key1:on-site`
You can't create a query that includes both a provider and metadata filter, other than `calendar_id`. For example, `https://api.us.nylas.com/calendar?metadata_pair=key1:plan-party&title=Birthday` returns an error.
## Reduce response size with field selection
Field selection allows you to use the `select` query parameter to specify which fields you want Nylas to include in the response.
You can use field selection for all Nylas API endpoints, _except_ the following:
- All `DELETE` endpoints.
- All Attachments endpoints.
- All Smart Compose endpoints.
- The Send Message endpoint.
- The Create a Draft endpoint.
Field selection helps to reduce the size of the response, improves latency, and helps you avoid rate limiting issues. You can also use it in cases where you want to avoid working with information from your users that you think might be sensitive.
Field selection can evaluate top-level object fields only. You cannot use it to return only nested fields.
📝 Note: Nylas strongly suggests you always use field selection, so you only get the data that you need.
For example, the following request specifies Nylas should return only the `id` and `name` fields of the Calendar object.
```bash
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/me/calendars?select=id,name'
```
The response payload includes only the `id` and `name` fields in the `data` object, as in the example below.
```json
{
"request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
"data": [
{
"id": "5d3qmne77v32r8l4phyuksl2x",
"name": "My Calendar"
},
{
"id": "5d3qmne77v32r23aphyuksl2x",
"name": "My Calendar 2"
}
]
}
```
## Nylas encoding
Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise.
contact:
url: https://www.nylas.com/
servers:
- url: https://api.us.nylas.com
description: U.S.
- url: https://api.eu.nylas.com
description: E.U.
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
tags:
- name: Applications
description: |
In the context of the Nylas APIs, an "application" is the object record of your Nylas application.
🔍 The term "application" can refer to any of three concepts: your Nylas application, the project you're building ("your application" or "your app"), and applications that you use to connect to service providers ("provider auth applications"). We try to be specific in this documentation to avoid confusion. The API endpoints described here are for working with your Nylas application, specifically.
The Nylas application is the central resource for your Nylas implementation. It collects the [connectors](/docs/reference/api/connectors-integrations/) that you use to store information about third party services that your application connects to, and stores the [grants](/docs/reference/api/manage-grants/) that you create when using connectors.
Nylas applications also allow you to define your specific branding, change the look and feel of the Nylas Hosted authentication flow, and list your application's callback URIs.
## Application callback URIs
Your Nylas application includes a list of allowed callback URIs. These are known URIs that Nylas can direct users to after authentication. You need to define at least _one_ callback URI so your users can complete the auth flow.
You must include any callback URIs you plan to use in this list. If an auth payload includes a callback URI that isn't on the list, the whole authentication flow fails.
## Application limitations
⚠️ You can create, edit, and delete applications from the Nylas Dashboard. You cannot create, edit, or delete them using the Nylas APIs.
Keep the following limitations in mind as you work with Nylas applications:
- Applications are the central resource that stores other Nylas resources. You _must_ create an application before you can create any other parts of your Nylas implementation.
- Applications can be associated with only one project at a time. While your project can have more than one Nylas application to provide different authentication experiences, you cannot share applications, connectors, or grants between more than one project.
- Applications cannot be nested, and cannot be set up with parent-child relationships.
- Your application must have _at least one_ callback URI, or else it cannot finish the authentication flow, which means it cannot create grants. Nylas requires grants to access user data.
- In an ideal scenario, your application will have multiple callback URIs defined.
- name: Authentication APIs
description: |
Nylas provides two ways to handle authentication:
- **Bring Your Own (BYO) Authentication**, which uses the [`/v3/connect/custom` endpoint](/docs/reference/api/manage-grants/byo_auth/). In BYO Authentication, you already have refresh tokens for your users, and you just need to create grants for them in Nylas. This endpoint is also used for [virtual calendars](/docs/v3/calendar/virtual-calendars/), [IMAP auth](/docs/v3/auth/imap/), and [bulk auth grants](/docs/v3/auth/bulk-auth-grants/).
- **Hosted OAuth**, where the user completes an OAuth process on the provider, and the provider returns an access token. Depending on your needs, you can use either the user's access token or a Nylas API key to authorize requests after you complete the OAuth flow. See the [Authentication documentation](/docs/v3/auth/) for more information.
## Hosted authentication with OAuth
OAuth is the modern industry-standard protocol for authorization, and is used by major technology companies like Google, Apple, Microsoft, and others. Nylas supports authentication using the [OAuth 2.0 protocol](https://oauth.net/2/) and an additional option to use PKCE for extra security. [PKCE is an extension of the OAuth 2.0 protocol](https://oauth.net/2/pkce/) that prevents authorization code interception attacks, and makes OAuth 2.0 more secure on mobile devices and client-side applications.
During the OAuth 2.0 authentication flow, the user provides the account that they want to authenticate to Nylas, and they're prompted to allow your application's "scopes" (for example, `https://www.googleapis.com/auth/gmail.readonly` or `https://www.googleapis.com/auth/userinfo.profile`). Nylas always returns the fully-qualified Google scopes when you make an Authentication request that references a Google grant. For grants authenticated with other providers, Nylas returns the truncated scopes.
### Using Hosted OAuth
To use Hosted OAuth you first need to create a Nylas application in the Nylas Dashboard, then create a [connector](/docs/reference/api/connectors-integrations/) in that application for each authentication provider. This allows Nylas to get and store each provider's settings, and configure a set of default scopes to apply.
Nylas can detect which provider a user is authenticating with and redirect them to the correct provider's authentication system.
If the user decides to choose different provider settings for an OAuth 2.0 authorization protocol, Nylas allows them to override the default provider connector's settings.
A successful OAuth authorization results in a [grant](/docs/reference/api/manage-grants/) with the scopes that the user allowed.
See [Create grants with OAuth 2.0 and PKCE](/docs/v3/auth/hosted-oauth-accesstoken/#create-grants-with-oauth-2.0-and-pkce) for more information.
### Adding the "Sign in with Google" button
Your Google provider auth app must have a "Sign in with Google" button that meets [Google's branding guidelines](https://developers.google.com/identity/branding-guidelines). This applies to the OAuth flow for both personal Gmail (`@gmail.com`) and Workspace email addresses.
For Hosted authentication, Nylas recommends you do one of the following:
- Configure the OAuth login prompt by setting the `prompt` parameter with `select_provider` or `detect,select_provider`. For more information, see [Configure the OAuth login prompt](/docs/v3/auth/customize-login-prompt/).
⚠️ If you add a login_hint that is a personal Gmail or Workspace email address, and you don't configure a prompt during the Hosted auth flow, the user is directed immediately to the Google OAuth page without clicking the "Sign in with Google" button. This can result in delays or failure in verification.
- Use the pre-approved "Sign in with Google" button along with the "Connect your account" button (or other provider login buttons) in your application. For more information, see Google's official [Sign in with Google branding guidelines](https://developers.google.com/identity/branding-guidelines).
For Bring Your Own Authentication, use the pre-approved "Sign in with Google" button along with the "Connect your account" button (or other provider login buttons) in your application.
Learn more about [Google verification and security assessment](/docs/provider-guides/google/google-verification-security-assessment-guide/).
- name: Manage Grants
description: |
Grants are the main objects that power Nylas, because they _grant_ your Nylas application specific scopes of access (for example, permission to read email messages) to the user's resources and data on their provider. They also represent access granted to your application for certain resources.
There are several ways to create grants:
- Using [Hosted OAuth and an API key](/docs/v3/auth/hosted-oauth-apikey/).
- Using [Hosted OAuth and an access token](/docs/v3/auth/hosted-oauth-accesstoken/), with [optional PKCE](/docs/v3/auth/hosted-oauth-accesstoken/#create-grants-with-oauth-2.0-and-pkce) for additional security.
- Using [Bring Your Own Authentication](/docs/v3/auth/custom/).
- Using a special [bulk auth grant](/docs/v3/auth/bulk-auth-grants/) (also called a "service account").
You can re-authenticate grants using any of these methods, and Nylas handles all the re-authentication logic internally.
## Grant expiry
Grants, and their access tokens and refresh tokens are controlled by the provider, not Nylas. Nylas can request that the provider invalidate or revoke a grant, but can't prevent the provider from expiring a grant.
Usually when a provider expires a grant it is after a period of inactivity, and the provider expires the associated access token for security reasons. To prevent grants from expiring, encourage users to actively engage with their accounts and regularly refresh the access token with a valid refresh token.
## Re-authentication and notifications
Grants can become invalid for many reasons (for example, the user changing their password). When a grant becomes invalid, the user must re-authenticate to access your application.
When a grant becomes invalid, Nylas loses access to the affected user's data and stops sending notifications about changes to its objects. When the user re-authenticates, Nylas looks at when their grant last authenticated successfully. If it was less than 72 hours ago, Nylas looks for any changes that happened since the last successful sync and sends you notifications about those events. This can be _a lot_ of notifications.
If the grant was out of service for more than 72 hours, Nylas doesn't send backfill notifications. When this happens, look for the `grant.expired` and `grant.updated` notifications and query the Nylas APIs for objects that changed between those timestamps.
## Grant limitations
When working with grants, keep the following limitations in mind:
- You can re-authenticate a grant to add new scopes, remove scopes, or extend its expiry date.
- Each grant belongs to a specific Nylas connector (because they come from a specific provider), in a specific Nylas application. A grant cannot be associated with multiple connectors or applications.
- Grants expire after a pre-defined period of time. When this happens, they must be re-authenticated.
## Grant notifications
You can subscribe to the following triggers so Nylas notifies you about changes to your users' data:
- `grant.created`
- `grant.updated`
- `grant.deleted`
- `grant.expired`
For more information, see the [Grant notification schemas](/docs/reference/notifications/#grant-notifications).
- name: Connectors (Integrations)
description: |
In Nylas, a connector (formerly called an "integration") stores information that allows your Nylas application to connect to a third party services, such as a provider auth application from Google (GCP), Microsoft (Azure), or to an IMAP provider. You must create a connector in your Nylas application for each specific provider before you can create Grants and access user data from that provider.
A Nylas connector stores data about how your Nylas application contacts the provider, the default permissions the Nylas application requests, and is generally the starting point for any authentication with that provider.
## Connector contents
The connector stores a label provided by the user, the provider name or type (for example, `google`/`microsoft`/`imap`/`virtual_calendar`), an expiry time for the hosted authentication link, and the provider settings.
The "provider's settings" come from the provider itself when you create your provider auth application on Google, Azure, or IMAP. For example, a provider's settings might contain the provider auth application's `client_id` and `client_secret`. Nylas stores these values securely and uses them as default credentials when authenticating with that provider.
Nylas follows modern security best practices to encode and encrypt these provider settings, to ensure that they can never be obtained by a third party, including Nylas internal employees.
### What are limitations of connectors?
Connectors are associated with a single [Nylas application](/docs/reference/api/applications/).
You can have only one Nylas connector for each type of provider. For example, your Nylas application can have only one Google connector.
If you want to create a grant for a different provider auth application, (for example, on a different GCP project, but you already have a default Google connector), you can create additional credentials for your connector. Each connector can have multiple credentials, where each credential represents a different provider auth application. For more information, see [Using multiple provider applications](/docs/v3/auth/using-multiple-provider-applications/).
- name: Connector credentials
description: |
A Nylas connector credential is a special type of record that securely stores information (such as provider settings) that allows you to connect using an administrator account. Nylas securely stores, hashes, and encrypts the connector credential's sensitive data, and the contents vary depending on the authentication provider.
Bulk authentication grants use connector credentials to connect or reconnect user accounts to your Nylas application. You can also use them to override a connector's settings to perform administrative tasks. For more information, see the [Bulk authentication grant documentation](/docs/v3/auth/bulk-auth-grants/).
Both Google and Microsoft bulk authentication grants can use connector credentials.
To override the default values in a provider's connector settings (for example, the `client_secret` and `client_id`), [create a grant using Bring Your Own Authentication](/docs/v3/auth/bring-your-own-authentication/) and provide the connector credential in your request payload, along with the values to override.
## Connector credential limitations
Keep the following limitations in mind as you work with connector credentials:
- A connector credential _must_ be connected to an existing Nylas connector.
- Each connector credential must have a unique name.
- When you make a [Create Credential request](/docs/reference/api/connector-credentials/create_credential/), Nylas checks if a connector credential with the same parameters exists. If one _does_ exist, Nylas uses that connector credential instead of creating one.
- name: Workspaces
description: |
Workspaces group and organize grants in a Nylas application by a common attribute, such as the email address domain (for example, `nylas.com`).
## Assign grants to workspaces
Nylas offers two endpoints to manage workspaces and the grants they contain:
- [**Automatically Group Grants into Workspaces**](/docs/reference/api/workspaces/autogroup-workspace/): Starts a background job that, based on your filters, processes existing grants in your Nylas application and automatically sorts them to existing workspaces. If necessary, Nylas automatically creates new workspaces.
- [**Update Workspace Assignments**](/docs/reference/api/workspaces/manually-assign-workspace/): Manually specify a workspace ID and up to 500 grants to add or remove from that workspace.
## Default workspace
A Nylas application can have a _default workspace_, which Nylas creates automatically when the application is created and manages on your behalf. Applications created before default workspaces were introduced might not have one. When you retrieve workspaces, Nylas identifies the default workspace with `"default": true`, and the application object exposes its ID as `default_workspace_id`.
When a new grant is created without an explicit `workspace_id`, Nylas first tries to auto-group it into a workspace that has `auto_group` enabled and a `domain` that matches the grant's email address domain. If no domain workspace matches, Nylas assigns the grant to the application's default workspace, if one exists.
The default workspace is protected: you can update only its `policy_id` and `rule_ids` values (changes to `name` or `auto_group` return an error), and you can't delete it. A workspace's `domain` can't be changed after creation, on any workspace.
## Policies and rules
Workspaces can carry a [policy](/docs/v3/agent-accounts/policies-rules-lists/) (`policy_id`) and [rules](/docs/v3/agent-accounts/policies-rules-lists/#rules) (`rule_ids`). Agent Accounts in a workspace use the policy attached to the workspace for limits and spam settings, and the rules attached to the workspace for mail filtering.
## Workspace limitations
- Workspaces are designed to group grants by the top-level domain (TLD) of users' email addresses. Nylas allows you to manually assign grants to any workspace, but that workspace must have `auto_group` set to `false`.
- When `auto_group` is set to `false`, Nylas doesn't automatically assign grants to that workspace. You'll need to manually assign grants to the workspace using the [Update Workspace Assignments endpoint](/docs/reference/api/workspaces/manually-assign-workspace/).
- When `auto_group` is `true`, Nylas automatically assigns new grants to the workspace. You can move grants to a different workspace by making an [Update Workspace Assignments request](/docs/reference/api/workspaces/manually-assign-workspace/).
- name: Manage API keys
description: |
The Manage API Keys endpoints let you create, list, and delete API keys from your Nylas application outside of the Nylas Dashboard.
## Nylas Service Account
⚠️
Before you can use the Manage API Keys endpoints, you need to create a Nylas Service Account. If you have a contract with us, you can
contact Nylas Support for more information.
🔍 The term "webhook" can refer to any of three component parts: a location where you receive notifications (the "webhook URL" or "webhook endpoint"), a subscription to events that you want notifications for ("webhook triggers"), or the information payload that is sent when a trigger condition is met (the "webhook notification"). We try to be specific in this documentation to avoid confusion.
To configure webhooks, you first need a webhook URL in your project where your app can receive incoming webhook payloads, and a list of triggers that you want to receive notifications for. See the [list of available trigger types](/docs/reference/notifications/) for more information.
Webhooks in Nylas are not compatible with Ngrok because of throughput limiting concerns. Nylas recommends you use [VS Code port forwarding](https://code.visualstudio.com/docs/editor/port-forwarding), [Hookdeck](https://hookdeck.com/), or a similar webhook tool.
## Testing webhooks
Nylas includes two utility API endpoints to help you identify problems with your webhook configuration.
Use the [Send Test Event endpoint](/docs/reference/api/webhook-notifications/send_test_event/) to check if your project's webhook destination is configured correctly. This endpoint sends a test webhook payload, and listens for a success acknowledgement from the webhook destination.
Use the [Get Mock Notification Payload endpoint](/docs/reference/api/webhook-notifications/get_mock_webhook_payload/) to see example notification payloads for the different Nylas events.
## Monitor grant status
The most important webhooks to subscribe to are those related to grant status: `grant.created`, `grant.updated`, `grant.deleted`, and `grant.expired`. They allow you to automate important grant lifecycle processes, like onboarding messages, data refreshes, and backend deletions.
The `grant.expired` trigger notifies you when a user needs to re-authenticate their account. When you receive a `grant.expired` notification, you can take appropriate action (for example, notifying the user or starting a background re-authentication process).
📝 When a grant becomes invalid, Nylas cannot access the user's data and does not send you webhook notifications about it. When you re-authenticate a grant, Nylas looks at when the grant last authenticated successfully. If it was less than 72 hours ago, Nylas looks for any changes that happened since the time of the last successful sync, and sends you notifications about them. This can be a lot of notifications.
If the grant has been out of service for more than 72 hours, Nylas does _not_ send backfill notifications. In this case, look for the `grant.expired` and `grant.updated` notifications, and query the Nylas API for objects that changed between those timestamps.
## iCloud limitation for Calendar notifications
Because iCloud doesn't support the `primary` property for calendars, Nylas sends `calendar.updated` notifications for changes to all calendars on an iCloud account.
## Gmail metadata notifications
Nylas sends [`message.created.metadata` and `message.updated.metadata` notifications](/docs/reference/notifications/#message-metadata-notifications) for Google grants that include the `/gmail.metadata` scope. These notifications have limited data because of the restrictive scope. Even if a grant has more permissive scopes, Google falls back to the `/gmail.metadata` permissions.
When you subscribe to a `message.*` webhook trigger, Nylas automatically sends `message.*.metadata` notifications as well. You don't need to subscribe to these triggers separately, and they don't appear as a configuration option in the Nylas Dashboard. For more information, see our list of [available trigger types](/docs/reference/notifications/).
## Payload size limit and truncation
Nylas sends webhook notifications as JSON payloads that contain the object that triggered the notification, up to a maximum payload size of 1MB. If a webhook notification exceeds the size limit, Nylas truncates the payload by removing the body content, and adds the `.truncated` suffix to the webhook trigger name (for example, `message.created.truncated`). This reduces the size of the payload and improves performance.
When you receive a truncated webhook notification, you'll need to re-query the Nylas APIs to get the data. For example, if you receive a `message.updated.truncated` notification, make a [Get Message request](/docs/reference/api/messages/get-messages-id/) that includes the message ID.
If you subscribe to a webhook trigger that can be truncated, Nylas automatically sends you `.truncated` notifications as well. You don't need to subscribe to webhook triggers with the `.truncated` suffix separately, and the suffix doesn't appear as a option in the Nylas Dashboard. See the [list of available trigger types](/docs/reference/notifications/) for more information.
You can monitor for `.truncated` notifications to create automations that retrieve the full affected object. For example, you can create an automation that makes a [`GET /v3/grants//messages/` request](/docs/reference/api/messages/get-messages-id/) when your application receives a `message.updated.truncated` notification.
## Payload compression
Set `compressed_delivery` to `true` on a webhook destination and Nylas gzip-compresses each notification before `POST`ing it to your endpoint, adding a `Content-Encoding: gzip` header. Compressed payloads are also opaque to firewalls and WAFs that would otherwise block requests containing HTML in email bodies. Verify the `X-Nylas-Signature` header against the raw compressed body _before_ decompressing. For full setup and when to use it, see [Reducing payload size with compression](/docs/dev-guide/best-practices/compression/).
## How to handle webhook failures
Nylas implements "circuit breaker" logic to handle failing webhooks. See [improvements to failure notifications](/docs/new/in-v3/webhooks-changes/#improvements-to-webhook-failure-notifications) and [Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for more information.
- **Failing state**: If Nylas cannot deliver a webhook notification to the destination endpoint for 95% of webhooks over a 15-minute period, Nylas marks the endpoint as `failing` but continues sending notifications to it. Nylas also sends you a message when this happens so you can troubleshoot the issue.
- **Failed state**: If Nylas cannot deliver 95% of webhook notifications to a `failing` endpoint over the next 72 hours, Nylas marks the endpoint as `failed` and stops sending notifications to it. Nylas also sends you a message when this happens so you can address the issue.
⚠️ Nylas does not automatically restart or reactivate failed webhooks.
This change gives you full control over when your webhook endpoint becomes active again, so you can verify that it's working as expected before you restart normal webhook traffic.
## Duplicate webhook notifications
Nylas guarantees "at least once" delivery of webhooks. You might receive duplicate webhook notifications because of the provider's behavior (for example, when Google and Microsoft Graph send upserts).
## Webhook triggers
- `contact.updated`: A contact was modified or updated.
- `contact.deleted`: A contact was deleted.
- `calendar.created`: A calendar was created.
- `calendar.updated`: A calendar was updated or modified.
- `calendar.deleted`: A calendar was deleted.
- `event.created`: An event was created on a user's calendar.
- `event.updated`: An event was updated or modified.
- `event.deleted`: An event was deleted.
- `grant.created`: A new grant was authenticated.
- `grant.updated`: A grant was modified, updated, or re-authenticated.
- `grant.deleted`: A grant was deleted as a result of the user making a [Delete Grant request](/docs/reference/api/manage-grants/delete_grant_by_id/).
- `grant.expired`: A grant's credentials have expired, and the user must re-authenticate.
- `message.created`: A message was created.
- `message.created.cleaned`: A cleaned (parsed) version of a newly created message was processed. Requires Clean Conversations to be enabled.
- `message.updated`: A message was updated.
- `message.send_success`: A scheduled message was sent and delivered successfully. You must set the `send_at` parameter in a message to use this trigger. For more information, see [Schedule messages to send in the future](/docs/v3/email/scheduled-send/).
- `message.send_failed`: A scheduled message was sent, but was not delivered. You must set the `send_at` parameter in a message to use this trigger. For more information, see [Schedule messages to send in the future](/docs/v3/email/scheduled-send/).
- `message.bounce_detected`: (Available for Google, Microsoft Graph, iCloud, and Yahoo) A message bounced or was not delivered.
- `message.opened`, `message.opened.legacy`: A participant opened a tracked message.
- `message.link_clicked`, `message.link_clicked.legacy`: A participant clicked a link in a tracked message.
- `thread.replied`, `thread.replied.legacy`: A participant replied to a message in a tracked thread.
- `folder.created`: A folder or label was created.
- `folder.updated`: A folder or label was modified or updated.
- `folder.deleted`: A folder or label was deleted.
- `booking.created`: A new Scheduler event was created.
- `booking.rescheduled`: A Scheduler event was rescheduled through Scheduler.
- `booking.cancelled`: A Scheduler event was cancelled through the Scheduler.
- `booking.pending`: A pending booking was created.
- `booking.reminder`: Nylas sent a reminder about a booking.
For more information on webhook trigger types, and for schema examples, see the [notification schemas](/docs/reference/notifications/).
## Scheduler events in Calendar webhooks
Calendar events that Nylas Scheduler creates also produce standard `event.*` notifications. Nylas stamps these events with metadata so you can identify them in Calendar webhooks:
- `source`: Always `scheduler`.
- `key5`: The Scheduler Configuration ID.
- `scheduler_last_start`, `scheduler_last_end`, `scheduler_updated_at`: Unix timestamps (as strings) that record the meeting time Scheduler most recently set, at booking creation and on each reschedule.
To tell Scheduler-driven changes apart from edits made directly on the organizer's calendar, compare an `event.updated` notification's `when` times against `scheduler_last_start` and `scheduler_last_end`: if the times match, the change came through Scheduler (Nylas also sends a `booking.rescheduled` notification), and if they differ, the event was changed directly on the calendar.
These metadata entries share the event's customer-visible `metadata` object. If you update an event's metadata using the Events API, include the Scheduler-stamped entries in your request — updates replace the metadata object as a whole.
- name: Pub/Sub Notifications
description: |
Nylas offers two ways to get notifications of what's happening on the provider. You can either subscribe to webhook notifications, or you can set up a notification channel.
Nylas offers Pub/Sub and Amazon SNS notification channels. These can be used in place of, or in addition to, normal webhook notifications.
To use Pub/Sub notifications, you first need to set up a Pub/Sub queue on Google Cloud Platform. For detailed set up instructions see the [Pub/Sub notifications documentation](/docs/v3/notifications/pubsub-channel/).
To use Amazon SNS notifications, you need to set up an SNS topic and IAM role in your AWS account. For detailed set up instructions see the [Amazon SNS notifications documentation](/docs/v3/notifications/sns-channel/).
Nylas notification channels use the same notification [trigger types and schemas](/docs/reference/notifications/) as webhook notifications, and require the same [provider scopes](/docs/dev-guide/scopes/).
## Payload compression
Both Pub/Sub and SNS channels accept a `compressed_delivery` boolean that gzip-compresses each notification payload before delivery. Nylas adds a `content_encoding` message attribute (`gzip` for Pub/Sub, `gzip+base64` for SNS) so your subscriber knows which messages to decompress. We strongly recommend enabling it on SNS channels, where the 256 KB message limit makes compression the simplest way to avoid payload truncation. For setup and decode patterns, see [Reducing payload size with compression](/docs/dev-guide/best-practices/compression/).
## Monitor grant status
The most important notifications to subscribe to are those related to grant status: `grant.created`, `grant.updated`, `grant.deleted`, and `grant.expired`. They allow you to automate important grant lifecycle processes, like onboarding messages, data refreshes, and backend deletions.
The `grant.expired` trigger notifies you when a user needs to re-authenticate their account. When you receive a `grant.expired` notification, you can take appropriate action (for example, notifying the user or starting a background re-authentication process).
📝 When a grant becomes invalid, Nylas cannot access the user's data and does not send you notifications about it. When you re-authenticate a grant, Nylas looks at when the grant last authenticated successfully. If it was less than 72 hours ago, Nylas looks for any changes that happened since the time of the last successful sync, and sends you notifications about them. This can be a lot of notifications.
If the grant has been out of service for more than 72 hours, Nylas does _not_ send backfill notifications. In this case, look for the `grant.expired` and `grant.updated` notifications, and query the Nylas API for objects that changed between those timestamps.
- name: Amazon SNS Notifications
description: |
Amazon SNS notification channels allow you to receive Nylas event notifications through Amazon Simple Notification Service (SNS) instead of webhooks.
To use Amazon SNS notifications, you need to set up an SNS topic and an IAM role in your AWS account. The topic ARN must start with `arn:aws:sns:`. The IAM role must allow Nylas to assume it via STS `AssumeRoleWithWebIdentity` and must have `sns:Publish` permission on the topic. For detailed set up instructions, see the [Amazon SNS notification channel documentation](/docs/v3/notifications/sns-channel/).
The Amazon SNS notification channels use the same notification [trigger types and schemas](/docs/reference/notifications/) as webhook notifications, and require the same [provider scopes](/docs/dev-guide/scopes/).
Nylas strongly recommends setting `compressed_delivery` to `true` when you create an SNS channel. SNS enforces a 256 KB message size limit, and gzip compression is the simplest way to keep large `message.*` notifications inside it. Nylas adds a `content_encoding: gzip+base64` message attribute so your subscriber knows which messages to decompress. For setup and the decode pattern, see [Reducing payload size with compression](/docs/dev-guide/best-practices/compression/).
- name: Messages
description: |
The Nylas Send API allows you to send messages immediately, and schedule them to be sent in the future (asynchronously). You can save scheduled messages either in Nylas, or as Draft objects on the provider. The Send API uses the same commands to manage messages across all providers, and can refer to specific messages using the provider's `message_id`.
Nylas uses webhooks to let you know when an email message has been sent. The webhook's message includes a status, a reason description, and the Nylas request ID. For more information, see the [notifications documentation](/docs/v3/notifications/).
## Adding attachments to messages
Use the Messages endpoints to add and modify files attached to email messages as you send them. The [Attachments APIs](#tag--Attachments) allow you to download or get the metadata about an existing attachment, but you use the Messages API to add or modify the attachments. For more information, see [Working with email attachments](/docs/v3/email/attachments/).
### Provider IDs for messages
Nylas uses an object's provider ID to refer to the object, and different providers return differently formatted IDs. For IMAP messages, Nylas extracts the ID from the `message-id` header. For Google and Microsoft, the object ID comes from the provider's internal ID.
## Metadata on messages
You can add metadata to new and existing messages by including the `metadata` sub-object in your `POST`, `PUT`, or `PATCH` request. For more information, see the [Metadata documentation](/docs/dev-guide/metadata/).
[Agent Account](/docs/v3/agent-accounts/) grants support metadata on messages, with the same 50-pair limit and the same five indexed reserved keys as connected grants.
## Messages scopes
The table below lists the Messages endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :------------------------------------------------------- | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| **GET** `/messages`
**GET** `/messages/` | `/gmail.readonly` ☑️
`/gmail.modify` | `Mail.Read` ☑️
`Mail.ReadWrite`
`Mail.Read.Shared``Mail.ReadWrite.Shared` |
| **PUT**`/messages/` | `/gmail.modify` ☑️ | `Mail.ReadWrite` ☑️
`Mail.ReadWrite.Shared` |
| **DELETE** `/messages/` | `/gmail.modify` ☑️
`https://mail.google.com/` (for hard-delete) | `Mail.ReadWrite` ☑️
`Mail.ReadWrite.Shared` |
| **POST** `/messages/send` | `/gmail.send` ☑️
`/gmail.compose`
`/gmail.modify` | `Mail.ReadWrite` ☑️
`Mail.ReadWrite.Shared` |
No scopes are required for the `/messages/schedules` endpoints, because scheduled messages are stored with Nylas. You will need `gmail.send` or `Mail.ReadWrite` to send scheduled messages, however.
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
## Messages notifications
You can subscribe to the following triggers so Nylas notifies you about changes to your users' data:
- `message.created`
- `message.updated`
You can subscribe to the following triggers to get notifications about the status of a scheduled message:
- `message.send_success`
- `message.send_failed`
- `message.bounce_detected` (Available for Google, Microsoft Graph, iCloud, and Yahoo.)
To receive message notifications, you must [enable specific scopes](/docs/dev-guide/scopes/#email-api-scopes) that allow Nylas to monitor for these events. For more information, see the [Message notification schemas](/docs/reference/notifications/#message-notifications).
## Message tracking and send status monitoring
You can configure options to track when a message you sent has been opened, when links inside of it are clicked, and when someone replies to a thread. For more information, see the [message tracking documentation](/docs/v3/email/message-tracking/).
Nylas includes a [`message.bounce_detected` notification](/docs/reference/notifications/#message-bounce-detected-notifications) for Google, Microsoft Graph, iCloud, and Yahoo that triggers when a message that you send bounces. You can subscribe to the trigger to monitor for bounced messages.
You can use the [`message.send_success`](/docs/reference/notifications/#message-send-success-notifications) and [`message.send_failed`](/docs/reference/notifications/#message-send-failed-notifications) triggers to monitor the status of messages that you send using Scheduled Send. For these triggers to work, you must set the `send_at` parameter in your [Send Message request](/docs/reference/api/messages/send-message/). For more information, see [Schedule messages to send in the future](/docs/v3/email/scheduled-send/).
## Search messages
Search for messages by making a [`GET /v3/grants//messages` request](/docs/reference/api/messages/get-messages/) that includes any of the following query parameters:
- `subject`, `thread_id`
- `any_email`, `to`, `from`, `cc`, `bcc`
- `received_before`, `received_after`
- `in`, `unread`, `starred`, `has_attachment`
- `search_query_native`
- `fields`
⚠️
Nylas doesn't support filtering for folders using keywords or attributes (for example,
in:inbox returns a
400 error). Instead, you should use the folder ID with
in to get the data you need.
⚠️
Nylas doesn't support filtering for folders using keywords or attributes (for example,
in:inbox returns a
400 error). Instead, you should use the folder ID with
in to get the data you need.
**GET** `/folders/` | `/gmail.labels` ☑️
`/gmail.modify` | `Mail.Read` ☑️
`Mail.ReadWrite`
`Mail.ReadWrite.Shared`
`Mail.Read.Shared` |
| **POST** `/folders`
**PUT** `/folders/`
**DELETE** `/folders/` | `/gmail.labels` ☑️
`/gmail.modify` | `Mail.ReadWrite` ☑️
`Mail.ReadWrite.Shared` |
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
## Folders notifications
You can subscribe to the following triggers so Nylas notifies you about changes to your users' data:
- `folder.created`
- `folder.updated`
- `folder.deleted`
For more information, see the [Folder notification schemas](/docs/reference/notifications/#folder-notifications).
## Folders limitations
Keep the following limitations in mind when you're working with folders:
- Because providers structure folders in different ways, Nylas doesn't support nested folders. Instead, Nylas flattens sub-folders and displays them in the same list as top-level folders.
- For Microsoft, you can use the `parent_id` to reflect the folder hierarchy in your project.
- On IMAP, the hierarchy is reflected in the folder name (for example, `Accounting.Taxes` or `INBOX\Accounting\Taxes`).
- Because of how IMAP providers handle folders and labels, the folder names that Nylas returns aren't always the same as those listed in the provider's UI (for example, the "Trash" folder might be "Deleted Messages" in a Nylas response). Instead of relying on names, you should [use attributes and IDs to get the data you need](/docs/v3/email/folders/#folder-and-label-behavior).
- IMAP servers use provider-specific formats to represent the folder name and hierarchy. When you make a [Create Folder request](/docs/reference/api/folders/post-folder/) for an IMAP account, Nylas creates a folder with the name you pass. If the name includes the IMAP separator that corresponds with the server settings, Nylas creates a sub-folder based on the folder name.
- Nylas doesn't support using keywords to reference folders on the provider (for example, `in:inbox` returns a [`400` error](/docs/api/errors/400-response/)). Instead, Nylas recommends you use specific folder `id`s to get the data you need.
- It might take up to 10 minutes for folders to be available in Nylas after you authenticate an IMAP grant.
- name: Attachments
description: |
You can use the `attachments` schema in a [Send Message request](/docs/reference/api/messages/send-message/) to send attachments, regardless of the email provider. You use the [Drafts](/docs/reference/api/drafts/) endpoints to add and modify files attached to drafts. The Attachments endpoints let you download or get the metadata for existing attachments. For more information, see [Working with email attachments](/docs/v3/email/attachments/).
If you're using draft support, the draft (including the attachment) is stored on the provider. If you're not using draft support, Nylas stores the attachment.
You can make a [Get Attachment Metadata request](/docs/reference/api/attachments/get-attachments-id/) to retrieve a single attachment's metadata using its ID.
## What counts as an attachment?
In Nylas, an attachment is any file included either inline as part of a message, or attached to a message as a file.
Some major email providers, such as Google and Microsoft, have their own cloud storage ("drive") services. These files usually appear as links in the message body instead of attachments on the Message object. Google Drive lets users attach files either as a link, or a file. Microsoft One Drive attachments always appear as links in the message body.
## Attachment size discrepancies
When Nylas returns information about an attachment, its listed size might be different from the actual size of the file. This is because of provider encryption methods, message headers, and rounding on the provider side. For example, if you receive a 3480-byte attachment in an email, Nylas might list it as 3680 bytes.
## Attachments scopes
The table below lists the Attachments endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :----------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------- |
| **GET** `/attachments/`**GET** `/attachments//download` | `/gmail.readonly` ☑️`/gmail.modify` | `Mail.Read` ☑️`Mail.ReadWrite``Mail.ReadWrite.Shared``Mail.Read.Shared` |
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
## Query IMAP server directly
Set the `query_imap` query parameter to `true` in your [Get Attachment Metadata](/docs/reference/api/attachments/get-attachments-id/) or [Download Attachment](/docs/reference/api/attachments/get-attachments-id-download/) requests to query the IMAP server directly instead of the Nylas database. This lets you get the most up-to-date information from the IMAP server, or data older than the default three-month retention time.
Keep in mind that most IMAP servers are slow and have low [rate limits](/docs/dev-guide/platform/rate-limits/). Nylas might take more time to return responses compared to requests that don't use the `query_imap` query parameter. If an account has many folders, or you're querying for a large attachment, your request can take even longer.
## Microsoft attachment size discrepancies
If you're working with Microsoft grants, you might notice a small difference between the attachment size in Nylas' response and the actual size of the downloaded file. This is because Nylas' attachment size calculation includes any MIME encoding headers. Nylas returns this value to be consistent with the provider, and so that it doesn't have to pre-process all attachment content.
When working with attachments on Microsoft grants, we recommend you...
- Treat the metadata `size` field as an estimate for UI display purposes.
- Always use the actual downloaded file for storage calculations and file operations.
- Implement flexible buffer handling when the exact byte count of a file matters to your project.
- Test your Nylas integration with a number of different attachment types and sizes.
- name: Smart compose
description: |
The Smart Compose endpoints extend the Nylas Messages API. Currently, Smart Compose supports only two methods of getting AI responses: you can either receive them as a REST response in a single JSON blob, or use server-sent events (SSE) to stream the response tokens as Nylas receives them.
If you want to receive responses using the REST method, add the `Accept: application/json` header. Nylas will return a single JSON blob. If you use this method, you might want to add a "working" indicator to your UI, as response times may vary.
To enable SSE for a request, add the `Accept: text/event-stream` header.
For more information, see the [Smart Compose documentation](/docs/v3/email/smart-compose/).
## Smart Compose scopes
The table below lists the Smart Compose endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------- |
| **POST** `/messages/smart-compose`**POST** `/messages//smart-compose` | `/gmail.readonly` ☑️`/gmail.modify` | `Mail.Read` ☑️`Mail.ReadWrite``Mail.ReadWrite.Shared``Mail.Read.Shared` |
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
- name: Calendar
description: |
The Nylas Calendar API allows you to create and manage calendars, and access the events they contain. Nylas uses the same commands to manage calendars across providers, and you can refer to specific calendars using the provider's `calendar_id`.
Depending on the provider, a calendar might be accessed by only one person, or shared among several users. Some common calendars might include Personal, Work, or Shared calendars.
A calendar might contain overlapping events or conflicting schedules. You can use the [Get Availability endpoint](/docs/reference/api/calendar/post-availability/) to find the best time for an event by identifying time periods that have no conflicting events among all participants.
## Find a calendar ID
You must specify a `calendar_id` in all calls you make to the Nylas Calendar API. You can use `primary` to specify the primary calendar associated with a grant, or you can look up the ID of the calendar that you want to work with and use that.
For virtual calendars, the `primary` calendar is the first created for a virtual account. You _cannot_ delete a virtual calendar that's designated as `primary`.
For iCloud, there is no `primary` calendar.
## Free/Busy information
The [Get Free/Busy Schedule endpoint](/docs/reference/api/calendar/post-calendars-free-busy/) is available for all providers, including Virtual Calendars, except for iCloud.
The [Get Availability endpoint](/docs/reference/api/calendar/post-availability/) doesn't support the `free_busy` object.
## Virtual calendars
Nylas allows you to create virtual calendars for users and resources that might not have calendars on your providers (for example, external contractors or meeting rooms). You can use the Nylas Calendar and Events APIs with the virtual accounts that power virtual calendars, just like you would any other account. Virtual accounts don't provide email or contacts features, so you can't use them with the Email or Contacts APIs.
For more information, see [Using virtual calendars](/docs/v3/calendar/virtual-calendars/).
## Metadata on calendars
You can add metadata to new and existing calendars by including the `metadata` sub-object in your `POST`, `PUT`, or `PATCH` request. For more information, see the [Metadata documentation](/docs/dev-guide/metadata/).
## Calendar scopes
The table below lists the Calendar endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **GET** `/calendars`**GET** `/calendars/`**POST** `/calendars/free-busy`**POST** `/calendars/availability` | `/calendar.readonly` ☑️`/calendar` | `Calendars.Read` ☑️`Calendars.ReadWrite` |
| **POST** `/calendars`**PUT** `/calendars/`**DELETE** `/calendars/` | `/calendar` ☑️ | `Calendars.ReadWrite` ☑️ |
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
## Calendar activity notifications
You can subscribe to the following triggers so Nylas notifies you about changes to your users' calendar data:
- `calendar.created`
- `calendar.updated`
- `calendar.deleted`
For more information, see the [Calendar webhook notification schemas](/docs/reference/notifications/#calendar-notifications).
## Microsoft event considerations
Microsoft Outlook events are often shared across all calendars in a user's account. If the user creates an event on one of their calendars, you can retrieve it using another calendar ID from their grant.
- name: Events
description: |
Events represent scheduled items on a calendar. The Nylas Events API uses the same commands to manage events across providers, and can refer to specific events using the provider's `event_id` parameter. Events can be public, private, or shared among a group of users. They might include details like participants, locations, and timing, along with other information.
The Events API includes the [Send RSVP endpoint](/docs/reference/api/events/send-rsvp/), which allows you to send RSVPs directly from your Nylas application, even for participants who might not have access to edit a specific event.
## Metadata on events
You can add metadata to new and existing events by including the `metadata` sub-object in your `POST`, `PUT`, or `PATCH` request. For more information, see the [Metadata documentation](/docs/dev-guide/metadata/).
[Agent Account](/docs/v3/agent-accounts/) grants support metadata on events, with the same 50-pair limit and the same five indexed reserved keys as connected grants.
## Virtual calendars
Nylas allows you to create virtual calendars for users and resources that might not have calendars on your providers (for example, external contractors or meeting rooms). You can use the Nylas Calendar and Events APIs with the virtual accounts that power virtual calendars, just like you would any other account. Virtual accounts don't provide email or contacts features, so you can't use them with the Email or Contacts APIs.
For more information, see [Using virtual calendars](/docs/v3/calendar/virtual-calendars/).
## Events scopes
The table below lists the Events endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------- |
| **GET** `/events`**GET** `/events/` | `/calendar.events.readonly` ☑️`/calendar.events``/calendar` (Required to use `primary` keyword when referencing calendars.) | `Calendars.Read` ☑️`Calendars.ReadWrite` |
| **POST** `/events`**PUT** `/events/`**DELETE** `/events/`**POST** `/events//send-rsvp` | `/calendar.events` ☑️`/calendar` (Required to use `primary` keyword when referencing calendars.) | `Calendars.ReadWrite` ☑️ |
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
## Events notifications
You can subscribe to the following notification triggers so Nylas notifies you about changes to your users' event data:
- `event.created`
- `event.updated`
- `event.deleted`
These are separate from the event reminders which you might send to your users. For more information, see the [Event webhook notification schemas](/docs/reference/notifications/#event-notifications).
## Microsoft event considerations
Microsoft Outlook events are often shared across all calendars in a user's account. If the user creates an event on one of their calendars, you can retrieve it using another calendar ID from their grant.
## iCloud query considerations
If you're searching for an event within a certain time range on an iCloud account, the difference between `start` and `end` can't be greater than six months. If you include a time range greater than six months, Nylas returns an "Invalid request" error similar to the following example.
```json
"error": {
"type": "invalid_request_error",
"message": "The maximum time range for iCloud event queries is 6 months."
}
```
For more information about searching for events, see [Searching with Nylas](/docs/dev-guide/best-practices/search/#search-for-events).
- name: Room resources
description: |
The Nylas Contacts API allows you to return information about rooms that you can book for meetings, conferences, and other events.
## Room resource booking scopes
The table below lists the Microsoft and Google scopes for room resource bookings. All scopes must include the fully qualified URI path for the provider, as defined in the table headers. These have been omitted from the scopes due to space constraints.
The ☑️ character indicates the most restrictive scopes you can use for each provider.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :---------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **GET** `/v3/grants//resources` | `/admin.directory.resource.calendar.readonly` ☑️️ | `Place.Read.All` ☑️️ |
For more information, see [Using scopes to request user data](/docs/dev-guide/scopes/).
- name: Contacts
description: |
The Nylas Contacts API allows you to create and manage contacts, and organize them into contact groups. Nylas uses the same commands to manage contacts across providers, and can refer to a specific contact using the provider's `contact_id`.
## Contacts scopes
The table below lists the Contacts endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------- | :----------------------------------------------------- |
| **GET** `/contacts`**GET** `/contacts/`**GET** `/contact_groups` | `/contacts.readonly` ☑️`/contacts.other.readonly` ☑️`/directory.readonly`\* ☑️ | `Contacts.Read` ☑️`People.Read`\* ☑️ |
| **POST** `/contacts`**PUT** `/contacts/`**DELETE** `/contacts/` | `/contacts` ☑️ | `Contacts.ReadWrite` ☑️ |
📝 Note: To access Contacts with the inbox source, you must use the contacts.other.readonly Google scope and the People.Read Microsoft scope. For Contacts with the domain source, you must use the directory.readonly Google scope and the People.Read Microsoft scope.
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
## Contacts notifications
You can subscribe to the following triggers so Nylas notifies you about changes to your users' data:
- `contact.updated`
- `contact.deleted`
For more information, see the [Contact notification schemas](/docs/reference/notifications/#contact-notifications).
- name: Notetaker
description: |
Nylas Notetaker is a real-time meeting bot that you can invite to your online meetings. It records and transcribes your discussion, and delivers results to you using the Nylas API and webhook notifications.
The [`/v3/grants//notetakers` endpoints](/docs/reference/api/notetaker/) let you interact with Nylas Notetaker while referencing a specific grant so you can use Notetaker's [calendar sync features](/docs/v3/notetaker/calendar-sync/) for your authenticated users.
The [`/v3/notetakers` endpoints](/docs/reference/api/standalone-notetaker/) let you send Notetakers that aren't connected to a grant as **standalone Notetakers**.
## Calendar sync
Notetaker works with the Nylas Calendar API to automatically sync with calendars and events. When you sync Notetaker with a grant's calendar or event, Nylas tracks their join times and meeting links so the Notetaker is always sent to the meeting on time.
## Webhook notifications
Nylas sends [webhook notifications](/docs/reference/notifications/#notetaker-notifications) when a Notetaker bot is created, updated, or deleted, and when the recording media is available.
- name: Standalone Notetaker
description: |
Nylas Notetaker is a real-time meeting bot that you can invite to your online meetings. It records and transcribes your discussion, and delivers results to you using the Nylas API and webhook notifications.
The `/v3/notetakers` endpoints let you interact with Nylas Notetaker without referencing a grant. This lets all your users — even those who haven't authenticated with your Nylas application — use Notetaker in their meetings.
- name: Application-level templates
description: |
Application-level templates let you create reusable messages with dynamic content. Each template is linked to the Nylas application associated with the API key specified in a [Create Template request](/docs/reference/api/application-level-templates/create-app-level-template/).
Nylas supports the following templating engines:
- [Handlebars](https://handlebarsjs.com/)
- [mustache }}](https://mustache.github.io/)
- [Nunjucks](https://mozilla.github.io/nunjucks/)
- [Twig](https://twig.symfony.com/)
We recommend you use [mustache }}](https://mustache.github.io/) or [Handlebars](https://handlebarsjs.com/) if you need a simple implementation. If you need more advanced formatting, conditions, or layouts, we recommend [Nunjucks](https://mozilla.github.io/nunjucks/) or [Twig](https://twig.symfony.com/).
- name: Grant-level templates
description: |
Grant-level templates let you create reusable messages with dynamic content. Each template is linked to the grant specified in a [Create Template request](/docs/reference/api/grant-level-templates/create-grant-level-template/).
Nylas supports the following templating engines:
- [Handlebars](https://handlebarsjs.com/)
- [mustache }}](https://mustache.github.io/)
- [Nunjucks](https://mozilla.github.io/nunjucks/)
- [Twig](https://twig.symfony.com/)
We recommend you use [mustache }}](https://mustache.github.io/) or [Handlebars](https://handlebarsjs.com/) if you need a simple implementation. If you need more advanced formatting, conditions, or layouts, we recommend [Nunjucks](https://mozilla.github.io/nunjucks/) or [Twig](https://twig.symfony.com/).
- name: Application-level workflows
description: |
Application-level workflows automatically send messages to certain users when a defined event is triggered. For example, if you want to send a confirmation message when a user schedules a booking, you can create a workflow that listens for [`booking.created` events](/docs/reference/notifications/#booking-created-notifications).
Each workflow is linked to the Nylas application associated with the API key specified in a [Create Workflow request](/docs/reference/api/application-level-workflows/create-workflow/).
- name: Grant-level workflows
description: |
Grant-level workflows automatically send messages to certain users when a defined event is triggered. For example, if you want to send a confirmation message when a user schedules a booking, you can create a workflow that listens for [`booking.created` events](/docs/reference/notifications/#booking-created-notifications).
Each workflow is linked to the grant specified in the [Create Workflow request](/docs/reference/api/grant-level-workflows/create-grant-workflow/).
- name: Configurations
description: |
A configuration is a collection of event settings and preferences. Nylas Scheduler stores Configuration objects in the Scheduler database and loads them as Scheduling Pages in the Scheduler UI.
A configuration can be either private if it uses a session, or public if it does not. By default, Nylas creates public configurations (`requires_session_auth: false`). To create a private configuration, set `requires_session_auth` to `true`.
After you create a private configuration, you can make a [`POST /v3/scheduling/sessions` request](/docs/reference/api/sessions/post-sessions/) that includes the Configuration object ID to create a session.
## Agent Accounts as the organizer
The `grant_id` in the path can be an [Agent Account](/docs/v3/agent-accounts/) grant, which makes the Agent Account the organizer of the Configuration. Guests then book against the agent's own calendar and receive confirmation email from the agent's own address, with no OAuth connection involved.
Two limits apply when an Agent Account is a participant:
- Set `availability.calendar_ids` to `["primary"]` and `booking.calendar_id` to `"primary"`. Scheduler reads and writes the Agent Account's primary calendar only.
- Round-robin Configurations aren't supported. An Agent Account can't be a host under `max-fairness` or `max-availability`, though one-on-one, collective, and group Configurations all work.
The scopes table below covers Google and Microsoft grants. Agent Accounts have no OAuth token, so they authenticate with your API key alone. For the full walkthrough, see [Use Scheduler with Agent Accounts](/docs/v3/scheduler/agent-accounts/).
## Configurations scopes
The table below lists the Configurations endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **POST** `/scheduling/configurations`**PUT** `/scheduling/configuration/` | `/calendar.readonly` ☑️`/calendar` | `Calendars.Read` ☑️`Calendars.ReadWrite` |
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
- name: Group Events
description: |
Group meetings let you host events with multiple participants. Unlike one-on-one meetings, group events are designed for collaborative scheduling where multiple attendees are invited to the same event.
- name: Sessions
description: |
Nylas Scheduler uses session IDs to authorize requests to the [`/v3/scheduling/availability`](/docs/reference/api/availability/) and [`/v3/scheduling/bookings`](/docs/reference/api/bookings/) endpoints.
When you create a session, you must include the ID of an existing [Configuration object](/docs/reference/api/configurations/). Sessions are only required for private configurations (`requires_session_auth: true`).
## Time to live
For security purposes, Nylas recommends you set the `time_to_live` value for each session and refresh the sessions as they expire.
- name: Availability
description: |
Nylas Scheduler uses the `/v3/scheduling/availability` endpoint to retrieve availability information. When you make a request, Nylas validates the provided session ID and uses it to retrieve the related Configuration object.
When a Configuration participant is an [Agent Account](/docs/v3/scheduler/agent-accounts/), Scheduler reads busy time from that account's primary calendar only. Set the participant's `availability.calendar_ids` to `["primary"]`; additional calendars on the Agent Account don't affect the returned slots.
## Availability scopes
The table below lists the Availability endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :--------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **GET** `/scheduling/availability` | `/calendar.readonly` ☑️`/calendar` | `Calendars.Read` ☑️`Calendars.ReadWrite` |
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
- name: Bookings
description: |
Nylas Scheduler uses the `/v3/scheduling/bookings` endpoint to manage bookings.
Bookings work the same way when the organizer is an [Agent Account](/docs/v3/scheduler/agent-accounts/): the event is created on the Agent Account's primary calendar, and the confirmation, reschedule, cancellation, and reminder email all send from the Agent Account's own address. Each of those messages counts against the account's [daily send quota](/docs/v3/agent-accounts/send-limits/#sending-limits).
## Booking types
Nylas Scheduler supports two booking types, `booking` and `organizer-confirmation`.
`booking` represents a regular booking flow. When the booking type is `organizer-confirmation`, Nylas creates an event marked "Pending" in the organizer's calendar. It then sends an confirmation request email to the organizer, which includes a link to a page where the organizer can confirm or cancel the booking.
### Finalizing pending bookings
The [`PUT /v3/scheduling/bookings/{booking_id}` request](/docs/reference/api/bookings/put-bookings-id/) allows the organizer to confirm or cancel a pending booking.
## Booking flow
The Scheduling Component provides information about the selected time slot, and any additional information that the user added, to the [`/v3/scheduling/bookings` endpoint](/docs/reference/api/bookings/post-bookings/). The Bookings endpoint performs the following tasks:
1. Validates the provided session ID and uses it to retrieve the related Configuration object.
2. Confirms if the selected time slot is still available.
3. Retrieves the booking participant's `grant_id`, using the list of participants' email addresses in the Configuration object.
4. Creates an event.
If the booking type is set to `organizer-confirmation`, a placeholder event is created in the organizer's calendar.
5. Creates a booking entry in the database and maps the provider's event ID and Scheduler's `booking_id`.
If the booking type is set to `organizer-confirmation`, a booking entry with the `pending` status is created. The booking entry includes the placeholder event's `booking_id` and the `additional_fields` data provided in the request.
6. Nylas creates a booking reference based on the configuration ID and the booking ID. You can use the booking reference to reschedule and cancel the event.
7. (Optional) Emits a booking (`booking.created`) or a pending booking (`booking.pending`) webhook, depending on the booking type.
## Bookings scopes
The table below lists the Bookings endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.
| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |
| :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **POST** `/scheduling/bookings`**DELETE** `/scheduling/bookings/`**PATCH** `/scheduling/bookings/` | `/calendar.events` ☑️`/calendar` | `Calendars.ReadWrite` ☑️ |
For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).
- name: App migration
description: |
Before you begin, you should already have:
- Linked your v2 and v3 Nylas organizations. If you're not sure if your organizations are linked and you have a contract with us, [contact Nylas Support](/docs/support/#contact-nylas-support).
- Created v3 applications to serve as the destinations for your v2 settings and connected account information.
- [Set up equivalent provider auth apps as needed](/docs/v2/upgrade-to-v3/upgrade/auth/), especially if your users are authenticating with Microsoft.
- [Set up v3 notification infrastructure](/docs/v2/upgrade-to-v3/upgrade/webhooks/). You'll use this to keep track of object that update while you're migrating your applications.
You make Migration API requests using the v3 API route, using an API key from the destination v3 application.
For each application to be migrated:
1. [Link apps](#post-/v3/migration-tools/link-v2v3-apps)
2. [Import app settings](#post-/v3/migration-tools/import-v2-app)
3. [Migrate a test user](#post-/v3/migration-tools/grants/-account_id-/clone) and/or [Start a batch migration](#post-/v3/migration-tools/snapshot-batch-clone)
Make sure you use the correct region! In Nylas v3, you mange applications for both the U.S. and E.U. regions using the same Dashboard. If you're migrating a v2 application to a v3 one, make sure you create the v3 application in the correct region.
- name: Data migration
description: |
In Nylas v2, you used the unique Nylas ID to locate data and objects in Nylas's synced data. In Nylas v3, you use the provider ID directly. These APIs look up the provider IDs for your v2 data.
Because every project is different, we leave it up to you to decide how your project updates the v2 IDs to v3 provider IDs.
These APIs are for one-time translation for migration purposes only. You can retry these APIs if you encounter issues, but they will be rate limited and you should not use them as part of your project's code or object handling logic.
Some data objects that exist in Nylas v2 may not have provider IDs available, meaning they do not exist on the provider. When this happens, Nylas returns the `v3_resource_id` as `None`.
- name: v2 Redirects
description: |
Nylas Scheduler uses the `/v3/scheduling/should-redirect/` endpoint to redirect existing v2 Scheduling Pages to v3.
paths:
/v3/applications:
get:
operationId: get_application
tags:
- Applications
summary: Get application
description: Gets the application object
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/applications' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "",
apiUri: "",
});
const applicationDetails = await nylas.applications.getDetails();
console.log({ applicationDetails });
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"",
"",
)
application = nylas.applications.info()
application_id = application[1]
print("Application ID:", application_id)
- lang: ruby
label: Ruby SDK
source: |
# frozen_string_literal: true
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: ''
)
application = nylas.applications.get_details()
puts application
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class getApplication {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("").build();
Response application = nylas.applications().getDetails();
System.out.println(application);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
fun main(args: Array) {
val nylas: NylasClient = NylasClient(
apiKey = ""
)
val application = nylas.applications().getDetails()
print(application)
}
security:
- NYLAS_API_KEY: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/ApplicationObject'
description: Returns Application object
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
patch:
operationId: update_application
tags:
- Applications
summary: Update an application
description: |-
Updates a Nylas application using the client ID associated with the specified API key.
⚠️ This endpoint will be removed in the future when application settings are available in the Nylas Dashboard.
When you make a `PATCH` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request PATCH \
--url 'https://api.us.nylas.com/v3/applications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ' \
--data '{
"branding": {
"name": "",
"icon_url": "",
"website_url": "",
"description": ""
},
"hosted_authentication": {
"background_image_url": "",
"alignment": "",
"color_primary": "",
"color_secondary": "",
"title": "",
"subtitle": "<SUBTITLE>",
"background_color": "<BACKGROUND_COLOR>",
"spacing": 10
},
"callback_uris": [
{
"id": "<CALLBACK_URI_ID>",
"url": "<CALLBACK_URL>",
"platform": "<PLATFORM>",
"settings": {
"origin": "<ORIGIN>",
"bundle_id": "<BUNDLE_ID>",
"package_name": "<PACKAGE_NAME>",
"sha1_certificate_fingerprint": "<SHA1_FINGERPRINT>"
}
}
]
}'
security:
- NYLAS_API_KEY: []
requestBody:
required: true
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationObject'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/ApplicationObject'
description: Returns application object
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/applications/redirect-uris:
get:
operationId: get_all_callback_uris
tags:
- Applications
summary: Get an application's callback URIs
description: Returns a list of callback URIs for the specified Nylas application.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/applications/redirect-uris' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const redirectUris = await nylas.applications.redirectUris.list();
console.log("Redirect URIs:", redirectUris);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
application_redirect_uris = nylas.applications.redirect_uris.list()
print("Application Redirects:", application_redirect_uris.data)
- lang: ruby
label: Ruby SDK
source: |
# frozen_string_literal: true
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: '<NYLAS_API_KEY>'
)
redirect_uris, _ = nylas.applications.redirect_uris.list
redirect_uris.each do |uri|
puts uri[:url]
end
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.ListResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.RedirectUri;
public class GetApplicationCallbackUris {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<RedirectUri> redirectUris = nylas.applications().redirectUris().list();
System.out.println("Redirect URIs: " + redirectUris.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient(apiKey = "<NYLAS_API_KEY>")
val redirectUris = nylas.applications().redirectUris().list()
println("Redirect URIs: ${redirectUris.data}")
}
security:
- NYLAS_API_KEY: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
$ref: '#/components/schemas/RedirectURIObject'
description: Returns a list of callback URIs
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
$ref: '#/components/schemas/400'
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
error:
$ref: '#/components/schemas/404'
post:
operationId: add_callback_uri
tags:
- Applications
summary: Add callback URI to application
description: |-
Adds a callback URI to the specified Nylas application. Nylas uses callback URIs to redirect users
to your project after they complete the authentication flow. If you don't specify a `platform`,
Nylas defaults to `web`.
The OAuth protocol requires that you include the `client_secret` field for calls made to this
endpoint, depending on the `platform` you define. If you're using
[OAuth 2.0 with PKCE](/docs/v3/auth/hosted-oauth-accesstoken/#create-grants-with-oauth-2.0-and-pkce)
and your platform is `js`, `ios`, `android`, or `desktop`, the `client_secret` field is not
required.
security:
- NYLAS_API_KEY: []
requestBody:
required: true
description: ''
content:
application/json:
schema:
type: object
required:
- url
oneOf:
- $ref: '#/components/schemas/webDesktopCallbackNoSettings'
- $ref: '#/components/schemas/JsCallbackwSettings'
- $ref: '#/components/schemas/iosCallbackwSettings'
- $ref: '#/components/schemas/AndroidCallbackwSettings'
discriminator:
propertyName: platform
mapping:
web: '#/components/schemas/webDesktopCallbackNoSettings'
desktop: '#/components/schemas/webDesktopCallbackNoSettings'
js: '#/components/schemas/JsCallbackwSettings'
ios: '#/components/schemas/iosCallbackwSettings'
android: '#/components/schemas/AndroidCallbackwSettings'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/RedirectURIObject'
description: Returns callback URI
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/applications/redirect-uris' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"platform": "web",
"url": "<CALLBACK_URI>",
"id": "<CALLBACK_URI_ID>"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const redirectUri = await nylas.applications.redirectUris.create({
requestBody: {
url: "<CALLBACK_URI>",
platform: "web",
},
});
console.log("Redirect URI created:", redirectUri);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
redirect_uri = nylas.applications.redirect_uris.create(
request_body={
"url": "https://example.com/oauth/exchange",
"platform": "web",
},
)
print("Created redirect URI:", redirect_uri)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.CreateRedirectUriRequest;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Platform;
import com.nylas.models.RedirectUri;
import com.nylas.models.Response;
public class CreateRedirectUri {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CreateRedirectUriRequest requestBody = new CreateRedirectUriRequest.Builder(
"<CALLBACK_URI>", Platform.WEB)
.build();
Response<RedirectUri> redirectUri = nylas.applications().redirectUris().create(requestBody);
System.out.println("Redirect URI created: " + redirectUri.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.CreateRedirectUriRequest
import com.nylas.models.Platform
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val requestBody = CreateRedirectUriRequest.Builder("<CALLBACK_URI>", Platform.WEB)
.build()
val redirectUri = nylas.applications().redirectUris().create(requestBody)
println("Redirect URI created: ${redirectUri.data}")
}
/v3/applications/redirect-uris/{id}:
parameters:
- example: 0556d035-6cb6-4262-a035-6b77e11cf8fc
name: id
schema:
type: string
in: path
required: true
get:
operationId: get_application_callback_uri
tags:
- Applications
summary: Return a callback URI
description: Returns the specified callback URI.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/applications/redirect-uris/<CALLBACK_URI_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function getRedirectUri() {
try {
const redirectUris = await nylas.applications.redirectUris.find({
redirectUriId: "<CALLBACK_URI_ID>",
});
console.log("Callback URI:", redirectUris);
} catch (error) {
console.error("Couldn't get callback URI:", error);
}
}
getRedirectUri();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
redirect_uri = nylas.applications.redirect_uris.find(
redirect_uri_id="<CALLBACK_URI_ID>",
)
print(redirect_uri)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\t\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nredirect_uris = nylas.applications.redirect_uris.find(redirect_uri_id: \"<CALLBACK_URI_ID>\")\n\nputs redirect_uris"
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class GetApplicationURIs {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<RedirectUri> redirect_uris = nylas.applications().redirectUris().find("<CALLBACK_URI_ID>");
System.out.println(redirect_uris);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val redirecturis = nylas.applications().redirectUris().find("<CALLBACK_URI_ID>")
print(redirecturis)
}
security:
- NYLAS_API_KEY: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/RedirectURIObject'
description: Returns callback URI
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
patch:
operationId: update_callback_uri
tags:
- Applications
summary: Update a callback URI
description: |-
Updates the specified callback URI.
If you don't define the `platform`, Nylas doesn't modify the existing settings.
When you make a `PATCH` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PATCH \
--url 'https://api.us.nylas.com/v3/applications/redirect-uris/<CALLBACK_URI_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
--data '{
"url": "<UPDATED_CALLBACK_URI>"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const updated = await nylas.applications.redirectUris.update({
redirectUriId: "<CALLBACK_URI_ID>",
requestBody: {
url: "<UPDATED_CALLBACK_URI>",
},
});
console.log("Redirect URI updated:", updated);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
redirect_uri = nylas.applications.redirect_uris.update(
redirect_uri_id="<REDIRECT_URI_ID>",
request_body={
"url": "https://example.com/oauth/exchange",
"platform": "web",
},
)
print("Updated redirect URI:", redirect_uri)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.RedirectUri;
import com.nylas.models.Response;
import com.nylas.models.UpdateRedirectUriRequest;
public class UpdateRedirectUri {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateRedirectUriRequest requestBody = new UpdateRedirectUriRequest.Builder()
.url("<UPDATED_CALLBACK_URI>")
.build();
Response<RedirectUri> updated = nylas.applications().redirectUris()
.update("<CALLBACK_URI_ID>", requestBody);
System.out.println("Redirect URI updated: " + updated.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.UpdateRedirectUriRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val requestBody = UpdateRedirectUriRequest.Builder()
.url("<UPDATED_CALLBACK_URI>")
.build()
val updated = nylas.applications().redirectUris().update("<CALLBACK_URI_ID>", requestBody)
println("Redirect URI updated: ${updated.data}")
}
security:
- NYLAS_API_KEY: []
requestBody:
required: true
description: ''
content:
application/json:
schema:
type: object
required:
- platform
- url
oneOf:
- $ref: '#/components/schemas/webDesktopCallbackNoSettings'
- $ref: '#/components/schemas/JsCallbackwSettings'
- $ref: '#/components/schemas/iosCallbackwSettings'
- $ref: '#/components/schemas/AndroidCallbackwSettings'
discriminator:
propertyName: platform
mapping:
web: '#/components/schemas/webDesktopCallbackNoSettings'
desktop: '#/components/schemas/webDesktopCallbackNoSettings'
js: '#/components/schemas/JsCallbackwSettings'
ios: '#/components/schemas/iosCallbackwSettings'
android: '#/components/schemas/AndroidCallbackwSettings'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/RedirectURIObject'
description: Returns callback URI
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
delete:
operationId: delete_callback_uri
tags:
- Applications
summary: Delete a callback URI
description: Deletes the specified callback URI.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/applications/redirect-uris/<CALLBACK_URI_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deleteRedirectUriId() {
try {
const response = await nylas.applications.redirectUris.destroy({
redirectUriId: "<CALLBACK_URI_ID>",
});
console.log("Callback URI deleted:", response);
} catch (error) {
console.error("Couldn't delete callback URI:", error);
}
}
deleteRedirectUriId();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.applications.redirect_uris.destroy(
redirect_uri_id="<CALLBACK_URI_ID>",
)
print(response)
- lang: ruby
label: Ruby SDK
source: |-
# frozen_string_literal: true
require 'nylas'
nylas = Nylas::Client.new(
api_key: '<NYLAS_API_KEY>'
)
redirect_uris = nylas.applications.redirect_uris.destroy(redirect_uri_id: "<CALLBACK_URI_ID>")
puts redirect_uris
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class DeleteApplicationURIs {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse redirect_uris =
nylas.applications().redirectUris().destroy("<REDIRECT_URI>");
System.out.println(redirect_uris);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val redirecturis = nylas.applications().redirectUris().destroy("<REDIRECT_URIS>")
print(redirecturis)
}
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/200-delete'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/connectors:
post:
operationId: create_connector
tags:
- Connectors (Integrations)
summary: Create a connector
description: |-
Create a connector in your Nylas application.
Connectors are how your Nylas application stores information it needs to connect to external
services. Creating a connector is the first step in setting up authentication for your project.
See [Supported providers](/docs/provider-guides/#supported-providers) for more information.
security:
- NYLAS_API_KEY: []
requestBody:
required: true
description: ''
content:
application/json:
schema:
oneOf:
- type: object
title: Google
description: Google connector. Requires GCP OAuth app credentials.
required:
- provider
properties:
provider:
type: string
description: The provider type. For Google providers, set to `google`.
example: google
settings:
type: object
description: GCP provider auth app credentials and settings.
required:
- client_id
- client_secret
properties:
client_id:
type: string
description: The GCP app's client ID.
example: abc-def
client_secret:
type: string
description: The GCP app's client secret.
example: xyz-abc-def
topic_name:
type: string
description: Google Pub/Sub topic name. Required if using Email webhooks.
example: topic-123
scope:
type: array
items:
type: string
description: Set the default scopes for each connector. These scopes are overridden by scopes set on the specific grant.
example:
- https://www.googleapis.com/auth/userinfo.email
- https://www.googleapis.com/auth/userinfo.profile
- https://www.googleapis.com/auth/gmail.readonly
- type: object
title: Microsoft
description: Microsoft connector. Requires Azure OAuth app credentials.
required:
- provider
properties:
provider:
type: string
description: The provider type. For Microsoft providers, set to `microsoft`.
example: microsoft
settings:
type: object
description: Your Azure provider auth app credentials and settings, as stored in Entra ID.
required:
- client_id
- client_secret
properties:
client_id:
type: string
description: The Azure auth app's client ID.
example: abc-def
client_secret:
type: string
description: The Azure auth app's client secret.
example: xyz-abc-def
tenant:
type: string
description: Microsoft tenant ID.
example: abc-123-def-456
scope:
type: array
items:
type: string
description: |-
Set the default scopes for each connector. Scopes set on individual grants override these scopes.
For Microsoft Graph connectors, the Nylas API accepts both the full URI version of a scope name (for example, `https://graph.microsoft.com/Calendars.Read`), as well as the short form (for example, `Calendars.Read`).
example:
- User.Read
- Mail.Read
- type: object
title: Zoom
description: Zoom connector for managing meetings on behalf of users.
required:
- provider
properties:
provider:
type: string
description: The provider type. For Zoom providers, set to `zoom`.
example: zoom
settings:
type: object
description: |-
Zoom provider credentials and settings. You can copy them from your [Zoom App](https://developers.zoom.us/docs/zoom-apps/) in [Zoom Developer Platform](https://developers.zoom.us/docs/). The Zoom Nylas connector does not support default scopes, so do not include them in the connector request.
However, you must configure the required [granular scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-granular/) directly on your Zoom OAuth app. To use Zoom conferencing with Nylas events, your Zoom app needs: `meeting:write:meeting` (create), `meeting:update:meeting` (update), and `meeting:delete:meeting` (delete).
required:
- client_id
- client_secret
properties:
client_id:
type: string
description: The Zoom app's client ID.
example: abc-def
client_secret:
type: string
description: The Zoom app's client secret.
example: xyz-abc-def
- type: object
title: iCloud
description: iCloud connector. No app credentials required.
required:
- provider
properties:
provider:
type: string
description: |-
The provider type, in this case `icloud`. See
[Authenticating iCloud accounts](/docs/provider-guides/icloud/) for more
information.
example: icloud
- type: object
title: IMAP
description: IMAP connector for generic IMAP/SMTP mail servers.
required:
- provider
properties:
provider:
type: string
description: |-
The provider type, in this case `imap`. See
[Using IMAP accounts and data](/docs/provider-guides/imap/) for more information.
example: imap
- type: object
title: EWS
description: EWS connector for Exchange on-premises servers.
required:
- provider
- settings
properties:
provider:
type: string
description: |-
The provider type (in this case, `ews`). See
[Authenticating Exchange on-premises accounts](/docs/provider-guides/exchange-on-prem/)
for more information.
example: ews
scopes:
type: string
description: Scopes settings tell Nylas to request specific data objects from the provider.
enum:
- ews.messages
- ews.calendar
- ews.contacts
examples:
- ews.messages
- ews.calendar
- ews.contacts
- type: object
title: Virtual calendars
description: Nylas-managed virtual calendar. No external provider.
required:
- provider
properties:
provider:
type: string
description: The provider type. For virtual calendars, set to `virtual-calendar`.
example: virtual-calendar
- type: object
title: Yahoo
description: Yahoo connector. Requires Yahoo OAuth app credentials.
required:
- provider
properties:
provider:
type: string
description: |-
The provider type (in this case, `yahoo`). See
[Authenticating Yahoo accounts](/docs/provider-guides/yahoo/) for more information.
example: yahoo
settings:
type: object
description: Yahoo provider credentials.
required:
- client_id
- client_secret
properties:
client_id:
type: string
description: The Yahoo app's client ID.
example: abc-def
client_secret:
type: string
description: The Yahoo app's client secret.
example: xyz-abc-def
scope:
type: array
items:
type: string
description: Set the default scopes for each connector. These scopes are overridden by scopes set on the specific grant.
example:
- email
- profile
- mail-w
- type: object
title: Nylas (Agent Account)
description: Connector for Nylas-hosted [Agent Account](/docs/v3/agent-accounts/) email and calendar mailboxes. Agent Account connectors don't support the `scope` field.
required:
- provider
properties:
provider:
type: string
description: The provider type (in this case, `nylas`).
example: nylas
responses:
'201':
description: Connector Created
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/ConnectorObject'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/connectors' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"provider": "google",
"settings": {
"client_id": "<NYLAS_CLIENT_ID>",
"client_secret": "<NYLAS_CLIENT_SECRET>",
"topic_name": "<TOPIC_NAME>"
},
"scope": [
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/userinfo.profile"
]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createConnector() {
try {
const connector = await nylas.connectors.create({
requestBody: {
name: "google",
provider: "google",
settings: {
clientId: "<GCP_CLIENT_ID>",
clientSecret: "<GCP_CLIENT_SECRET>",
},
scope: [
"openid",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/gmail.modify",
"https://www.googleapis.com/auth/calendar",
"https://www.googleapis.com/auth/contacts",
],
},
});
console.log("Connector created:", connector);
} catch (error) {
console.error("Error creating connector:", error);
}
}
createConnector();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
connector = nylas.connectors.create(
request_body={
"provider": "google",
"settings": {
"client_id": "<GCP_CLIENT_ID>",
"client_secret": "<GCP_CLIENT_SECRET>",
},
"scopes": [
"openid",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/gmail.modify",
"https://www.googleapis.com/auth/calendar",
"https://www.googleapis.com/auth/contacts",
],
}
)
- lang: ruby
label: Ruby SDK
source: |-
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
provider: "google",
settings: {
clientId: "<GCP_CLIENT_ID>",
clientSecret: "<GCP_CLIENT_SECRET>",
},
scope: [
'openid',
'https://www.googleapis.com/auth/userinfo.email',
'https://www.googleapis.com/auth/gmail.modify',
'https://www.googleapis.com/auth/calendar',
'https://www.googleapis.com/auth/contacts',
]
}
nylas.connectors.create(request_body: request_body)
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class connector {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<String> scope = new ArrayList<>();
scope.add("openid");
scope.add("https://www.googleapis.com/auth/userinfo.email");
scope.add("https://www.googleapis.com/auth/gmail.modify");
scope.add("https://www.googleapis.com/auth/calendar");
scope.add("https://www.googleapis.com/auth/contacts");
GoogleCreateConnectorSettings settings = new GoogleCreateConnectorSettings(
"<GCP_CLIENT_ID>",
"<GCP_CLIENT_SECRET>",
""
);
CreateConnectorRequest request = new CreateConnectorRequest.Google(settings, scope);
nylas.connectors().create(request);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.CreateConnectorRequest
import com.nylas.models.GoogleCreateConnectorSettings
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
var scope = listOf(
"openid",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/gmail.modify",
"https://www.googleapis.com/auth/calendar",
"https://www.googleapis.com/auth/contacts"
)
val settings : GoogleCreateConnectorSettings = GoogleCreateConnectorSettings(
"<GCP_CLIENT_ID>",
"<GCP_CLIENT_SECRET>",
""
)
val request : CreateConnectorRequest = CreateConnectorRequest.Google(settings, scope)
nylas.connectors().create(request)
}
get:
operationId: get_connector_all
tags:
- Connectors (Integrations)
summary: List connectors
description: List the connectors in your Nylas application.
security:
- NYLAS_API_KEY: []
parameters:
- name: limit
in: query
schema:
type: integer
required: false
description: Limit the number of results in a connector list.
- name: offset
in: query
schema:
type: integer
required: false
description: Offset the list of results in a connector list.
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: array
items:
$ref: '#/components/schemas/ConnectorObject'
limit:
type: integer
example: 10
offset:
type: integer
example: 0
description: Returns an array of Connector objects.
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/connectors' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const listConnectors = async () => {
try {
const connectors = await nylas.connectors.list({});
console.log("Connectors:", connectors);
} catch (error) {
console.error("Error fetching connectors:", error);
}
};
listConnectors();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
connectors = nylas.connectors.list
print("Connectors:", connectors)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>",
)
connectors = nylas.connectors.list()
puts connectors
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ListDraft {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas =
new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Connector> connectors =
nylas.connectors().list();
System.out.println(connectors);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val connectors = nylas.connectors().list()
println(connectors)
}
/v3/connectors/{provider}:
get:
operationId: get_connector_by_provider
tags:
- Connectors (Integrations)
summary: Get connector
description: Returns a connector for the specified provider.
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/provider'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/ConnectorObject'
description: Returns a connector object
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/connectors/<PROVIDER>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const getConnector = async () => {
try {
const connector = await nylas.connectors.find({
provider: "google",
});
console.log("Connector", connector);
} catch (error) {
console.error("Error fetching connector:", error);
}
};
getConnector();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
connector = nylas.connectors.find(
provider="google"
)
print("Connector:", connector)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>",
)
connectors = nylas.connectors.find(provider: "google")
puts connectors
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ListDraft {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas =
new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Connector> connector =
nylas.connectors().find(AuthProvider.GOOGLE);
System.out.println(connector);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AuthProvider
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val connector =
nylas.connectors().find(AuthProvider.GOOGLE)
println(connector)
}
patch:
operationId: update_connector_by_provider
tags:
- Connectors (Integrations)
summary: Update a connector
description: |-
Update the connector for the specified provider.
When you make a `PATCH` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/provider'
requestBody:
required: true
description: ''
content:
application/json:
schema:
type: object
properties:
settings:
type: object
description: Oauth provider credentials and settings
example:
tenant: common
scope:
type: array
description: Oauth "scope" parameter
example:
- Mail.Read
- User.Read
- offline_access
items:
type: string
active_credential_id:
type: string
description: (Optional) The ID of the "default" credential record of this Connector. This credential will be used as a default for communication with the provider.
example: c123f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/ConnectorObject'
description: Returns the connector object (previously called an integration) for the provider you specify.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PATCH \
--url 'https://api.us.nylas.com/v3/connectors/<PROVIDER>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"name": "google"
}'
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
connector = nylas.connectors.update(
provider="google",
request_body={
"name": "google"
}
)
print("Connector:", connector)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
scope: [
'https://www.googleapis.com/auth/contacts'
]
}
connector = nylas.connectors.update(provider: "google", request_body: request_body)
puts connector
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class ListDraft {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas =
new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<String> scope = new ArrayList<>();
scope.add("https://www.googleapis.com/auth/contacts");
GoogleConnectorSettings settings = new GoogleConnectorSettings();
UpdateConnectorRequest.Google request = new UpdateConnectorRequest.Google.Builder()
.settings(settings)
.scope(scope)
.build();
nylas.connectors().update(AuthProvider.GOOGLE, request);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AuthProvider
import com.nylas.models.GoogleConnectorSettings
import com.nylas.models.UpdateConnectorRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val settings : GoogleConnectorSettings =
GoogleConnectorSettings()
val request =
UpdateConnectorRequest.Google(settings)
val connector =
nylas.connectors().update(AuthProvider.GOOGLE,
request)
println(connector)
}
delete:
operationId: delete_connector_by_provider
tags:
- Connectors (Integrations)
summary: Delete a connector
description: |-
Deletes the connector for the provider you specify. All grants on the connector stop working right away, and its credentials are deleted too.
To learn what gets removed and when, see [Deleting resources and data](/docs/dev-guide/platform/deleting-resources/).
parameters:
- $ref: '#/components/parameters/provider'
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/200-delete'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/connectors/<PROVIDER>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const provider = "google";
try {
await nylas.connectors.destroy({ provider });
console.log(`Connector with ID ${provider} removed successfully.`);
} catch (error) {
console.error("Error removing connector:", error);
}
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
provider = "google"
request = nylas.connectors.destroy(
provider,
)
print(request)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>",
)
connector = nylas.connectors.destroy(provider: "google")
puts connector
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ListDraft {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse connector =
nylas.connectors().destroy(AuthProvider.GOOGLE);
System.out.println(connector);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AuthProvider
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val connector =
nylas.connectors().destroy(AuthProvider.GOOGLE)
println(connector)
}
/v3/providers/detect:
post:
operationId: detect_provider_by_email
tags:
- Connectors (Integrations)
summary: Detect provider
description: Returns the provider if one is detected. This operation is rate limited to 20 calls per minute for each Nylas application ID.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/providers/detect?email=<EMAIL>&all_provider_types=false' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const detectProvider = async () => {
try {
const response = await nylas.auth.detectProvider({
email: "<EMAIL>",
});
console.log("Detected provider:", response);
} catch (error) {
console.error("Error detecting provider:", error);
}
};
detectProvider();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.auth.detect_provider({
"email": "<EMAIL>",
})
print("Detected provider:", response)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
provider, _ = nylas.auth.detect_provider({ email: "<EMAIL>" })
puts provider
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class detect_provider {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ProviderDetectParams params = new ProviderDetectParams.Builder("<EMAIL>").build();
Response<ProviderDetectResponse> provider = nylas.auth().detectProvider(params);
System.out.println(provider);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.ProviderDetectParams
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val params = ProviderDetectParams("<EMAIL>")
val provider = nylas.auth().detectProvider(params)
print(provider)
}
security:
- NYLAS_API_KEY: []
parameters:
- in: query
name: email
description: Email for detection
required: true
schema:
type: string
- in: query
name: all_provider_types
description: Search by all providers regardless of if they have an existing connector
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/AutodetectObject'
description: Returns the autodetected provider
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
/v3/connect/auth:
get:
operationId: get_oauth2_flow
tags:
- Authentication APIs
summary: Hosted OAuth - Authorization Request
description: |-
The initial OAuth 2.0 authorization request. Use this endpoint with the required query parameters to start the OAuth 2.0 process. The query parameters pass details to the Nylas API about how the user should authenticate, and where they should go after authenticating.
This endpoint supports the authorization code flow and optional PKCE settings for client-side only applications. For more information, see the [Hosted OAuth with access token](/docs/v3/auth/hosted-oauth-accesstoken/) and [Hosted OAuth with access token and PKCE](/docs/v3/auth/hosted-oauth-accesstoken/#create-grants-with-oauth-2.0-and-pkce) documentation.
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request GET \
--url 'https://api.us.nylas.com/v3/connect/auth?client_id=<NYLAS_CLIENT_ID>&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&provider=google&login_hint=user@example.com'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
// Build a hosted-authentication URL. Redirect the user to this URL to start
// the OAuth flow; Nylas calls back to your `redirectUri` with an authorization
// code that you exchange for a grant via `nylas.auth.exchangeCodeForToken()`.
const authUrl = nylas.auth.urlForOAuth2({
clientId: "<NYLAS_CLIENT_ID>",
provider: "google",
redirectUri: "http://localhost:3000/oauth/exchange",
loginHint: "email_to_connect@example.com",
accessType: "offline",
});
console.log(authUrl);
- lang: python
label: Python SDK
source: |
@app.route("/nylas/auth", methods=["GET"])
def login():
if session.get("grant_id") is None:
config = URLForAuthenticationConfig({"client_id": "<NYLAS_CLIENT_ID>",
"redirect_uri" : "http://localhost:5000/oauth/exchange"})
url = nylas.auth.url_for_oauth2(config)
return redirect(url)
else:
return f'{session["grant_id"]}'
@app.route("/oauth/exchange", methods=["GET"])
def authorized():
if session.get("grant_id") is None:
code = request.args.get("code")
exchangeRequest = CodeExchangeRequest({"redirect_uri": "http://localhost:5000/oauth/exchange",
"code": code, "client_id": "<NYLAS_CLIENT_ID>"})
exchange = nylas.auth.exchange_code_for_token(exchangeRequest)
session["grant_id"] = exchange.grant_id
return redirect(url_for("login"))
- lang: ruby
label: Ruby SDK
source: |
# frozen_string_literal: true
require 'nylas'
require 'sinatra'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
set :show_exceptions, :after_handler
error 404 do
'No authorization code returned from Nylas'
end
error 500 do
'Failed to exchange authorization code for token'
end
# Build the hosted-authentication URL and redirect the user there.
get '/nylas/auth' do
config = {
client_id: "<NYLAS_CLIENT_ID>",
provider: 'google',
redirect_uri: 'http://localhost:4567/oauth/exchange',
login_hint: '<email_to_connect>',
access_type: 'offline'
}
url = nylas.auth.url_for_oauth2(config)
redirect url
end
# Receive the authorization code and exchange it for a grant.
get '/oauth/exchange' do
code = params[:code]
status 404 if code.nil?
begin
response = nylas.auth.exchange_code_for_token({
client_id: "<NYLAS_CLIENT_ID>",
redirect_uri: 'http://localhost:4567/oauth/exchange',
code: code
})
rescue StandardError
status 500
else
"Grant_Id: #{response[:grant_id]} \n Email: #{response[:email]}"
end
end
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.AccessType;
import com.nylas.models.AuthProvider;
import com.nylas.models.UrlForAuthenticationConfig;
public class HostedAuthUrl {
public static void main(String[] args) {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Build a hosted-authentication URL. Redirect the user to this URL to start
// the OAuth flow; Nylas calls back to your `redirectUri` with an authorization
// code that you exchange for a grant via `nylas.auth().exchangeCodeForToken()`.
UrlForAuthenticationConfig config = new UrlForAuthenticationConfig.Builder(
"<NYLAS_CLIENT_ID>",
"http://localhost:3000/oauth/exchange")
.provider(AuthProvider.GOOGLE)
.accessType(AccessType.OFFLINE)
.loginHint("email_to_connect@example.com")
.build();
String url = nylas.auth().urlForOAuth2(config);
System.out.println(url);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AccessType
import com.nylas.models.AuthProvider
import com.nylas.models.UrlForAuthenticationConfig
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
// Build a hosted-authentication URL. Redirect the user to this URL to start
// the OAuth flow; Nylas calls back to your `redirectUri` with an authorization
// code that you exchange for a grant via `nylas.auth().exchangeCodeForToken()`.
val config = UrlForAuthenticationConfig.Builder(
"<NYLAS_CLIENT_ID>",
"http://localhost:3000/oauth/exchange")
.provider(AuthProvider.GOOGLE)
.accessType(AccessType.OFFLINE)
.loginHint("email_to_connect@example.com")
.build()
val url = nylas.auth().urlForOAuth2(config)
println(url)
}
parameters:
- in: query
name: client_id
required: true
description: Your Nylas application's client ID (or application ID).
schema:
type: string
- in: query
name: provider
required: false
description: |-
The connector provider type that you set up with Nylas for this application. If the provider
isn't set, the user is directed to the Nylas Hosted login page and prompted to select their
provider. Multiple providers can be set as a comma-separated list.
schema:
type: string
enum:
- google
- microsoft
- imap
- icloud
- yahoo
- ews
- zoom
- in: query
name: redirect_uri
required: true
description: Your project's callback URI (used as the OAuth `redirect_uri`). This is where the OAuth provider sends a user after they authenticate using Hosted OAuth. This must be URL-encoded.
schema:
type: string
example: redirect_uri=https%3A%2F%2Fapp.example.com&
- in: query
name: response_type
required: true
description: Specifies the type of response Nylas returns for the authorization flow. Should be set to `code` for the OAuth 2.0 flow, and `adminconsent` for the Microsoft admin consent service flow.
schema:
type: string
enum:
- code
- adminconsent
- in: query
name: scope
description: |-
A space-delimited list of scopes that identify the resources that your application may access
on the user's behalf. If no scopes are set, Nylas uses the default connector scopes.
schema:
type: string
- in: query
name: prompt
required: false
description: |-
(Optional) The prompt for the Hosted login page. This parameter can accept multiple values
separated by a comma, without spaces in between. The order of the prompts affects the UI of
the Hosted login page.
If `provider` is not set, the user is redirected to the provider page directly, and the prompt
is ignored.
schema:
type: string
default: select_provider
enum:
- select_provider
- detect
- select_provider,detect
- detect,select_provider
- in: query
name: state
description: (Optional) The state of the grant, returned after authentication. The maximum length is 256 characters.
schema:
type: string
- in: query
name: login_hint
description: Prefill the login name (usually the email address) during the authentication flow. If a grant already exists for the provided email address, Nylas automatically re-authenticates the grant.
schema:
type: string
- in: query
name: access_type
description: Specifies whether Nylas should return a refresh token along with the exchange token. This isn't suitable for client-side or JavaScript applications.
schema:
type: string
enum:
- offline
- online
- in: query
name: code_challenge
description: Specifies a Base64-encoded `code_verifier` without padding. The verifier is used as a server-side challenge during the authorization code exchange.
schema:
example: e96bf6686a3c3510e9e927db7069cb1cba9b99b022f49483a6ce3270809e68a2
type: string
- in: query
name: code_challenge_method
description: Specifies the method used to encode the `code_verifier`. The verifier is used as a server-side challenge during the authorization code exchange.
schema:
example: S256
type: string
enum:
- plain
- S256
default: plain
- in: query
name: credential_id
description: |-
The ID of an existing Nylas connector's credential record.
If you set the `response_type` value to `code` then you can use the credential to override an OAuth connector's default settings and create a grant. You need to [create a credential record](/docs/reference/api/connector-credentials/create_credential/) before you can make a credential override request. If not provided, connector's default "active_credential_id" is used.
If you set the `response_type` value to `adminconsent`, with provider Microsoft, then this will be the OAuth of Microsoft's Service Account Admin Consent flow. You need to [set up the Microsoft connector with an Admin Consent credential before you can make this request](/docs/v3/auth/bulk-auth-grants/#set-up-microsoft-admin-consent-flow).
schema:
type: string
example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
- in: query
name: options
description: |-
(Google only) Set to `exclude_google_granted_scopes` to exclude Google-granted scopes from the
authorization request.
schema:
type: string
example: options=exclude_google_granted_scopes
responses:
'302':
description: Redirects user to provider's authorization page
headers:
Location:
description: Location header.
schema:
type: string
format: url
example: |
https://accounts.google.com/o/oauth2/auth/oauthchooseaccount?prompt=consent&login_hint=email@google.com&access_type=offline&state=<BA630DED06...> &redirect_uri=https://api.us.nylas.com/v3/connect/callback&response_type=code&client_id=<NYLAS_CLIENT_ID>
'400':
$ref: '#/components/responses/400'
/v3/connect/token:
post:
operationId: exchange_oauth2_token
tags:
- Authentication APIs
summary: Hosted OAuth - Token exchange
description: |-
The standard OAuth token endpoint for Hosted Authentication. This endpoint doesn't require authentication, as it is part of the auth process.
You can pass one of the following `grant_type` values:
- `authorization_code`: Exchange the `code` Nylas returns from the OAuth 2.0 authorization flow for tokens (`access_token` and `refresh_token`). - `refresh_token`: Use the existing `refresh_token` for an existing grant to issue a new `access_token`. You _must_ pass your API key in the `client_secret` field.
- `client_credentials`: Issue a new short-lived (1 hour) `access_token` using an existing `grant_id`. You _must_ pass your API key in the `client_secret` field. This is mainly used in Scheduler implementations.
This endpoint accepts both `application/json` and `application/x-www-form-urlencoded` request body types. The body parameters are the same for both, with the same naming conventions.
For more information, see the [Hosted authentication with access token documentation](/docs/v3/auth/hosted-oauth-accesstoken/).
### Failed token exchange requests
Each OAuth `code` is a unique, one-time-use credential. If your token exchange fails, you must restart the OAuth process. If you try to pass the original `code` in another token exchange request, the provider rejects the `code` and Nylas returns an error.
security: []
requestBody:
required: true
description: ''
content:
application/json:
schema:
oneOf:
- type: object
title: Exchange code
description: Exchange an authorization code for access and refresh tokens.
required:
- code
- client_id
- client_secret
- redirect_uri
- grant_type
properties:
client_id:
example: <NYLAS_CLIENT_ID>
type: string
description: Your Nylas application's client ID.
client_secret:
example: <NYLAS_API_KEY>
type: string
description: Your Nylas application's API key.
grant_type:
example: authorization_code
type: string
description: Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token` and `client_credentials` for issuing short-lived access based on the grant id provided.
enum:
- authorization_code
code:
type: string
description: The `code` from the OAuth 2.0 authorization flow.
redirect_uri:
example: https://example.com/callback-handler
format: url
type: string
description: |-
The URL that Nylas uses to redirect the user to your project after they complete
the authorization flow. This should match the `callback_uri` or `redirect_uri` that
you used to get the `code` during your initial
[authorization request](/docs/reference/api/authentication-apis/get_oauth2_flow/).
code_verifier:
example: nylas
type: string
description: |-
The plaintext `code` verifier (`code_challenge`) that you created in your
[authorization request](/docs/reference/api/authentication-apis/get_oauth2_flow/).
- type: object
title: Refresh access token
description: Use a refresh token to issue a new access token.
required:
- refresh_token
- client_id
- client_secret
- grant_type
properties:
client_id:
example: <NYLAS_CLIENT_ID>
type: string
description: Your Nylas application's client ID.
client_secret:
example: <NYLAS_API_KEY>
type: string
description: Your Nylas application's API key.
grant_type:
example: refresh_token
type: string
description: Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token` and `client_credentials` for issuing short-lived access based on the grant id provided.
enum:
- refresh_token
refresh_token:
example: <REFRESH_TOKEN>
type: string
description: Required to refresh or request a short-lived access token.
- type: object
title: Client credentials
description: Issue a short-lived access token for an existing grant.
required:
- grant_id
- client_id
- client_secret
- grant_type
properties:
client_id:
example: <NYLAS_CLIENT_ID>
type: string
description: Your Nylas application's client ID.
client_secret:
example: <NYLAS_API_KEY>
type: string
description: Your Nylas application's API key.
grant_type:
example: refresh_token
type: string
description: Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token` and `client_credentials` for issuing short-lived access based on the grant id provided.
enum:
- client_credentials
grant_id:
example: <GRANT_ID>
type: string
description: Required to request a short-lived access token for a specific grant.
responses:
'200':
description: The token exchange was successful.
content:
application/json:
schema:
type: object
title: data
properties:
access_token:
example: <NYLAS_ACCESS_TOKEN>
type: string
description: Supports exchanging a `code` for a token, or refreshing an access token using a `refresh_token`.
expires_in:
example: 3600
type: integer
default: 3600
description: The remaining lifetime of the access token, in seconds.
id_token:
example: <JWT_TOKEN>
type: string
description: |-
A JSON web token (JWT) that contains identity information about a user. It's digitally
signed by Nylas.
email:
example: example@gmail.com
type: string
description: The email address associated with the provider token exchange.
refresh_token:
example: <REFRESH_TOKEN>
type: string
description: Returned only if the `code` was requested using `access_type=offline`.
scope:
example: https://www.googleapis.com/auth/gmail.readonly profile
type: string
description: List of scopes associated with this token.
token_type:
example: Bearer
type: string
description: Currently always `Bearer`.
grant_id:
example: <NYLAS_GRANT_ID>
type: string
description: The ID for the new grant.
provider:
example: google
enum:
- google
- microsoft
- imap
- icloud
- yahoo
- ews
- zoom
type: string
description: The provider name associated with the authorized grant. Only returned during the code exchange process.
'400':
description: The token exchange was unsuccessful. Nylas returns a message with a description, and a link to troubleshooting documentation.
content:
application/json:
schema:
type: object
title: data
properties:
error:
example: invalid_request
type: string
description: Error type constant.
error_description:
example: 'Missing required parameter: code'
type: string
description: A human-readable error description.
error_uri:
example: developer.nylas.com/docs/api/errors/400-response/
type: string
description: A URL to the related documentation and troubleshooting regarding this error.
error_code:
example: 400
type: string
description: Error code used for referencing the documentation, logs, and data stream.
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request POST \
--url "https://api.us.nylas.com/v3/connect/token" \
--header 'Content-Type: application/json' \
--data '{
"client_id": "<NYLAS_CLIENT_ID>",
"client_secret": "<NYLAS_API_KEY>",
"grant_type": "authorization_code",
"code": "<AUTHORIZATION_CODE>",
"redirect_uri": "https://example.com/callback-handler",
"code_verifier": "<CODE_VERIFIER>"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
// Exchange the authorization code returned by Nylas for an access token and
// grant ID. Call this from your OAuth callback handler with the `code` query
// parameter that Nylas appends to your `redirectUri`.
const code = "<AUTHORIZATION_CODE>";
try {
const response = await nylas.auth.exchangeCodeForToken({
clientId: "<NYLAS_CLIENT_ID>",
redirectUri: "http://localhost:3000/oauth/exchange",
code,
// Only set `codeVerifier` if you used PKCE in the initial authorization request.
// codeVerifier: "<PKCE_CODE_VERIFIER>",
});
console.log("Grant ID:", response.grantId);
console.log("Access token:", response.accessToken);
} catch (error) {
console.error("Error exchanging code for token:", error);
}
- lang: python
label: Python SDK
source: |
from flask import Flask, request
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
app = Flask(__name__)
REDIRECT_URI = "http://localhost:9000/oauth/exchange"
@app.route("/oauth/exchange", methods=["GET"])
def exchange_code_for_token():
code_exchange_response = nylas.auth.exchange_code_for_token(
request={
"code": request.args.get("code"),
"client_id": "<NYLAS_CLIENT_ID>",
"redirect_uri": REDIRECT_URI,
}
)
return {
"email_address": code_exchange_response.email,
"grant_id": code_exchange_response.grant_id,
}
- lang: ruby
label: Ruby SDK
source: |
# frozen_string_literal: true
require 'nylas'
require 'sinatra'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
set :show_exceptions, :after_handler
# Receive the authorization code from Nylas and exchange it for a grant.
get '/oauth/exchange' do
code = params[:code]
status 404 if code.nil?
begin
response = nylas.auth.exchange_code_for_token({
client_id: "<NYLAS_CLIENT_ID>",
redirect_uri: 'http://localhost:4567/oauth/exchange',
code: code
})
rescue StandardError
status 500
else
grant_id = response[:grant_id]
email = response[:email]
"Grant_Id: #{grant_id} \n Email: #{email}"
end
end
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.CodeExchangeRequest;
import com.nylas.models.CodeExchangeResponse;
public class ExchangeCodeForToken {
public static void main(String[] args) {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Exchange the authorization code returned by Nylas for an access token and
// grant ID. Call this from your OAuth callback handler with the `code` query
// parameter that Nylas appends to your `redirectUri`.
CodeExchangeRequest codeRequest = new CodeExchangeRequest.Builder(
"http://localhost:3000/oauth/exchange",
"<AUTHORIZATION_CODE>",
"<NYLAS_CLIENT_ID>")
// Only set codeVerifier if you used PKCE in the initial authorization request.
// .codeVerifier("<PKCE_CODE_VERIFIER>")
.build();
try {
CodeExchangeResponse codeResponse = nylas.auth().exchangeCodeForToken(codeRequest);
System.out.println("Grant ID: " + codeResponse.getGrantId());
System.out.println("Access token: " + codeResponse.getAccessToken());
} catch (Exception e) {
System.err.println("Error exchanging code for token: " + e);
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.CodeExchangeRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
// Exchange the authorization code returned by Nylas for an access token and
// grant ID. Call this from your OAuth callback handler with the `code` query
// parameter that Nylas appends to your `redirectUri`.
val codeRequest = CodeExchangeRequest.Builder(
"http://localhost:3000/oauth/exchange",
"<AUTHORIZATION_CODE>",
"<NYLAS_CLIENT_ID>")
// Only set codeVerifier if you used PKCE in the initial authorization request.
// .codeVerifier("<PKCE_CODE_VERIFIER>")
.build()
try {
val codeResponse = nylas.auth().exchangeCodeForToken(codeRequest)
println("Grant ID: ${codeResponse.grantId}")
println("Access token: ${codeResponse.accessToken}")
} catch (e: Exception) {
System.err.println("Error exchanging code for token: $e")
}
}
/v3/connect/revoke:
post:
operationId: revoke_oauth2_token_and_grant
tags:
- Authentication APIs
summary: Hosted OAuth - Revoke OAuth token
description: |-
Revokes the specified OAuth access token. When you revoke the token, Nylas _doesn't_ revoke the
grant or the associated provider token. This means that a user can re-authenticate to get a new
access token for the existing grant, so their `grant_id` doesn't change.
If you revoke a Nylas access token, Nylas also revokes all child tokens and the parent
`refresh_token` attached to the access token.
parameters:
- in: query
name: token
schema:
type: string
required: true
description: The token to revoke
responses:
'200':
description: The token was revoked successfully.
content:
application/json:
schema:
type: object
'400':
description: The token could not be revoked, possibly because it was invalid or already expired.
content:
application/json:
schema:
type: object
title: data
properties:
error:
example: invalid_token
type: string
description: Error type constant.
error_description:
example: Token expired or revoked
type: string
description: Human readable error description.
error_uri:
example: developer.nylas.com/docs/api/errors/400-response/
type: string
description: A url to the related documentation and troubleshooting regarding this error.
error_code:
example: 400
type: string
description: Error code used for referencing the docs, logs and data stream.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/connect/revoke?token=<TOKEN>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
// Configure the Nylas SDK with your API key and server URL
const NylasConfig = {
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
};
const nylas = new Nylas(NylasConfig);
const revokeToken = async () => {
try {
const token = "<TOKEN>";
const response = await nylas.auth.revoke(token);
console.log("Token Revoked:", response);
} catch (error) {
console.error("Error removing connector:", error);
}
};
revokeToken();
- lang: python
label: Python SDK
source: |-
import sys
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
request = nylas.auth.revoke(
"<TOKEN>",
)
print(request)
- lang: ruby
label: Ruby SDK
source: |
# frozen_string_literal: true
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
begin
nylas.auth.revoke("<NYLAS_AUTH_TOKEN>")
puts "The token was successfully revoked"
rescue Nylas::NylasApiError => e
puts "The token could not be revoked: #{e.message}"
end
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.TokenParams;
public class Main {
public static void main(String[] args) {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
TokenParams token = new TokenParams("<NYLAS_ACCESS_TOKEN>");
try {
boolean tokenStatus = nylas.auth().revoke(token);
if (tokenStatus) {
System.out.println("The token was successfully removed");
} else {
System.out.println("The token cannot be removed");
}
} catch (Exception e) {
System.out.println("Invalid token cannot be removed");
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
fun main() {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val token = TokenParams("<NYLAS_ACCESS_TOKEN>")
try {
val tokenStatus = nylas.auth().revoke(token)
if (tokenStatus) {
println("The token was successfully removed")
} else {
println("The token cannot be removed")
}
} catch (e: Exception) {
print("Invalid token cannot be removed")
}
}
/v3/connect/tokeninfo:
get:
operationId: info_oauth2_token
tags:
- Authentication APIs
summary: OAuth Token Info
description: |
Get info about a specific token based on the identifier you include. Use _either_ the ID Token or Access Token.</br></br>**Note**: Because Nylas uses the schema outlined in [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068#name-requesting-a-jwt-access-tok) to ensure that it is compatible with all OAuth libraries in all languages, the format for this endpoint is different from the other OAuth endpoints.
parameters:
- in: query
name: id_token
schema:
type: string
description: ID token
- in: query
name: access_token
schema:
type: string
description: Access token
responses:
'200':
description: Returns Token info
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: object
properties:
iss:
type: string
description: Token's issuer
example: https://nylas.com
aud:
type: string
description: Token's audience
example: http://localhost:3030
sub:
type: string
description: Token's subject
example: daf84d88-f274-46cc-bbc9-aed7dac061c7
email:
type: string
description: Email of grant's user token belongs to
example: user@example.com
iat:
type: integer
description: Token issued at
example: 1692094848
exp:
type: integer
description: Token expires at
example: 1692095173
'400':
description: Bad request
content:
application/json:
schema:
type: object
title: data
properties:
error:
example: invalid_token
type: string
description: Error type constant.
error_description:
example: Token expired or revoked
type: string
description: Human readable error description.
error_uri:
example: developer.nylas.com/docs/api/errors/400-response/
type: string
description: A url to the related documentation and troubleshooting regarding this error.
error_code:
example: 400
type: string
description: Error code used for referencing the docs, logs and data stream.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/connect/tokeninfo?id_token=<ACCESS_TOKEN_ID>&access_token=<NYLAS_ACCESS_TOKEN>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const accessToken = "<ACCESS_TOKEN>";
try {
const tokenInfo = await nylas.auth.accessTokenInfo(accessToken);
console.log("Token info:", tokenInfo);
} catch (error) {
console.error("Error fetching token info:", error);
}
- lang: python
label: Python SDK
source: |-
import sys
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
request = nylas.auth.id_token_info(
"<ACCESS_TOKEN_ID>",
)
print(request)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\t api_key: \"<NYLAS_API_KEY>\"\n)\n\nquery_params = {\n id_token: \"<ACCESS_TOKEN_ID>\"\n}\n\ntoken_info = nylas.auth.access_token_info(query_params: query_params)\n\nputs token_info\n"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class GetTokenInfo {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<TokenInfoResponse> token = nylas.auth().idTokenInfo("<ACCESS_TOKEN_ID>");
System.out.println(token);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val token = nylas.auth().idTokenInfo("<ACCESS_TOKEN_ID>")
print(token)
}
/v3/connect/custom:
post:
summary: Bring Your Own Authentication
tags:
- Manage Grants
- Authentication APIs
operationId: byo_auth
description: |-
Manually creates a grant using the Bring Your Own (BYO) Authentication flow. If you're handling the
OAuth flow in your own project or you want to migrate existing users, BYO Auth lets you provide
the user's `refresh_token` to create a grant.
If a user previously authenticated with your Nylas application using the same email address, Nylas
detects this and re-authenticates their existing grant instead of creating a new one. The API
response contains the user's existing `grant_id`.
### Supported providers
Pick the request body variant that matches your provider:
- **Refresh token** — OAuth providers (`google`, `microsoft`, `yahoo`, `zoom`) using a standard refresh token.
- **Credential override** — OAuth providers, but using a stored [credential record](/docs/reference/api/connector-credentials/) to swap in different client credentials.
- **Microsoft bulk auth** — Microsoft App Permissions. Requires a [connector credential](/docs/reference/api/connector-credentials/create_credential/) and the [admin consent flow](/docs/v3/auth/bulk-auth-grants/#make-a-microsoft-admin-consent-flow-request-using-nylas-apis).
- **Google bulk auth** — Google Service Accounts. Requires a [connector credential](/docs/reference/api/connector-credentials/create_credential/) and the [Service Account flow](/docs/v3/auth/bulk-auth-grants/#google-app-permission-via-nylas).
- **IMAP** — direct IMAP/SMTP credentials for any IMAP provider.
- **iCloud** — an iCloud email address plus an [Apple app password](https://support.apple.com/en-us/HT204397).
- **EWS** — on-premises Microsoft Exchange; hosted Exchange should use Microsoft Graph instead.
- **Virtual calendar** — a [Virtual Calendar](/docs/v3/calendar/virtual-calendars/) grant for scheduling without a third-party provider.
- **Zoom Meetings** — Zoom OAuth. Your OAuth app must include the [granular scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-granular/) `meeting:write:meeting`, `meeting:update:meeting`, and `meeting:delete:meeting`.
- **Nylas (Agent Account)** — a fully Nylas-hosted [Agent Account](/docs/v3/agent-accounts/) email and calendar mailbox on a domain you've registered with Nylas.
security:
- NYLAS_API_KEY: []
requestBody:
required: true
description: ''
content:
application/json:
schema:
oneOf:
- type: object
title: Refresh token
description: Use an OAuth refresh token to create a grant.
required:
- provider
- settings
properties:
provider:
type: string
description: The user's OAuth provider.
enum:
- google
- microsoft
- yahoo
- zoom
settings:
description: A list of settings required by the provider, including the `refresh_token`.
example:
refresh_token: 1//09XpDHQ6hq6PrCgYIARAAGAkSNwF...
type: object
properties:
refresh_token:
type: string
description: The refresh token associated with the email account.
example: 1//09XpDHQ6hq6PrCgYIARAAGAkSNwF...
- type: object
title: Credential override
description: Override the connector's client credentials with a stored credential record.
required:
- provider
- settings
properties:
provider:
type: string
description: The user's OAuth provider.
enum:
- google
- microsoft
- yahoo
- zoom
settings:
description: |-
A list of settings required by the provider, including the `refresh_token`.
If you add the `credential_id` field with the UUID of an existing
[credential record](/docs/reference/api/connector-credentials/), Nylas uses the
provider's `client_id` and `client_secret` from the credential record.
example:
refresh_token: 1//09XpDHQ6hq6PrCgYIARAAGAkSNwF...
credential_id: e280d2fa-86db-4937-81c9-ffbd539872d6
type: object
properties:
refresh_token:
type: string
description: The refresh token associated with the email account.
example: 1//09XpDHQ6hq6PrCgYIARAAGAkSNwF...
credential_id:
type: string
description: |-
The UUID of an existing
[credential record](/docs/reference/api/connector-credentials/) that Nylas
can use to override the default connector settings.
- type: object
title: Microsoft bulk auth
description: Create a grant via Microsoft admin-consent App Permissions.
required:
- provider
- settings
properties:
provider:
type: string
description: The user's OAuth provider.
enum:
- microsoft
settings:
description: |-
A list of settings required by Microsoft. This sets the user's email address and
the Nylas `credential_id`.
If a grant already exists for the provided email address, Nylas automatically starts
the re-authentication process.
example:
email_address: user@office365.com
credential_id: e280d2fa-86db-4937-81c9-ffbd539872d6
type: object
properties:
email_address:
type: string
description: The user's email address.
example: user@office365.com
credential_id:
type: string
description: |-
The ID of an existing `adminconsent` credential that Nylas can use to
authenticate Microsoft App Permission grants.
example: e280d2fa-86db-4937-81c9-ffbd539872d6
- type: object
title: Google bulk auth
description: Create a grant via a Google Service Account.
required:
- provider
- settings
properties:
provider:
type: string
description: The user's OAuth provider.
enum:
- google
settings:
description: |-
A list of settings required by Google. This sets the user's email address and the
Nylas `credential_id`.
If a grant already exists for the provided email address, Nylas automatically starts
the re-authentication process.
example:
email_address: user@gmailworkspace.com
credential_id: e280d2fa-86db-4937-81c9-ffbd539872d6
type: object
properties:
email_address:
type: string
description: The user's email address.
example: user@gmailworkspace.com
credential_id:
type: string
description: |-
The ID of an existing `serviceaccount` credential that Nylas can use to
authenticate Google Service Account grants.
example: e280d2fa-86db-4937-81c9-ffbd539872d6
scopes:
type: array
items:
type: string
description: A list of scopes for the grant.
example:
- https://www.googleapis.com/auth/userinfo.email
- https://www.googleapis.com/auth/userinfo.profile
- https://www.googleapis.com/auth/gmail.readonly
- type: object
title: IMAP
description: Create an IMAP grant using username, password, and server details.
required:
- provider
- settings
properties:
provider:
type: string
description: The user's provider.
enum:
- imap
settings:
description: |-
A list of settings needed for Nylas to connect to the provider's IMAP server. If
the provider uses a different address or credentials for SMTP (to send email),
include that information separately in the SMTP fields.
example:
imap_username: <IMAP_USERNAME>
imap_password: <IMAP_PASSWORD>
imap_host: <IMAP_HOST>
imap_port: '993'
smtp_host: <SMTP_HOST>
smtp_port: '465'
smtp_username: <SMTP_USERNAME>
smtp_password: <SMTP_PASSWORD>
type: object
properties:
imap_username:
type: string
description: The user's username or email address.
example: nyla@example.com
imap_password:
type: string
description: The user's email account password or app password.
imap_host:
type: string
description: |-
The IMAP host. If you don't define the host in the request payload, Nylas tries
to auto-detect the hostname using the provided `imap_username`. If you're using
a self-hosted IMAP server, you _must_ provide the hostname.
example: imap.mail.me.com
imap_port:
type: integer
description: |-
The IMAP port number. If you don't define the port in the request payload, Nylas
tries to auto-detect it using the provided `imap_username`. If you're using a
self-hosted IMAP server, you _must_ provide the port number.
example: 993
smtp_host:
type: string
description: |-
The SMTP host. If you don't define the host in the request payload, Nylas tries
to auto-detect it using the provided `imap_username`. If you're using a self-
hosted SMTP server, you _must_ provide the hostname.
example: smtp.mail.me.com
smtp_port:
type: integer
description: |-
The SMTP port number. If you don't define the port in the request payload, Nylas
tries to auto-detect it using the provided `imap_username`. If you're using a
self-hosted SMTP server, you _must_ provide the port number.
example: 587
smtp_username:
type: string
description: |-
The user's SMTP username, if their SMTP credentials are different from their
IMAP credentials.
example: nyla@example.com
smtp_password:
type: string
description: |-
The user's SMTP password, if their SMTP credentials are different from their
IMAP credentials.
- type: object
title: iCloud
description: Create an iCloud grant using an email address and app password.
required:
- provider
- settings
properties:
provider:
type: string
description: The user's provider.
enum:
- icloud
settings:
description: A list of settings required by iCloud.
example:
username: <ICLOUD_USERNAME>
password: <ICLOUD_PASSWORD>
type: object
properties:
username:
type: string
description: The user's iCloud email address.
example: example@icloud.com
password:
type: string
description: The user's app password.
- type: object
title: EWS
description: Create a grant for an on-premises Microsoft Exchange account.
required:
- provider
- settings
properties:
provider:
type: string
description: The user's provider.
enum:
- ews
settings:
description: A list of settings required by EWS.
example:
email: nyla@ews.example.com
ews_username: <EWS_USERNAME>
ews_password: <EWS_PASSWORD>
ews_host: <EWS_HOST>
type: object
properties:
email:
type: string
description: The user's email address.
example: nyla@ews.example.com
ews_username:
type: string
description: The user's Exchange username, formatted as an email address.
example: nyla@ews.example.com
ews_password:
type: string
description: The user's Microsoft Exchange password.
ews_host:
type: string
description: |-
The EWS host. If you don't define the host in the request payload, Nylas tries
to auto-detect it using the provided `ews_username`. If you're using a self-
hosted EWS server, you _must_ provide the hostname.
example: ews.mail.example.com
ews_port:
type: integer
description: The EWS port number.
default: 443
scope:
type: array
items:
type: string
description: A list of scopes for the grant.
example:
- ews.messages
- ews.calendars
- ews.contacts
- type: object
title: Virtual calendar
description: Create a Virtual Calendar grant for scheduling without a provider.
required:
- provider
- settings
properties:
provider:
type: string
description: The account's provider.
enum:
- virtual-calendar
example: virtual-calendar
settings:
description: A list of settings required by Nylas.
type: object
properties:
email:
type: string
description: |-
The virtual account identifier. This can be any arbitrary string — it doesn't
have to be in email address format.
example: floor1desk24@example.com
state:
type: string
description: |-
An optional state value that Nylas returns to your project when the authentication
flow completes. If you include the `state`, Nylas returns the unmodified value to
your project. You can use this for verification, or to track information about the
account.
For more information about the `state` parameter, see the
[OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749) or the
[official OAuth 2.0 documentation](https://www.oauth.com/oauth2-servers/authorization/the-authorization-request/).
example: my-state
- type: object
title: Zoom Meetings
description: Create a Zoom Meetings grant from an OAuth refresh token.
required:
- provider
- settings
properties:
provider:
type: string
description: The user's OAuth provider (in this case, `zoom`).
enum:
- zoom
settings:
description: A list of settings required by Zoom.
type: object
properties:
refresh_token:
type: string
description: The `refresh_token` from the Zoom `code` exchange flow.
example: <ZOOM_REFRESH_TOKEN>
- type: object
title: Nylas (Agent Account)
description: Create a Nylas-hosted Agent Account on a domain you've registered.
required:
- provider
- settings
properties:
provider:
type: string
description: The account's provider. Use `nylas` to create an Agent Account.
enum:
- nylas
example: nylas
name:
type: string
description: |-
The Agent Account's display name. Nylas stores this as the grant's `name` and uses it
as the default `From` display name when the account sends email, so a recipient sees
`Sales Agent <sales-agent@agents.yourcompany.com>` instead of the bare address. Omit it
and the account sends with no display name. You can override the name on an individual
message with the `from` field on [send](/docs/reference/api/messages/send-message/).
example: Sales Agent
workspace_id:
type: string
description: |-
The ID of the [workspace](/docs/reference/api/workspaces/) to place the Agent Account in.
The workspace's `policy_id` and `rule_ids` govern the account's limits, spam detection,
and mail rules. If omitted, Nylas auto-groups the account into a workspace whose `domain`
matches the email address (when `auto_group` is enabled), or places it in the
application's default workspace.
example: abf6ff99-05ad-4c0a-aaf8-400aacf2470a
settings:
description: The settings required for a Nylas Agent Account.
example:
email: user@yourdomain.com
type: object
required:
- email
properties:
email:
type: string
description: |-
The Agent Account's email address. The email's domain must match a domain you've already
[registered with Nylas](/docs/reference/api/manage-domains/).
example: user@yourdomain.com
app_password:
type: string
description: |-
Optional password that unlocks IMAP and SMTP-submission access to the Agent Account.
Omit it and protocol-level access stays disabled. Must be 18–40 printable ASCII
characters (codes 33–126) and contain at least one uppercase letter, one lowercase
letter, and one digit. Stored as a bcrypt hash — it can't be retrieved later, only
reset by updating the grant. See [Connect mail clients to an Agent Account](/docs/v3/agent-accounts/mail-clients/).
minLength: 18
maxLength: 40
example: MySecureP4ssword!2024
x-code-samples:
- lang: bash
label: cURL (Microsoft)
source: |
curl --request POST \
--url "https://api.us.nylas.com/v3/connect/custom" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"provider": "microsoft",
"settings": {
"refresh_token": "<REFRESH_TOKEN>"
}
}'
- lang: bash
label: cURL (Google)
source: |
curl --request POST \
--url "https://api.us.nylas.com/v3/connect/custom" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"provider": "google",
"settings": {
"refresh_token": "<GOOGLE_REFRESH_TOKEN>"
}
}'
- lang: bash
label: cURL (IMAP)
source: |
curl --request POST \
--url "https://api.us.nylas.com/v3/connect/custom" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"provider": "imap",
"settings": {
"imap_username": "user@example.com",
"imap_password": "<IMAP_PASSWORD>",
"imap_host": "imap.example.com",
"imap_port": 993,
"smtp_host": "smtp.example.com",
"smtp_port": 587,
"smtp_username": "user@example.com",
"smtp_password": "<SMTP_PASSWORD>"
}
}'
- lang: bash
label: cURL (iCloud)
source: |
curl --request POST \
--url "https://api.us.nylas.com/v3/connect/custom" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"provider": "icloud",
"settings": {
"username": "user@icloud.com",
"password": "<ICLOUD_APP_PASSWORD>"
}
}'
- lang: bash
label: cURL (Virtual Calendar)
source: |
curl --request POST \
--url "https://api.us.nylas.com/v3/connect/custom" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"provider": "virtual-calendar",
"settings": {
"email": "conference-room-3a@example.com"
}
}'
- lang: bash
label: cURL (Nylas Agent Account)
source: |
curl --location 'https://api.us.nylas.com/v3/connect/custom' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"provider": "nylas",
"name": "Sales Agent",
"workspace_id": "<WORKSPACE_ID>",
"settings": {
"email": "user@yourdomain.com"
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
// Microsoft (refresh-token) Bring-Your-Own-Auth grant.
async function authenticateMicrosoft() {
const grant = await nylas.auth.customAuthentication({
requestBody: {
provider: "microsoft",
settings: {
refreshToken: "<MICROSOFT_REFRESH_TOKEN>",
},
scope: ["Mail.Read", "Mail.Send"],
},
});
return grant;
}
// Nylas Agent Account grant — provisions a Nylas-hosted mailbox on a domain
// you've registered with Nylas. No OAuth refresh token required.
async function authenticateAgentAccount() {
const grant = await nylas.auth.customAuthentication({
requestBody: {
provider: "nylas",
name: "Sales Agent",
settings: {
email: "agent@yourdomain.com",
policyId: "<POLICY_ID>",
},
},
});
return grant;
}
authenticateMicrosoft()
.then((grant) => console.log("Microsoft grant:", grant))
.catch((error) => console.error("Microsoft auth error:", error));
authenticateAgentAccount()
.then((grant) => console.log("Agent Account grant:", grant))
.catch((error) => console.error("Agent Account auth error:", error));
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>",
)
request_body = {
provider: '<PROVIDER>',
settings: {'username': '<USERNAME>', 'password': '<PASSWORD>'},
scope: 'email.read_only,calendar.read_only,contacts.read_only',
state: '<STATE>'
}
auth = nylas.auth.custom_authentication(request_body)
puts auth
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
request_body = {
"provider": "icloud",
"settings": {
"username": "<USERNAME>",
"password": "<PASSWORD>",
},
"scope": ["email.read_only", "calendar.read_only", "contacts.read_only"],
"state": "<STATE>",
}
grant = nylas.auth.custom_authentication(request_body)
print(grant)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class Main {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
AuthProvider provider = AuthProvider.ICLOUD;
Map<String, Object> settings = new HashMap<>();
settings.put("username", "<USERNAME>");
settings.put("password", "<PASSWORD>");
List<String> scopes = List.of(
"email.read_only", "calendar.read_only", "contacts.read_only");
CreateGrantRequest requestBody = new CreateGrantRequest.Builder(provider, settings)
.state("<STATE>")
.scopes(scopes)
.build();
Response<Grant> grant = nylas.auth().customAuthentication(requestBody);
System.out.println(grant);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
fun main() {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val provider = AuthProvider.ICLOUD
val settings = mapOf("username" to "<USERNAME>", "password" to "<PASSWORD>")
val scopes = listOf("email.read_only", "calendar.read_only", "contacts.read_only")
val requestBody = CreateGrantRequest(provider, settings, "<STATE>", scopes)
val grant = nylas.auth().customAuthentication(requestBody)
println(grant)
}
responses:
'201':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/GrantObject'
description: Grant Created
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
/v3/grants:
get:
summary: Return all grants
tags:
- Manage Grants
operationId: get-all-grants
description: Returns all grants in your Nylas application.
security:
- NYLAS_API_KEY: []
parameters:
- name: account_id
in: query
schema:
type: string
description: |-
Returns grants with a matching v2 Nylas account ID. Only applicable for grants migrated from
Nylas v2.
- name: account_ids
in: query
schema:
type: string
description: |-
Returns grants with a matching list of v2 Nylas account IDs. Only applicable for grants migrated
from Nylas v2.
- name: before
in: query
schema:
type: integer
description: |-
Returns grants whose `created_at` value is less than or equal to the defined value, in seconds
using the Unix timestamp format.
- name: email
in: query
schema:
type: string
example: nyla@example.com
description: Returns grants with a matching `email`.
- name: grant_status
in: query
schema:
type: string
enum:
- invalid
- valid
description: Filters for only valid or invalid grants.
- name: ip
in: query
schema:
type: string
description: Returns grants with a matching IP address.
- name: limit
in: query
schema:
type: integer
default: 10
description: |-
The maximum number of grants to return. See
[Pagination](/docs/reference/api/#pagination) for more information.
- name: offset
in: query
schema:
type: integer
default: 0
description: |-
The offset value for the request. See
[Pagination](/docs/reference/api/#pagination) for more information.
- name: order_by
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
description: The order in which Nylas should sort results for the request.
- name: provider
in: query
schema:
type: string
description: Returns grants with a matching `provider`.
- name: since
in: query
schema:
type: integer
description: |-
Returns grants whose `created_at` value is greater than or equal to the defined value, in
seconds using the Unix timestamp format.
- name: sort_by
in: query
schema:
type: string
enum:
- created_at
- updated_at
default: created_at
description: The field Nylas should use to sort results for the request.
- name: workspace_id
in: query
schema:
type: string
description: Returns grants in the specified workspace.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants?limit=3&provider=google' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listGrants() {
try {
const grants = await nylas.grants.list();
console.log("Grants found:", grants);
} catch (error) {
console.error("Error finding grants:", error);
}
}
listGrants();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
grants = nylas.grants.list()
print(grants)
- lang: ruby
label: Ruby SDK
source: |
# frozen_string_literal: true
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: '<NYLAS_API_KEY>'
)
grants, _ = nylas.grants.list()
grants.each do |grant|
puts "#{grant}\n\n"
end
- lang: java
label: Java SDK
source: |-
// Import Nylas packages
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.List;
public class read_grants {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Grant> grants = nylas.grants().list();
for(Grant grant : grants.getData()){
System.out.println(grant);
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |
// Import Nylas packages
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val grants = nylas.grants().list().data;
for(grant in grants){
println(grant)
}
}
responses:
'200':
description: Success. Returns an array of Grant objects.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: array
items:
$ref: '#/components/schemas/GrantObject'
limit:
type: integer
example: 10
offset:
type: integer
example: 0
'401':
description: 'Error: Not authenticated'
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: 'Error: not found'
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/grants/{grantId}:
get:
parameters:
- name: grantId
schema:
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
type: string
in: path
required: true
- name: expose_aliases
schema:
type: boolean
default: false
in: query
required: false
description: |-
If set to `true`, the response will include an array of email aliases associated with the grant.
Applicable only for Google and Microsoft grants. Not set by default.
For Microsoft, aliases are only available for Microsoft 365 / Exchange Online mailboxes. Free
Outlook.com (consumer) accounts have no aliases to expose, so the `email_aliases` field is
omitted from the response entirely.
Email aliases are only returned for the called API, not stored in the grant object permanently.
operationId: get_grant_by_id
tags:
- Manage Grants
summary: Get a grant
description: |-
Gets a grant with the provided ID.
If the grant's `grant_status` is `invalid`, the grant has expired and needs to be re-authenticated. See [Handling expired grants](https://developer.nylas.com/docs/dev-guide/best-practices/grant-lifecycle/) for best practices on detection and recovery.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
// Instantiate Nylas SDK
const NylasConfig = {
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
};
const nylas = new Nylas(NylasConfig);
// Define the ID of the grant to find
const grantId = "<NYLAS_GRANT_ID>";
// Function to find the grant
async function findGrant() {
try {
const grant = await nylas.grants.find({ grantId });
console.log("Grant found:", grant);
} catch (error) {
console.error("Error finding grant:", error);
}
}
findGrant();
- lang: python
label: Python SDK
source: |-
import sys
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
grant = nylas.grants.find(
grant_id
)
print(grant)
- lang: ruby
label: Ruby SDK
source: |-
# frozen_string_literal: true
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: '<NYLAS_API_KEY>'
)
grant, _ = nylas.grants.find(grant_id: "<NYLAS_GRANT_ID>")
puts grant
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class get_grants {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Grant> grant = nylas.grants().find("<NYLAS_GRANT_ID>");
System.out.println(grant);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val grant = nylas.grants().find("<NYLAS_GRANT_ID>")
print(grant)
}
security:
- NYLAS_API_KEY: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/GrantObject'
description: Returns Grant object
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
patch:
parameters:
- name: grantId
schema:
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
type: string
in: path
required: true
operationId: patch_grant_by_id
tags:
- Manage Grants
summary: Update a grant
description: |-
Updates the specified grant's stored settings or scope metadata.
**Common use cases:**
- **Rotate a refresh token** — If you obtain a new `refresh_token` from a provider (for example, after a user re-consents in your own OAuth flow), you can update the grant's stored token without deleting and recreating the grant. Pass the new token in `settings.refresh_token`.
- **Update stored scope list** — Update the `scope` array to reflect the scopes the grant currently holds. Note: this only updates the scope metadata stored by Nylas. It does **not** change the actual permissions the provider has granted. To change provider permissions, the user must re-authenticate through the provider's OAuth consent flow.
When you make a `PATCH` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request PATCH \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"settings": {
"refresh_token": "<NEW_REFRESH_TOKEN>"
},
"scope": ["Mail.Read", "Mail.Send", "User.Read", "offline_access"]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const NylasConfig = {
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
};
const nylas = new Nylas(NylasConfig);
async function updateGrant() {
try {
const grant = await nylas.grants.update({
grantId: "<NYLAS_GRANT_ID>",
requestBody: {
scope: ["mail.ready"],
},
});
console.log("Updated Grant:", grant);
} catch (error) {
console.error("Error to update grant:", error);
}
}
updateGrant();
- lang: python
label: Python SDK
source: |-
import sys
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
grant = nylas.grants.update(
grant_id,
request_body={
"scope": ["mail.ready"]
}
)
print(grant)
- lang: ruby
label: Ruby SDK
source: |-
# frozen_string_literal: true
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
scope: ["mail.read"]
}
status, _ = nylas.grants.update(grant_id: "a57cdf3e-6580-4097-9d71-a95e867fb79c", request_body: request_body)
puts status
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class update_grants {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<String> scope = new ArrayList<>();
scope.add("mail.read");
UpdateGrantRequest requestBody = new UpdateGrantRequest.Builder().scopes(scope).build();
Response<Grant> grant = nylas.grants().update("<NYLAS_GRANT_ID>", requestBody);
System.out.println(grant);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.UpdateGrantRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val scope = listOf("mail.read")
val requestBody = UpdateGrantRequest(null, scope)
val grant = nylas.grants().update("<NYLAS_GRANT_ID>", requestBody);
print(grant)
}
security:
- NYLAS_API_KEY: []
requestBody:
required: true
description: ''
content:
application/json:
schema:
type: object
properties:
settings:
description: Provider-specific settings for the grant. For OAuth providers, this typically contains the `refresh_token`. Nylas replaces the entire `settings` object with the value you provide.
example:
refresh_token: <NEW_REFRESH_TOKEN>
type: object
scope:
type: array
description: Updates the list of OAuth scopes stored on the grant. This updates only Nylas' record of the scopes — it does not change the actual permissions at the provider. To change provider permissions, the user must re-authenticate through the provider's OAuth consent flow.
example:
- Mail.Read
- Mail.Send
- User.Read
- offline_access
items:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/GrantObject'
description: Returns Grant object
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
delete:
parameters:
- name: grantId
schema:
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
type: string
in: path
required: true
operationId: delete_grant_by_id
tags:
- Manage Grants
summary: Delete a grant
description: |-
Delete an existing grant by ID. You cannot re-authenticate the deleted grant. If you try to re-authenticate it, Nylas creates a new grant instead.
**Before deleting a grant, consider whether re-authentication is the better option.** Deleting a grant is permanent: object IDs may change (especially for IMAP providers), sync state resets, and tracking links break. See [Handling expired grants](https://developer.nylas.com/docs/dev-guide/best-practices/grant-lifecycle/) for details.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
// Instantiate Nylas SDK
const NylasConfig = {
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
};
const nylas = new Nylas(NylasConfig);
// Define the identifier for the grant
const identifier = "<NYLAS_GRANT_ID>";
// Function to delete the grant
async function destroyGrant() {
try {
const response = await nylas.grants.destroy({
grantId: identifier,
});
console.log("Grant deleted:", response);
} catch (error) {
console.error("Error finding grant:", error);
}
}
destroyGrant();
- lang: python
label: Python SDK
source: |-
import sys
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
response = nylas.grants.destroy(
grant_id
)
print(response)
- lang: ruby
label: Ruby SDK
source: |-
# frozen_string_literal: true
# Load gems
require 'nylas'
nylas = Nylas::Client.new(
api_key: '<NYLAS_API_KEY>'
)
status, _ = nylas.grants.destroy(grant_id: "<NYLAS_GRANT_ID>")
puts status
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class read_grants {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse grant = nylas.grants().destroy("<NYLAS_GRANT_ID>");
System.out.println(grant);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val grant = nylas.grants().destroy("<NYLAS_GRANT_ID>")
print(grant)
}
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/200-delete'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/grants/me:
get:
operationId: get_grant_by_access_token
tags:
- Manage Grants
summary: Get current grant
description: Gets a grant using current access token
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/me' \
--header 'Authorization: Bearer <NYLAS_USER_ACCESS_TOKEN>' \
--header 'Accept: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
// "me" resolves to the grant associated with the access token used on the
// request. Pair with an ACCESS_TOKEN auth header rather than the API key.
async function getCurrentGrant() {
try {
const grant = await nylas.grants.find({
grantId: "me",
});
console.log("Current grant:", grant);
} catch (error) {
console.error("Error retrieving current grant:", error);
}
}
getCurrentGrant();
security:
- ACCESS_TOKEN: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/GrantObject'
description: Returns Grant object
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/workspaces:
get:
summary: Return all workspaces
tags:
- Workspaces
operationId: get-all-workspaces
description: |-
Returns all workspaces in your Nylas application. The application queried is determined based on
the API key you use to authorize your request.
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/workspaces" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
description: Success. Returns a list of Workspace objects.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: array
items:
$ref: '#/components/schemas/WorkspaceObject'
'401':
description: 'Error: Not authenticated'
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: 'Error: Not found'
content:
application/json:
schema:
$ref: '#/components/schemas/404'
post:
summary: Create a workspace
tags:
- Workspaces
operationId: create-workspace
description: Creates a workspace.
security:
- NYLAS_API_KEY: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
- name
properties:
auto_group:
type: boolean
description: |-
When `true`, specifies that newly created grants in the application are automatically
assigned to the workspace if their email address' domain matches the `domain`.
default: true
example: true
domain:
type: string
description: |-
The top-level domain associated with the workspace. You can't change the domain after
the workspace is created.
example: nylas.com
name:
type: string
description: A short, descriptive name for the workspace.
example: The Nylas Workspace
policy_id:
type: string
description: |-
The ID of the [policy](/docs/v3/agent-accounts/policies-rules-lists/) to attach to the
workspace.
example: 6dcc5d92-8a55-4ce8-85a8-2f4275f8f0a0
rule_ids:
type: array
items:
type: string
description: |-
The IDs of any [rules](/docs/v3/agent-accounts/policies-rules-lists/#rules) to attach to
the workspace.
example:
- 3f2504e0-4f89-41d3-9a0c-0305e82c3301
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request POST \
--url "https://api.us.nylas.com/v3/workspaces" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "The Nylas Workspace",
"domain": "nylas.com",
"auto_group": true,
"policy_id": "<POLICY_ID>",
"rule_ids": ["<RULE_ID>"]
}'
responses:
'200':
description: Success. Returns new Workspace object.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/WorkspaceObject'
'400':
description: |-
Error: Bad request. For example, the request body was invalid, or a workspace already exists
for the application and domain.
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: 'Error: Not authenticated'
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: 'Error: Not found'
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/workspaces/{workspace_id}:
parameters:
- name: workspace_id
in: path
schema:
type: string
required: true
description: ID of the workspace to access.
example: 123e4567-e89b-12d3-a456-426614174000
get:
summary: Return a workspace
tags:
- Workspaces
operationId: get-workspace
description: Returns the specified workspace.
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
description: Success. Returns Workspace object.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/WorkspaceObject'
'401':
description: 'Error: Not authenticated'
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: 'Error: Not found'
content:
application/json:
schema:
$ref: '#/components/schemas/404'
patch:
summary: Update a workspace
tags:
- Workspaces
operationId: update-workspace
description: |-
Updates the specified workspace. You cannot change a workspace's `domain` after it's created.
On the application's default workspace, you can update only the `policy_id` and `rule_ids` values.
security:
- NYLAS_API_KEY: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
auto_group:
type: boolean
description: |-
When `true`, specifies that newly created grants in the application are automatically
assigned to the workspace if their email address' domain matches the `domain`.
example: true
name:
type: string
description: A short, descriptive name for the workspace.
example: The Nylas Workspace
policy_id:
type:
- string
- 'null'
description: |-
The ID of the [policy](/docs/v3/agent-accounts/policies-rules-lists/) to attach to the
workspace. Set a policy ID to attach the policy, set `null` to detach the current policy,
or omit the field to keep the current value. The policy must belong to your application.
example: 6dcc5d92-8a55-4ce8-85a8-2f4275f8f0a0
rule_ids:
type:
- array
- 'null'
items:
type: string
description: |-
The IDs of any [rules](/docs/v3/agent-accounts/policies-rules-lists/#rules) to attach to
the workspace. Set an array to replace the current rules, set `null` or an empty array to
detach all rules, or omit the field to keep the current value. Each rule must belong to
your application.
example:
- 3f2504e0-4f89-41d3-9a0c-0305e82c3301
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request PATCH \
--url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"policy_id": "<POLICY_ID>",
"rule_ids": ["<RULE_ID>"]
}'
responses:
'200':
description: Success. Returns updated Workspace object.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/WorkspaceObject'
'400':
description: |-
Error: Bad request. For example, the request tried to change the workspace's `domain`, modify a
value other than `policy_id` or `rule_ids` on the application's default workspace, or set a
`policy_id` or `rule_ids` value that doesn't belong to the application.
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: 'Error: Not authenticated'
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: 'Error: Not found'
content:
application/json:
schema:
$ref: '#/components/schemas/404'
delete:
summary: Delete a workspace
tags:
- Workspaces
operationId: delete-workspace
description: |-
Deletes the specified workspace. You can't delete the application's default workspace. The workspace's grants keep working and move to the default workspace, or become unassigned if there isn't one.
To learn what gets removed and when, see [Deleting resources and data](/docs/dev-guide/platform/deleting-resources/).
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
description: 'Error: Bad request. The workspace is the application''s default workspace, which can''t be deleted.'
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: 'Error: Not authenticated'
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: 'Error: Not found'
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/workspaces/auto-group:
post:
summary: Automatically group grants into workspace
tags:
- Workspaces
operationId: autogroup-workspace
description: |-
Configures automatic grouping settings for new or existing workspaces, depending on the filters
set. If you don't set any filters, Nylas considers all grants.
security:
- NYLAS_API_KEY: []
requestBody:
content:
application/json:
schema:
type: object
properties:
after_created_at:
type: number
description: |-
Applies automatic grouping settings to grants created at or after the specified time,
in seconds using the Unix timestamp format.
example: 1622548800
invalid_also:
type: boolean
description: |-
When `true`, applies automatic grouping settings to both invalid and valid grants. When
`false`, applies settings to valid grants only.
default: false
example: false
specific_domain:
type: string
description: Applies automatic grouping settings to grants with the specified email domain only.
example: nylas.com
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/workspaces/auto-group" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"after_created_at": 1725273600,
"invalid_also": true,
"specific_domain": "nylas.com"
}'
responses:
'200':
description: Success. Returns a information about automatic grouping job.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: object
properties:
job_id:
type: string
description: The ID of the automatic grouping job.
example: 52e61713-ab00-4d70-8974-73cf541c5db9
message:
type: string
description: Information about the background automatic grouping job.
example: Auto-grouping started successfully under JobID '52e61713-ab00-4d70-8974-73cf541c5db9', please wait for the process to complete. It may take some time.
'401':
description: 'Error: Not authenticated'
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: 'Error: Not found'
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/workspaces/{workspace_id}/manual-assign:
parameters:
- name: workspace_id
in: path
schema:
type: string
required: true
description: ID of the workspace to access.
example: 123e4567-e89b-12d3-a456-426614174000
post:
summary: Update workspace assignments
tags:
- Workspaces
operationId: manually-assign-workspace
description: |-
Manually assigns or removes specified grants to or from a specific workspace. You must specify at
least one grant ID in either `assign_grants` or `remove_grants`. You can include up to 500 grants
per list.
security:
- NYLAS_API_KEY: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
assign_grants:
type: array
items:
type: string
description: A list of grant IDs to be assigned to the workspace.
example:
- 123e4567-e89b-12d3-a456-426614174001
remove_grants:
type: array
items:
type: string
description: A list of grant IDs to be removed from the workspace.
example:
- 123e4567-e89b-12d3-a456-426614174001
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>/manual-assign" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"assign_grants": [
"10726e7c-89c3-4a1d-9f4a-5f3f37f6f2d9",
"3b9f5c1a-21d4-46c1-b84f-0e8d1f9eaa42"
],
"remove_grants": [
"5f1a2c9e-739b-4c66-9a3d-2c88a0c6d123",
"9c6e4b7d-2e4a-4ef0-a1b8-badf5a76a555"
]
}'
responses:
'200':
description: Success. Returns updated grant information.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: object
properties:
application_id:
type: string
description: The ID of the Nylas application associated with the workspace.
example: 123e4567-e89b-12d3-a456-426614174000
domain:
type: string
description: The top-level domain associated with the workspace.
example: nylas.com
grants_assigned:
type: array
items:
type: string
description: A list of grant IDs assigned to the workspace.
example:
- 123e4567-e89b-12d3-a456-426614174001
- 123e4567-e89b-12d3-a456-426614174003
grants_removed:
type: array
items:
type: string
description: A list of grant IDs removed from the workspace.
example:
- 123e4567-e89b-12d3-a456-426614174002
workspace_id:
type: string
description: The ID of the workspace that was updated.
example: 123e4567-e89b-12d3-a456-426614174000
'401':
description: 'Error: Not authenticated'
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: 'Error: Not found'
content:
application/json:
schema:
$ref: '#/components/schemas/404'
/v3/admin/applications/{application_id}/api-keys:
parameters:
- in: path
schema:
type: string
name: application_id
required: true
description: ID of the Nylas application to access.
- in: header
name: X-Nylas-Signature
schema:
type: string
required: true
description: |-
A Base64-encoded signature using your private key's RSA with a 2048-bit key and an SHA-256 hashed
string of the path, method, timestamp, nonce, and payload.
- in: header
name: X-Nylas-Kid
schema:
type: string
required: true
description: The `private_key_id` from your Service Account JSON file.
- in: header
name: X-Nylas-Nonce
schema:
type: string
required: true
description: |-
A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a
nonce, Nylas rejects the request.
- in: header
name: X-Nylas-Timestamp
schema:
type: number
required: true
description: |-
The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within
a 5-minute window of your real request time.
post:
summary: Create API key
tags:
- Manage API keys
operationId: create-api-key
x-beta: true
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage API Keys endpoints, you need to <a href="/docs/reference/api/manage-api-keys/">create a Nylas Service Account</a></b>.</div>
Creates an API key for the specified Nylas application.
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: A short, descriptive name for the API key.
example: example-key
expires_in:
type: number
description: How long the API key will be valid, in days.
example: 3600
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X POST "https://api.us.nylas.com/v3/admin/applications/<NYLAS_APPLICATION_ID>/api-keys" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1676412353123" \
-d '{
"name": "example-key",
"expires_in": 3600
}'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
type: object
properties:
api_key:
type: string
description: The API key.
example: <NYLAS_API_KEY>
application_id:
type: string
description: The application ID associated with the API key.
example: ad410018-d306-43f9-8361-fa5d7b2172e0
created_at:
type: number
description: When the API key was created, in seconds using the Unix timestamp format.
example: 1742932766
expires_at:
type: number
description: When the API key will expire, in seconds using the Unix timestamp format.
example: 1753300766
id:
type: string
description: The API key ID.
example: <NYLAS_API_KEY_ID>
name:
type: string
description: The name of the API key.
example: example-key
permissions:
type: array
description: The scopes assigned to the API key.
example:
- apikey.create
- apikey.get
- apikey.delete
status:
type: string
description: The status of the API key.
example: active
updated_at:
type: number
description: |-
When the API key was last updated, in seconds using the Unix timestamp format. For new API keys,
this value is the same as `created_at`.
example: 1742932766
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
get:
summary: Get all API keys
tags:
- Manage API keys
operationId: get-api-keys
x-beta: true
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage API Keys endpoints, you need to <a href="/docs/api/v3/admin/#tag--Manage-API-keys--nylas-service-account">create a Nylas Service Account</a></b>.</div>
Returns a list of API keys associated with the specified Nylas application.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X GET "https://api.us.nylas.com/v3/admin/applications/<NYLAS_APPLICATION_ID>/api-keys" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1676412353123"
responses:
'200':
$ref: '#/components/responses/get-api-keys-200'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/admin/applications/{application_id}/api-keys/{api_key_id}:
parameters:
- schema:
type: string
name: application_id
in: path
required: true
description: ID of the Nylas application to access.
- schema:
type: string
name: api_key_id
in: path
required: true
description: ID of the API key to access.
- in: header
name: X-Nylas-Signature
schema:
type: string
required: true
description: |-
A Base64-encoded signature using your private key's RSA with a 2048-bit key and an SHA-256 hashed
string of the path, method, timestamp, nonce, and payload.
- in: header
name: X-Nylas-Kid
schema:
type: string
required: true
description: The `private_key_id` from your Service Account JSON file.
- in: header
name: X-Nylas-Nonce
schema:
type: string
required: true
description: |-
A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a
nonce, Nylas rejects the request.
- in: header
name: X-Nylas-Timestamp
schema:
type: number
required: true
description: |-
The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within
a 5-minute window of your real request time.
get:
summary: Get API key
tags:
- Manage API keys
operationId: get-api-key
x-beta: true
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage API Keys endpoints, you need to <a href="/docs/api/v3/admin/#tag--Manage-API-keys--nylas-service-account">create a Nylas Service Account</a></b>.</div>
Returns the specified API key.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X GET "https://api.us.nylas.com/v3/admin/applications/<NYLAS_APPLICATION_ID>/api-keys/<API_KEY_ID>" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1676412353123"
responses:
'200':
$ref: '#/components/responses/get-api-key-200'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
delete:
summary: Delete API key
tags:
- Manage API keys
operationId: delete-api-key
x-beta: true
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage API Keys endpoints, you need to <a href="/docs/api/v3/admin/#tag--Manage-API-keys--nylas-service-account">create a Nylas Service Account</a></b>.</div>
Deletes the specified API key.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --location --globoff --request DELETE "https://api.us.nylas.com/v3/admin/applications/<NYLAS_APPLICATION_ID>/api-keys/<API_KEY_ID>" \
--header "Content-Type: application/json" \
--header "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
--header "X-Nylas-Nonce: <NONCE>" \
--header "X-Nylas-Timestamp: 1676412353123" \
--header "X-Nylas-Signature: <BASE64_SIGNATURE>"
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
examples:
OK:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/webhooks:
post:
tags:
- Webhook Notifications
summary: Create a webhook destination
operationId: post-webhook-destinations
description: |-
Creates a webhook destination with the specified URL and list of trigger types.
### Webhook destinations and retry logic
You should limit the number of webhook destinations you have for each trigger type. When Nylas
retries a webhook, the retry goes to all the destinations for that trigger type. This can result
in _a lot_ of notifications.
Some webhook testing tools rate-limit or block you if your endpoint generates too much traffic.
Nylas blocks Ngrok connections for this reason.
### Webhook notification header
Every webhook notification Nylas sends includes the `x-nylas-signature` header. If you're using
the Nylas SDKs, you might see `X-Nylas-Signature` instead.
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/create_200'
description: Returns the new Destination
'400':
$ref: '#/components/responses/create_400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/destination_input_payload'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/webhooks/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data-raw '{
"trigger_types": [
"grant.created",
"grant.deleted",
"grant.expired"
],
"description": "local",
"webhook_url": "<WEBHOOK_URL>",
"notification_email_addresses": [
"leyah@example.com",
"nyla@example.com"
]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas, { WebhookTriggers } from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const createWebhook = async () => {
try {
const webhook = await nylas.webhooks.create({
requestBody: {
triggerTypes: [WebhookTriggers.EventCreated],
webhookUrl: "<WEBHOOK_URL>",
description: "My first webhook",
notificationEmailAddresses: ["<EMAIL_ADDRESS>"],
},
});
console.log("Webhook created:", webhook);
} catch (error) {
console.error("Error creating webhook:", error);
}
};
createWebhook();
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.models.webhooks import WebhookTriggers
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
webhook = nylas.webhooks.create(
request_body={
"trigger_types": [WebhookTriggers.EVENT_CREATED],
"webhook_url": "<WEBHOOK_URL>",
"description": "My first webhook",
"notification_email_addresses": ["<EMAIL_ADDRESS>"],
}
)
print(webhook)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
request_body = {
trigger_types: [Nylas::WebhookTrigger::EVENT_CREATED],
webhook_url: "<WEBHOOK_URL>",
description: 'My first webhook',
notification_email_addresses: ["<EMAIL_ADDRESS>"]
}
begin
webhook, _request_id = nylas.webhooks.create(request_body: request_body)
puts "Webhook created: #{webhook}"
rescue Nylas::NylasApiError => e
puts "Error creating webhook: #{e.message}"
end
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class webhooks {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<WebhookTriggers> triggers = new ArrayList<>();
triggers.add(WebhookTriggers.EVENT_CREATED);
CreateWebhookRequest webhookRequest = new CreateWebhookRequest(
triggers,
"<WEBHOOK_URL>",
"My first webhook",
List.of("<EMAIL_ADDRESS>"));
try {
Response<WebhookWithSecret> webhook = nylas.webhooks().create(webhookRequest);
System.out.println(webhook.getData());
} catch (Exception e) {
System.out.println("Error: " + e);
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>){
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val triggersList: List<WebhookTriggers> = listOf(WebhookTriggers.EVENT_CREATED)
val webhookRequest: CreateWebhookRequest = CreateWebhookRequest(
triggersList,
"<WEBHOOK_URL>",
"My first webhook",
listOf("<EMAIL_ADDRESS>"))
try {
val webhook: Response<WebhookWithSecret> = nylas.webhooks().create(webhookRequest)
println(webhook.data)
} catch(exception : Exception) {
println("Error :$exception")
}
}
get:
tags:
- Webhook Notifications
summary: Get destinations for an application
operationId: get-webhook-destinations-application
description: Get a list of all webhook destinations for an application id.
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/get_200'
description: List of destinations for an application.
'400':
$ref: '#/components/responses/get_400'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/webhooks' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const listWebhooks = async () => {
try {
const webhooks = await nylas.webhooks.list({});
console.log("webhooks:", webhooks);
} catch (error) {
console.error("Error fetching webhooks:", error);
}
};
listWebhooks();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
webhooks = nylas.webhooks.list()
print("webhooks:", webhooks)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
webhooks = nylas.webhooks.list()
puts webhooks
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class webhooks {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Webhook> webhooks = nylas.webhooks().list();
System.out.println(webhooks.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>){
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val webhooks = nylas.webhooks().list()
println(webhooks.data)
}
/v3/webhooks/{id}:
get:
operationId: get-webhook-by-id
tags:
- Webhook Notifications
summary: Get the destinations for an application by webhook ID
description: Get the webhook destinations for an application ID by webhook ID
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
$ref: '#/components/responses/get_by_id_200'
description: The destinations matching the query
'400':
$ref: '#/components/responses/get_400'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchWebhookById() {
try {
const webhook = await nylas.webhooks.find({
webhookId: "<WEBHOOK_ID>",
});
console.log("webhook:", webhook);
} catch (error) {
console.error("Error fetching webhook:", error);
}
}
fetchWebhookById();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
message = nylas.webhooks.find(
"<WEBHOOK_ID>",
)
print(message)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
webhook = nylas.webhooks.find(webhook_id: "<WEBHOOK_ID>")
puts webhook
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class webhooks {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Webhook> webhook = nylas.webhooks().find("<WEBHOOK_ID>");
System.out.println(webhook.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>){
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val webhooks = nylas.webhooks().find("<WEBHOOK_ID>")
println(webhooks.data)
}
put:
operationId: put-webhook-by-id
tags:
- Webhook Notifications
summary: Update a webhook destination
description: |-
Update the values in a specific webhook destination.
### Limitations
- You only need to specify fields that need to change when you make a request to this endpoint.
Empty fields in the request do not overwrite existing fields.
- You should limit how many webhook destinations you have for each trigger type. When Nylas retries
a webhook, the retry goes to _all destinations for the specific trigger type_. This can result in
a lot of notifications.
- Some webhook testing tools rate-limit or block you if your webhook destination endpoint generates
too much traffic. Nylas blocks Ngrok connections for this reason.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
$ref: '#/components/responses/update_200'
'400':
$ref: '#/components/responses/update_400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/destination_update_payload'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PUT \
--url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"notification_email_addresses": ["leyah@example.com"]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateWebhook() {
try {
const webhook = await nylas.webhooks.update({
webhookId: "<WEBHOOK_ID>",
requestBody: {
notificationEmailAddresses: ["<EMAIL_ADDRESS>"],
},
});
console.log("Updated Webhook:", webhook);
} catch (error) {
console.error("Error updating webhook:", error);
}
}
updateWebhook();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
webhook = nylas.webhooks.update(
"<WEBHOOK_ID>",
request_body={
"notification_email_addresses": ["<EMAIL_ADDRESS>"],
}
)
print(webhook)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
description: 'My updated webhook'
}
webhooks = nylas.webhooks.update(webhook_id: "<WEBHOOK_ID>",
request_body: request_body)
puts webhooks
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class webhooks {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateWebhookRequest webhookRequest = new
UpdateWebhookRequest.Builder().
description("My updated webhook").
build();
Response<Webhook> webhook = nylas.webhooks().update("<WEBHOOK_ID>",
webhookRequest);
System.out.println(webhook.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.UpdateWebhookRequest
fun main(args: Array<String>){
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val webhookRequest : UpdateWebhookRequest =
UpdateWebhookRequest.Builder().
description("My updated webhook").
build()
val webhooks = nylas.webhooks().update("<WEBHOOK_ID>",
webhookRequest)
println(webhooks.data)
}
delete:
operationId: delete-webhook-by-id
tags:
- Webhook Notifications
summary: Delete a webhook destination
description: Delete a webhook destination record.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
$ref: '#/components/responses/delete_200'
description: Returns a success message.
'400':
$ref: '#/components/responses/delete_400'
description: Returns an error message.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const deleteWebhook = async () => {
try {
await nylas.webhooks.destroy({ webhookId: "<WEBHOOK_ID>" });
console.log("Webhook deleted successfully.");
} catch (error) {
console.error("Error deleting webhook:", error);
}
};
deleteWebhook();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
request = nylas.webhooks.destroy(
"<WEBHOOK_ID>",
)
print(request)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
status = nylas.webhooks.destroy(webhook_id: "<WEBHOOK_ID>")
puts status
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class webhooks {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
WebhookDeleteResponse deleteResponse =
nylas.webhooks().destroy("<WEBHOOK_ID>");
System.out.println(deleteResponse);
}
}
- lang: kotlin
label: Kotllin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>){
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val webhooks = nylas.webhooks().destroy("<WEBHOOK_ID>")
println(webhooks.data)
}
/v3/webhooks/rotate-secret/{id}:
post:
operationId: post-new-secret
tags:
- Webhook Notifications
summary: Rotate a webhook secret
description: |-
Update the webhook secret value for a destination. The previous value will immediately stop being used and the new value will take over.
### Webhook notification header
Every webhook notification Nylas sends includes the `x-nylas-signature` header. Depending on the SDK you're using, you might see `X-Nylas-Signature` instead.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/webhooks/rotate-secret/<WEBHOOK_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const rotated = await nylas.webhooks.rotateSecret({
webhookId: "<WEBHOOK_ID>",
});
console.log("Rotated webhook secret:", rotated);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
webhook = nylas.webhooks.rotate_secret(
"<WEBHOOK_ID>"
)
print(webhook)
- lang: ruby
label: Ruby SDK
source: |
# frozen_string_literal: true
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: '<NYLAS_API_KEY>'
)
secret, _ = nylas.webhooks.rotate_secret(webhook_id: "<WEBHOOK_ID>")
puts secret
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.List;
public class read_grants {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<WebhookWithSecret> secret = nylas.webhooks().rotateSecret("<WEBHOOK_ID>");
System.out.println(secret);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.UpdateGrantRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val secret = nylas.webhooks().rotateSecret("<WEBHOOK_ID>")
print(secret)
}
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
schema:
type: string
required: true
responses:
'200':
$ref: '#/components/responses/rotate_secret_200'
description: Returns the updated Destination.
'400':
$ref: '#/components/responses/delete_400'
/v3/webhooks/mock-payload:
post:
operationId: get_mock_webhook_payload
tags:
- Webhook Notifications
- Pub/Sub Notifications
summary: Get mock notification payload
description: |-
Use this endpoint to see example notification payloads for the different Nylas events you specify,
to the webhook URL you specify.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/webhooks/mock-payload' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"trigger_type": "calendar.created",
"webhook_url": "<WEBHOOK_URL>"
}'
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/get_mock_payload_200'
description: Returns the mock payload for corresponding trigger type.
'400':
$ref: '#/components/responses/400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/get_mock_payload_input'
/v3/webhooks/send-test-event:
post:
operationId: send_test_event
tags:
- Webhook Notifications
summary: Send test event
description: |-
Use this endpoint to check if your project's webhook destination is configured correctly. Nylas
sends a test webhook payload to the webhook URL you specify, and listens for a success
acknowledgement.
The secret used is `mock-webhook-secret`.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/webhooks/send-test-event' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"trigger_type": "calendar.created",
"webhook_url": "<WEBHOOK_URL>"
}'
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/send_test_event_200'
description: Returns the mock payload for corresponding trigger type.
'400':
$ref: '#/components/responses/400'
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/send_test_event_input'
/v3/channels/pubsub:
post:
summary: Create a Pub/Sub channel
tags:
- Pub/Sub Notifications
operationId: create-pubsub-channel
description: |
Create a Pub/Sub channel in the specified application.
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/create_pubsub_200'
description: Returns the new Destination
'400':
$ref: '#/components/responses/create_pubsub_400'
description: Returns the new Destination
requestBody:
required: true
description: Destination definition
content:
application/json:
schema:
$ref: '#/components/schemas/pubsub_input_payload'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/channels/pubsub' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data-raw '{
"description": "PubSub Test",
"trigger_types": ["message.send_success"],
"encryption_key": "",
"topic": "projects/<YOUR_PROJECT_ID>/topics/<YOUR_TOPIC_ID>",
"notification_email_addresses": ["leyah@example.com"]
}'
get:
summary: Get Pub/Sub channels for an application
tags:
- Pub/Sub Notifications
operationId: get-pubsub-channels
description: |
Get the Pub/Sub channels for an application.
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/get_pubsub_200'
description: List of destinations for an application.
'400':
$ref: '#/components/responses/get_pubsub_400'
description: List of destinations for an application.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/channels/pubsub/' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
/v3/channels/pubsub/{id}:
get:
operationId: get-pubsub-by-id
tags:
- Pub/Sub Notifications
summary: Get a specific Pub/Sub channel
description: Get a specific Pub/Sub channel from a specific Nylas application.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Pub/Sub channel to retrieve.
required: true
schema:
type: string
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
responses:
'200':
$ref: '#/components/responses/get_pubsub_by_id_200'
description: The destinations matching the query
'400':
$ref: '#/components/responses/get_pubsub_400'
put:
operationId: put-pubsub-by-id
tags:
- Pub/Sub Notifications
summary: Update a Pub/Sub channel
description: |-
Updates the specified Pub/Sub channel.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Pub/Sub channel to retrieve.
required: true
schema:
type: string
requestBody:
required: true
description: The Pub/Sub channel properties to update.
content:
application/json:
schema:
type: object
properties:
description:
type: string
description: A human-readable description of the Pub/Sub channel.
example: Prod account status notifications PubSub
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The new status of the channel. Use this to restart a channel that you manually paused, or that was automatically paused due to deliverability issues.
enum:
- active
- pause
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if there are errors or deliverability problems. See the [rate limit documentation](/docs/dev-guide/best-practices/rate-limits/) for details.
example:
- sysadmin@example.com
- sre_pager@example.com
compressed_delivery:
type: boolean
description: 'If `true`, Nylas compresses notification payloads using gzip before delivering them. Nylas adds a `content_encoding: gzip` message attribute to the Pub/Sub message.'
example: true
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PUT \
--url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data-raw '{
"description": "PubSub Update Test",
"trigger_types": ["message.updated"],
"encryption_key": "",
"topic": "projects/<YOUR_PROJECT_NAME>/topics/<YOUR_TOPIC_NAME>",
"notification_email_addresses": ["leyah@example.com"]
}'
responses:
'200':
$ref: '#/components/responses/update_pubsub_200'
'400':
$ref: '#/components/responses/update_pubsub_400'
delete:
operationId: delete-pubsub-by-id
tags:
- Pub/Sub Notifications
summary: Delete a specific Pub/Sub channel
description: Delete a specific Pub/Sub channel from a specific Nylas application.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Pub/Sub channel to retrieve.
required: true
schema:
type: string
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
responses:
'200':
$ref: '#/components/responses/delete_200'
description: Returns a success message.
'400':
$ref: '#/components/responses/delete_400'
description: Returns an error message.
/v3/channels/sns:
post:
summary: Create an Amazon SNS channel
tags:
- Amazon SNS Notifications
operationId: create-sns-channel
description: |
Create an Amazon SNS notification channel in the specified application.
The `topic` must be a valid Amazon SNS topic ARN (starting with `arn:aws:sns:`).
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/create_sns_200'
description: Returns the new Amazon SNS channel.
'400':
$ref: '#/components/responses/create_sns_400'
description: Returns an error.
requestBody:
required: true
description: Amazon SNS channel definition
content:
application/json:
schema:
$ref: '#/components/schemas/amazon_sns_input_payload'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/channels/sns' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data-raw '{
"description": "SNS Test",
"trigger_types": ["message.send_success"],
"topic": "arn:aws:sns:us-east-1:123456789012:my-topic",
"role_arn": "arn:aws:iam::123456789012:role/nylas-sns-role",
"notification_email_addresses": ["leyah@example.com"]
}'
get:
summary: Get Amazon SNS channels for an application
tags:
- Amazon SNS Notifications
operationId: get-sns-channels
description: |
Get the Amazon SNS notification channels for an application.
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/get_sns_200'
description: List of Amazon SNS channels for an application.
'400':
$ref: '#/components/responses/get_sns_400'
description: Returns an error.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/channels/sns/' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
/v3/channels/sns/{id}:
get:
operationId: get-sns-by-id
tags:
- Amazon SNS Notifications
summary: Get a specific Amazon SNS channel
description: Get a specific Amazon SNS notification channel from a specific Nylas application.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Amazon SNS channel to retrieve.
required: true
schema:
type: string
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/channels/sns/<SNS_CHANNEL_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
responses:
'200':
$ref: '#/components/responses/get_sns_by_id_200'
description: The Amazon SNS channel matching the query.
'400':
$ref: '#/components/responses/get_sns_400'
put:
operationId: put-sns-by-id
tags:
- Amazon SNS Notifications
summary: Update an Amazon SNS channel
description: |-
Updates the specified Amazon SNS notification channel.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Amazon SNS channel to update.
required: true
schema:
type: string
requestBody:
required: true
description: The Amazon SNS channel properties to update.
content:
application/json:
schema:
type: object
properties:
description:
type: string
description: A human-readable description of the Amazon SNS channel.
example: Prod account status notifications SNS
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Amazon SNS topic ARN that Nylas sends notifications to. Must start with `arn:aws:sns:`.
example: arn:aws:sns:us-east-1:123456789012:my-topic
role_arn:
type: string
description: The ARN of the IAM role that Nylas assumes to publish messages to the SNS topic.
example: arn:aws:iam::123456789012:role/nylas-sns-role
status:
type: string
description: The new status of the channel. Use this to restart a channel that you manually paused, or that was automatically paused due to deliverability issues.
enum:
- active
- pause
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if there are errors or deliverability problems. See the [rate limit documentation](/docs/dev-guide/best-practices/rate-limits/) for details.
example:
- sysadmin@example.com
- sre_pager@example.com
compressed_delivery:
type: boolean
description: 'If `true`, Nylas gzip-compresses and then base64-encodes notification payloads before delivering them. Nylas adds a `content_encoding: gzip+base64` message attribute to the SNS message. To decode, base64-decode the message body, then gzip-decompress.'
example: true
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PUT \
--url 'https://api.us.nylas.com/v3/channels/sns/<SNS_CHANNEL_ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data-raw '{
"description": "Updated SNS channel",
"trigger_types": ["event.created", "event.updated"],
"topic": "arn:aws:sns:us-east-1:123456789012:my-updated-topic",
"notification_email_addresses": ["sysadmin@example.com"]
}'
responses:
'200':
$ref: '#/components/responses/update_sns_200'
'400':
$ref: '#/components/responses/update_sns_400'
delete:
operationId: delete-sns-by-id
tags:
- Amazon SNS Notifications
summary: Delete a specific Amazon SNS channel
description: Delete a specific Amazon SNS notification channel from a specific Nylas application.
security:
- NYLAS_API_KEY: []
parameters:
- name: id
in: path
description: The ID of the Amazon SNS channel to delete.
required: true
schema:
type: string
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/channels/sns/<SNS_CHANNEL_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
responses:
'200':
$ref: '#/components/responses/delete_200'
description: Returns a success message.
'400':
$ref: '#/components/responses/delete_400'
description: Returns an error message.
/v3/connectors/{provider}/creds:
post:
operationId: create_credential
tags:
- Connector credentials
summary: Create a credential
description: Manually create a credential record.
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/provider'
requestBody:
required: true
description: ''
content:
application/json:
schema:
oneOf:
- type: object
title: Connector Override
description: Override the default connector with another auth app.
required:
- name
- credential_type
- credential_data
properties:
name:
type: string
description: The name of the credential. Must be unique.
example: Google auth app \#2 multitenant
credential_type:
type: string
description: The type of the credential. Set this value to `connector` if you have multiple provider auth applications for a single provider and need to create an override credential. </br></br> For example, if you have two Google provider auth apps, the Google connector for each application can only connect to one of those Google auth apps by default. You can set up a connector override credential, however, then specify that credential ID in authentication requests so that the request goes through the Google connector, but goes to the non-default Google auth app.
example: connector
credential_data:
type: object
description: |-
An object that contains special information that must be included in the credential.
This information is securely encrypted and stored, and isn't visible to users.
You must include data such as the `client_id` and `client_secret` for the provider
auth application.
example:
client_id: 3805ABCD1234-ABCD1234uv02m.apps.googleusercontent.com
client_secret: Ilg....01pe8db
- type: object
title: Service Account
description: Service account credential for Google App Permission.
required:
- name
- credential_type
- credential_data
properties:
name:
type: string
description: The name of the credential. Must be unique.
example: My first Google credential
credential_type:
type: string
description: The type of the credential. For the App Permission flow (currently supported for [Google App Permission](/docs/v3/auth/bulk-auth-grants/#google-app-permission-via-nylas) only), the type must be `serviceaccount`.
example: serviceaccount
credential_data:
type: object
description: An object that specifies some special information required for the credential. This information is securely encoded and stored, and is _not_ visible to end users. </br></br> For the [Google App Permission flow](/docs/v3/auth/bulk-auth-grants/#google-app-permission-via-nylas), this field must contain the `private_key_id`, `private_key`, and `client_email`.
example:
type: service_account
project_id: marketplace-sa-test
private_key_id: abcd1234defg5678
private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
client_email: some-name@marketplace-sa-test.iam.gserviceaccount.com
client_id: '123456789'
auth_uri: https://accounts.google.com/o/oauth2/auth
token_uri: https://oauth2.googleapis.com/token
auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/some-name%40marketplace-sa-test.iam.gserviceaccount.com
- type: object
title: Admin Consent
description: Admin consent credential for Microsoft bulk auth.
required:
- name
- credential_type
- credential_data
properties:
name:
type: string
description: The name of the credential. Must be unique.
example: My Microsoft Admin Consent credential
credential_type:
type: string
description: The type of the credential. For the [Microsoft Admin Consent flow](/docs/v3/auth/bulk-auth-grants/#use-a-microsoft-bulk-authentication-grant), the type must be `adminconsent`.
example: adminconsent
credential_data:
type: object
description: |-
An object that specifies some special information required for the credential.
This information is securely encoded and stored, and isn't visible to users.
For the Microsoft Admin Consent 2.0 flow, this field must contain the `tenant`
(either yours or the user's). If you don't specify the Azure `client_id` and
`client_secret` Nylas uses the information from your Nylas application's
Microsoft connector.
example:
client_id: 2f70ABCD-1234-ABCD-1234-ABCD0316be16
client_secret: yhg7.....6BoK4j
tenant: 2f70ABCD-5678-DEFG-5678-ABCD0316be16
responses:
'201':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/CredentialObject'
description: The credential is created.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"name": "CONNECTOR",
"credential_type": "connector",
"credential_data": {
"client_id": "<CLIENT_ID>", // PROVIDER_CLIENT_ID or NYLAS_CLIENT_ID, depending on credential type.
"client_secret": "<CLIENT_SECRET>" // PROVIDER_CLIENT_SECRET or NYLAS_CLIENT_SECRET, depending on credential type.
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas, { CredentialType } from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const credential = await nylas.connectors.credentials.create({
provider: "google",
requestBody: {
name: "Google connector override",
credentialType: CredentialType.CONNECTOR,
credentialData: {
client_id: "<CLIENT_ID>",
client_secret: "<CLIENT_SECRET>",
},
},
});
console.log("Credential created:", credential);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
credential = nylas.connectors.credentials.create(
provider="google",
request_body={
"name": "Google connector override",
"credential_type": "connector",
"credential_data": {
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
},
},
)
print("Created credential:", credential)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.AuthProvider;
import com.nylas.models.Credential;
import com.nylas.models.CreateCredentialRequest;
import com.nylas.models.CredentialData;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class CreateCredential {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CredentialData.ConnectorOverride credentialData = new CredentialData.ConnectorOverride(
"<CLIENT_ID>", "<CLIENT_SECRET>", null);
CreateCredentialRequest requestBody = new CreateCredentialRequest.Connector(
"Google connector override", credentialData);
Response<Credential> credential = nylas.connectors().credentials()
.create(AuthProvider.GOOGLE, requestBody);
System.out.println("Credential created: " + credential.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AuthProvider
import com.nylas.models.CreateCredentialRequest
import com.nylas.models.CredentialData
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val credentialData = CredentialData.ConnectorOverride(
clientId = "<CLIENT_ID>",
clientSecret = "<CLIENT_SECRET>")
val requestBody = CreateCredentialRequest.Connector(
name = "Google connector override",
credentialData = credentialData)
val credential = nylas.connectors().credentials().create(AuthProvider.GOOGLE, requestBody)
println("Credential created: ${credential.data}")
}
get:
operationId: get_credential_all
tags:
- Connector credentials
summary: List credentials
description: List credentials for the specified provider.
security:
- NYLAS_API_KEY: []
parameters:
- in: query
name: limit
description: Limit the number of credentials Nylas returns.
schema:
type: integer
default: 10
- in: query
name: offset
description: Offset the results.
schema:
default: 0
type: integer
- in: query
name: sort_by
description: Sort the returned credentials using the contents of the specified field.
schema:
type: string
default: created_at
enum:
- created_at
- updated_at
- in: query
name: order_by
description: Specify the sort order of returned credentials.
schema:
type: string
default: desc
enum:
- desc
- asc
- $ref: '#/components/parameters/provider'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: array
items:
$ref: '#/components/schemas/CredentialObject'
limit:
type: integer
example: 10
offset:
type: integer
example: 0
description: Returns an array of Credential objects.
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const credentials = await nylas.connectors.credentials.list({
provider: "google",
});
console.log("Credentials:", credentials);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
credentials = nylas.connectors.credentials.list(
provider="google",
query_params={
"limit": 50,
},
)
print("Credentials:", credentials)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.AuthProvider;
import com.nylas.models.Credential;
import com.nylas.models.ListResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class ListCredentials {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Credential> credentials = nylas.connectors().credentials().list(AuthProvider.GOOGLE);
System.out.println("Credentials: " + credentials.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AuthProvider
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val credentials = nylas.connectors().credentials().list(AuthProvider.GOOGLE)
println("Credentials: ${credentials.data}")
}
/v3/connectors/{provider}/creds/{id}:
get:
operationId: get_credential_by_id
tags:
- Connector credentials
summary: Get credential
description: Return a credential with the specified ID.
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/provider'
- $ref: '#/components/parameters/id'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/CredentialObject'
description: Returns the credential with the specified ID.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds/<CREDENTIAL_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const credential = await nylas.connectors.credentials.find({
provider: "google",
credentialsId: "<CREDENTIAL_ID>",
});
console.log("Credential:", credential);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
credential = nylas.connectors.credentials.find(
provider="google",
credential_id="<CREDENTIAL_ID>",
)
print("Credential:", credential)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.AuthProvider;
import com.nylas.models.Credential;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class FindCredential {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Credential> credential = nylas.connectors().credentials()
.find(AuthProvider.GOOGLE, "<CREDENTIAL_ID>");
System.out.println("Credential: " + credential.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AuthProvider
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val credential = nylas.connectors().credentials().find(AuthProvider.GOOGLE, "<CREDENTIAL_ID>")
println("Credential: ${credential.data}")
}
patch:
operationId: patch_credential_by_id
tags:
- Connector credentials
summary: Update a connector credential
description: |-
Updates the specified connector credential.
When you make a `PATCH` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/provider'
- $ref: '#/components/parameters/id'
requestBody:
required: true
description: ''
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The credential name.
example: My first Google credential
credential_data:
description: |-
An object that specifies some special information required for the credential.
This information is securely encoded and stored, and is _not_ visible to users.
For the
[Google App Permission flow](/docs/v3/auth/bulk-auth-grants/#google-app-permission-via-nylas),
this field must contain the `private_key_id`, `private_key`, and `client_email`.
For the
[Microsoft App Permission flow](/docs/v3/auth/bulk-auth-grants/#use-a-microsoft-bulk-authentication-grant),
this field must contain the Azure `client_id` and `client_secret`.
To use the credential to override a connector, this field must contain the `client_id`
and `client_secret`.
example:
type: service_account
project_id: marketplace-sa-test
private_key_id: abcd1234defg5678
private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
client_email: some-name@marketplace-sa-test.iam.gserviceaccount.com
client_id: '123456789'
auth_uri: https://accounts.google.com/o/oauth2/auth
token_uri: https://oauth2.googleapis.com/token
auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/some-name%40marketplace-sa-test.iam.gserviceaccount.com
type: object
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/CredentialObject'
description: Returns the updated credential.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PATCH \
--url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds/<CREDENTIAL_ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"name": "google",
"credential_data": {
"client_id": "<PROVIDER_CLIENT_ID>",
"client_secret": "<PROVIDER_CLIENT_SECRET>"
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const updated = await nylas.connectors.credentials.update({
provider: "google",
credentialsId: "<CREDENTIAL_ID>",
requestBody: {
name: "google",
credentialData: {
client_id: "<PROVIDER_CLIENT_ID>",
client_secret: "<PROVIDER_CLIENT_SECRET>",
},
},
});
console.log("Credential updated:", updated);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
credential = nylas.connectors.credentials.update(
provider="google",
credential_id="<CREDENTIAL_ID>",
request_body={
"name": "Updated connector override",
},
)
print("Updated credential:", credential)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.AuthProvider;
import com.nylas.models.Credential;
import com.nylas.models.CredentialData;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
import com.nylas.models.UpdateCredentialRequest;
public class UpdateCredential {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CredentialData.ConnectorOverride credentialData = new CredentialData.ConnectorOverride(
"<PROVIDER_CLIENT_ID>", "<PROVIDER_CLIENT_SECRET>", null);
UpdateCredentialRequest requestBody = new UpdateCredentialRequest.Builder()
.name("google")
.credentialData(credentialData)
.build();
Response<Credential> updated = nylas.connectors().credentials()
.update(AuthProvider.GOOGLE, "<CREDENTIAL_ID>", requestBody);
System.out.println("Credential updated: " + updated.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AuthProvider
import com.nylas.models.CredentialData
import com.nylas.models.UpdateCredentialRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val credentialData = CredentialData.ConnectorOverride(
clientId = "<PROVIDER_CLIENT_ID>",
clientSecret = "<PROVIDER_CLIENT_SECRET>")
val requestBody = UpdateCredentialRequest.Builder()
.name("google")
.credentialData(credentialData)
.build()
val updated = nylas.connectors().credentials()
.update(AuthProvider.GOOGLE, "<CREDENTIAL_ID>", requestBody)
println("Credential updated: ${updated.data}")
}
delete:
operationId: delete_credential_by_id
tags:
- Connector credentials
summary: Delete credential
description: |-
Deletes the credential with the specified ID. You can't delete a connector's default (active) credential, only a non-default one. Any grants that use the deleted credential stop working right away.
To learn what gets removed and when, see [Deleting resources and data](/docs/dev-guide/platform/deleting-resources/).
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/provider'
- $ref: '#/components/parameters/id'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
description: The credential is deleted from the database.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds/<CREDENTIAL_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const result = await nylas.connectors.credentials.destroy({
provider: "google",
credentialsId: "<CREDENTIAL_ID>",
});
console.log("Deleted:", result);
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.connectors.credentials.destroy(
provider="google",
credential_id="<CREDENTIAL_ID>",
)
print("Credential deleted:", response)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.AuthProvider;
import com.nylas.models.DeleteResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class DeleteCredential {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse result = nylas.connectors().credentials()
.destroy(AuthProvider.GOOGLE, "<CREDENTIAL_ID>");
System.out.println("Deleted: " + result);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.AuthProvider
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val result = nylas.connectors().credentials().destroy(AuthProvider.GOOGLE, "<CREDENTIAL_ID>")
println("Deleted: $result")
}
/v3/admin/domains:
parameters:
- in: header
name: X-Nylas-Signature
schema:
type: string
required: true
description: |-
A Base64-encoded signature using your private key's RSA with a 2048-bit key and an SHA-256 hashed
string of the path, method, timestamp, nonce, and payload.
- in: header
name: X-Nylas-Kid
schema:
type: string
required: true
description: The `private_key_id` from your Service Account JSON file.
- in: header
name: X-Nylas-Nonce
schema:
type: string
required: true
description: |-
A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a
nonce, Nylas rejects the request.
- in: header
name: X-Nylas-Timestamp
schema:
type: number
required: true
description: |-
The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within
a 5-minute window of your real request time.
post:
summary: Create domain
tags:
- Manage Domains
operationId: create-domain
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a href="/docs/v3/auth/nylas-service-account/">Nylas Service Account</a></b>.</div>
Registers a new email domain for your organization. After creating a domain, you must
[verify its DNS records](/docs/v3/email/domains/) before you can use it with Transactional Send or Nylas Agent Accounts.
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- domain_address
properties:
name:
type: string
description: A human-readable label for the domain.
example: My transactional domain
domain_address:
type: string
description: The domain address to register (for example, `mail.example.com`).
example: mail.example.com
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X POST "https://api.us.nylas.com/v3/admin/domains" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766" \
-d '{
"name": "My transactional domain",
"domain_address": "mail.example.com"
}'
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.handler.service_account import ServiceAccountSigner
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
signer = ServiceAccountSigner(
private_key_pem="<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>",
private_key_id="<SERVICE_ACCOUNT_ID>",
)
domain = nylas.domains.create(
request_body={
"name": "My transactional domain",
"domain_address": "mail.example.com",
},
signer=signer,
)
print(domain)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/DomainObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
get:
summary: List domains
tags:
- Manage Domains
operationId: list-domains
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a href="/docs/v3/auth/nylas-service-account/">Nylas Service Account</a></b>.</div>
Returns a list of all domains registered to your organization.
parameters:
- $ref: '#/components/parameters/limit'
- name: page_token
in: query
required: false
schema:
type: string
description: A token to fetch the next page of results. Use the `next_cursor` value from the previous response.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X GET "https://api.us.nylas.com/v3/admin/domains" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766"
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.handler.service_account import ServiceAccountSigner
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
signer = ServiceAccountSigner(
private_key_pem="<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>",
private_key_id="<SERVICE_ACCOUNT_ID>",
)
domains = nylas.domains.list(signer=signer)
print(domains)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
type: array
items:
$ref: '#/components/schemas/DomainObject'
next_cursor:
type: string
description: A token to use for paginating through results. If present, pass this value as `page_token` in the next request.
example: eyJhbGciOiJIUzI1NiJ9
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/admin/domains/{domain_id}:
parameters:
- schema:
type: string
name: domain_id
in: path
required: true
description: ID of the domain to access.
- in: header
name: X-Nylas-Signature
schema:
type: string
required: true
description: |-
A Base64-encoded signature using your private key's RSA with a 2048-bit key and an SHA-256 hashed
string of the path, method, timestamp, nonce, and payload.
- in: header
name: X-Nylas-Kid
schema:
type: string
required: true
description: The `private_key_id` from your Service Account JSON file.
- in: header
name: X-Nylas-Nonce
schema:
type: string
required: true
description: |-
A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a
nonce, Nylas rejects the request.
- in: header
name: X-Nylas-Timestamp
schema:
type: number
required: true
description: |-
The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within
a 5-minute window of your real request time.
get:
summary: Get domain
tags:
- Manage Domains
operationId: get-domain
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a href="/docs/v3/auth/nylas-service-account/">Nylas Service Account</a></b>.</div>
Returns the specified domain.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X GET "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766"
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.handler.service_account import ServiceAccountSigner
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
signer = ServiceAccountSigner(
private_key_pem="<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>",
private_key_id="<SERVICE_ACCOUNT_ID>",
)
domain = nylas.domains.find(
domain_id="<DOMAIN_ID>",
signer=signer,
)
print(domain)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/DomainObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
put:
summary: Update domain
tags:
- Manage Domains
operationId: update-domain
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a href="/docs/v3/auth/nylas-service-account/">Nylas Service Account</a></b>.</div>
Updates the specified domain. Currently, only the `name` field can be updated.
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: A human-readable label for the domain.
example: Updated domain name
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X PUT "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766" \
-d '{
"name": "Updated domain name"
}'
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.handler.service_account import ServiceAccountSigner
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
signer = ServiceAccountSigner(
private_key_pem="<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>",
private_key_id="<SERVICE_ACCOUNT_ID>",
)
domain = nylas.domains.update(
domain_id="<DOMAIN_ID>",
request_body={
"name": "Updated domain name",
},
signer=signer,
)
print(domain)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/DomainObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
delete:
summary: Delete domain
tags:
- Manage Domains
operationId: delete-domain
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a href="/docs/v3/auth/nylas-service-account/">Nylas Service Account</a></b>.</div>
Deletes the specified domain. This action is irreversible.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X DELETE "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766"
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.handler.service_account import ServiceAccountSigner
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
signer = ServiceAccountSigner(
private_key_pem="<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>",
private_key_id="<SERVICE_ACCOUNT_ID>",
)
response = nylas.domains.destroy(
domain_id="<DOMAIN_ID>",
signer=signer,
)
print(response)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
examples:
OK:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/admin/domains/{domain_id}/info:
parameters:
- schema:
type: string
name: domain_id
in: path
required: true
description: ID of the domain to get DNS info for.
- in: header
name: X-Nylas-Signature
schema:
type: string
required: true
description: |-
A Base64-encoded signature using your private key's RSA with a 2048-bit key and an SHA-256 hashed
string of the path, method, timestamp, nonce, and payload.
- in: header
name: X-Nylas-Kid
schema:
type: string
required: true
description: The `private_key_id` from your Service Account JSON file.
- in: header
name: X-Nylas-Nonce
schema:
type: string
required: true
description: |-
A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a
nonce, Nylas rejects the request.
- in: header
name: X-Nylas-Timestamp
schema:
type: number
required: true
description: |-
The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within
a 5-minute window of your real request time.
post:
summary: Get domain info
tags:
- Manage Domains
operationId: get-domain-info
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a href="/docs/v3/auth/nylas-service-account/">Nylas Service Account</a></b>.</div>
Returns the DNS record information and verification status for the specified verification type.
Use this endpoint to retrieve the DNS records you need to add at your DNS provider before
calling the [Verify domain](/docs/reference/api/manage-domains/verify-domain/) endpoint.
requestBody:
content:
application/json:
schema:
type: object
required:
- type
properties:
type:
type: string
description: The type of DNS verification to get info for.
enum:
- ownership
- mx
- spf
- dkim
- feedback
example: ownership
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X POST "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>/info" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766" \
-d '{
"type": "ownership"
}'
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.handler.service_account import ServiceAccountSigner
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
signer = ServiceAccountSigner(
private_key_pem="<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>",
private_key_id="<SERVICE_ACCOUNT_ID>",
)
info = nylas.domains.get_info(
domain_id="<DOMAIN_ID>",
request_body={
"type": "ownership",
},
signer=signer,
)
print(info)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
type: object
properties:
domain_id:
type: string
description: The ID of the domain.
example: abc-123-domain-id
attempt:
type: object
description: Details about the DNS records required for this verification type.
properties:
type:
type: string
description: The type of DNS verification.
example: ownership
options:
type: object
description: The DNS record values to configure at your DNS provider.
properties:
host:
type: string
description: The DNS host value.
example: '@'
type:
type: string
description: The DNS record type.
example: TXT
value:
type: string
description: The DNS record value to set.
example: nylas-ownership-verify=gNIeZAtY1lPUEpWOhA2XBB...
status:
type: string
description: The current verification status for this type.
enum:
- done
- failed
- pending
example: pending
created_at:
type: number
description: When the info record was created, in seconds using the Unix timestamp format.
example: 1770242496
expires_at:
type: number
description: When the info record expires, in seconds using the Unix timestamp format. Some verification values are temporary and change after expiration.
example: 1770415296
message:
type: string
description: A human-readable message about the current status.
example: Please configure the TXT record for the domain to the returned options. Once done, you can retry the verification.
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/admin/domains/{domain_id}/verify:
parameters:
- schema:
type: string
name: domain_id
in: path
required: true
description: ID of the domain to verify.
- in: header
name: X-Nylas-Signature
schema:
type: string
required: true
description: |-
A Base64-encoded signature using your private key's RSA with a 2048-bit key and an SHA-256 hashed
string of the path, method, timestamp, nonce, and payload.
- in: header
name: X-Nylas-Kid
schema:
type: string
required: true
description: The `private_key_id` from your Service Account JSON file.
- in: header
name: X-Nylas-Nonce
schema:
type: string
required: true
description: |-
A randomly generated nonce. Each request needs to have a unique nonce. If you try to reuse a
nonce, Nylas rejects the request.
- in: header
name: X-Nylas-Timestamp
schema:
type: number
required: true
description: |-
The time when you submit your request, in seconds using the Unix timestamp format. This timestamp should fall within
a 5-minute window of your real request time.
post:
summary: Verify domain
tags:
- Manage Domains
operationId: verify-domain
description: |-
<div id="admonition-warning">⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a href="/docs/v3/auth/nylas-service-account/">Nylas Service Account</a></b>.</div>
Triggers a verification check for the specified DNS record type. Before calling this endpoint,
add the required DNS records to your domain's DNS configuration. You can get the required records
by calling the [Get domain info](/docs/reference/api/manage-domains/get-domain-info/) endpoint.
requestBody:
content:
application/json:
schema:
type: object
required:
- type
properties:
type:
type: string
description: The type of DNS verification to trigger.
enum:
- ownership
- mx
- spf
- dkim
- feedback
example: dkim
x-code-samples:
- lang: bash
label: cURL
source: |-
curl -X POST "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>/verify" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766" \
-d '{
"type": "dkim"
}'
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.handler.service_account import ServiceAccountSigner
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
signer = ServiceAccountSigner(
private_key_pem="<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>",
private_key_id="<SERVICE_ACCOUNT_ID>",
)
result = nylas.domains.verify(
domain_id="<DOMAIN_ID>",
request_body={
"type": "dkim",
},
signer=signer,
)
print(result)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/DomainVerificationResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/policies:
post:
summary: Create a policy
tags:
- Policies
operationId: create-policy
description: |-
Creates a policy for your application. Policies define message limits, spam detection settings, and linked
rules for Nylas Agent Accounts. The `application_id` and `organization_id` are derived from your API key, so you
don't need to include them in the request body — they are read-only.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: A human-readable name for the policy.
example: Standard Agent Account Policy
limits:
type: object
properties:
limit_attachment_size_limit:
type: integer
format: int64
example: 26214400
limit_attachment_count_limit:
type: integer
example: 20
limit_attachment_allowed_types:
type: array
items:
type: string
example:
- image/png
- application/pdf
limit_size_total_mime:
type: integer
format: int64
example: 31457280
limit_storage_total:
type: integer
format: int64
example: 10737418240
limit_count_daily_message_received:
type: integer
format: int64
example: 1000
limit_count_daily_email_sent:
type: integer
format: int64
example: 1000
limit_inbox_retention_period:
type: integer
description: Days. Must be greater than `limit_spam_retention_period` when both are set.
example: 365
limit_spam_retention_period:
type: integer
description: Days. Must be shorter than `limit_inbox_retention_period` when both are set.
example: 30
rules:
type: array
description: Rule IDs to link to this policy.
items:
type: string
example:
- c1d2e3f4-5678-4abc-9def-0123456789ab
spam_detection:
type: object
properties:
use_list_dnsbl:
type: boolean
example: true
use_header_anomaly_detection:
type: boolean
example: true
spam_sensitivity:
type: number
format: float
minimum: 0.1
maximum: 5
example: 1.5
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X POST "https://api.us.nylas.com/v3/policies" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "Standard Agent Account Policy",
"spam_detection": {
"use_list_dnsbl": true,
"use_header_anomaly_detection": true,
"spam_sensitivity": 1.5
},
"limits": {
"limit_attachment_size_limit": 26214400,
"limit_attachment_count_limit": 20,
"limit_inbox_retention_period": 365,
"limit_spam_retention_period": 30
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createPolicy() {
try {
const policy = await nylas.policies.create({
requestBody: {
name: "Standard Agent Account Policy",
rules: ["<RULE_ID>"],
limits: {
limitAttachmentSizeLimit: 26214400,
limitAttachmentCountLimit: 20,
limitInboxRetentionPeriod: 365,
limitSpamRetentionPeriod: 30,
},
spamDetection: {
useListDnsbl: true,
useHeaderAnomalyDetection: true,
spamSensitivity: 1.5,
},
},
});
console.log("Policy:", policy);
} catch (error) {
console.error("Error creating policy:", error);
}
}
createPolicy();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
policy = nylas.policies.create(
request_body={
"name": "Standard Agent Account Policy",
"spam_detection": {
"use_list_dnsbl": True,
"use_header_anomaly_detection": True,
"spam_sensitivity": 1.5,
},
"limits": {
"limit_attachment_size_limit": 26214400,
"limit_attachment_count_limit": 20,
"limit_inbox_retention_period": 365,
"limit_spam_retention_period": 30,
},
},
)
print(policy)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/PolicyObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
get:
summary: List policies
tags:
- Policies
operationId: list-policies
description: Returns a list of all policies for your application.
parameters:
- $ref: '#/components/parameters/limit'
- name: page_token
in: query
required: false
schema:
type: string
description: A token to fetch the next page of results. Use the `next_cursor` value from the previous response.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X GET "https://api.us.nylas.com/v3/policies?limit=50" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listPolicies() {
try {
const policies = await nylas.policies.list({
queryParams: {
limit: 10,
},
});
console.log("Policies:", policies);
} catch (error) {
console.error("Error listing policies:", error);
}
}
listPolicies();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
policies = nylas.policies.list(
query_params={
"limit": 50,
},
)
print(policies)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
type: array
items:
$ref: '#/components/schemas/PolicyObject'
next_cursor:
type: string
description: A token to use for paginating through results. If present, pass this value as `page_token` in the next request.
example: eyJhbGciOiJIUzI1NiJ9
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
/v3/policies/{policy_id}:
parameters:
- schema:
type: string
name: policy_id
in: path
required: true
description: The ID of the policy to access.
get:
summary: Get a policy
tags:
- Policies
operationId: get-policy
description: Returns the specified policy.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X GET "https://api.us.nylas.com/v3/policies/<POLICY_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function findPolicy() {
try {
const policy = await nylas.policies.find({
policyId: "<POLICY_ID>",
});
console.log("Policy:", policy);
} catch (error) {
console.error("Error finding policy:", error);
}
}
findPolicy();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
policy = nylas.policies.find(
policy_id="<POLICY_ID>",
)
print(policy)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/PolicyObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
put:
summary: Update a policy
tags:
- Policies
operationId: update-policy
description: |-
Updates the specified policy. All fields are optional — only provided fields are updated. The same plan-limit,
spam sensitivity, and retention-period validation applies as on create.
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: Updated policy name
limits:
type: object
properties:
limit_attachment_size_limit:
type: integer
format: int64
limit_attachment_count_limit:
type: integer
limit_attachment_allowed_types:
type: array
items:
type: string
limit_size_total_mime:
type: integer
format: int64
limit_storage_total:
type: integer
format: int64
limit_count_daily_message_received:
type: integer
format: int64
limit_count_daily_email_sent:
type: integer
format: int64
limit_inbox_retention_period:
type: integer
limit_spam_retention_period:
type: integer
rules:
type: array
items:
type: string
example:
- c1d2e3f4-5678-4abc-9def-0123456789ab
spam_detection:
type: object
properties:
use_list_dnsbl:
type: boolean
use_header_anomaly_detection:
type: boolean
spam_sensitivity:
type: number
format: float
minimum: 0.1
maximum: 5
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X PUT "https://api.us.nylas.com/v3/policies/<POLICY_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"rules": ["<RULE_ID_1>", "<RULE_ID_2>"]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updatePolicy() {
try {
const policy = await nylas.policies.update({
policyId: "<POLICY_ID>",
requestBody: {
limits: {
limitInboxRetentionPeriod: 180,
},
},
});
console.log("Updated policy:", policy);
} catch (error) {
console.error("Error updating policy:", error);
}
}
updatePolicy();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
policy = nylas.policies.update(
policy_id="<POLICY_ID>",
request_body={
"rules": ["<RULE_ID_1>", "<RULE_ID_2>"],
},
)
print(policy)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/PolicyObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
delete:
summary: Delete a policy
tags:
- Policies
operationId: delete-policy
description: Deletes the specified policy. This action is irreversible.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X DELETE "https://api.us.nylas.com/v3/policies/<POLICY_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deletePolicy() {
try {
const result = await nylas.policies.destroy({
policyId: "<POLICY_ID>",
});
console.log("Deleted policy:", result);
} catch (error) {
console.error("Error deleting policy:", error);
}
}
deletePolicy();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.policies.destroy(
policy_id="<POLICY_ID>",
)
print(response)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
examples:
OK:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
/v3/rules:
post:
summary: Create a rule
tags:
- Rules
operationId: create-rule
description: |-
Creates a rule for your application. A rule defines a `trigger` (`inbound` or `outbound`), conditions against
sender or recipient fields, and actions to apply when the conditions match. Inbound rules run on incoming
messages; outbound rules run on sends before they're submitted to the email provider. Inbound and outbound
rules are isolated — inbound rules never run during sends, and outbound rules never run on message receipt.
Inbound rules can match `from.address`, `from.domain`, or `from.tld`. Outbound rules can match
`from.address`, `from.domain`, `from.tld`, `recipient.address`, `recipient.domain`, `recipient.tld`, or
`outbound.type` (`compose` or `reply`). Link inbound rules to a policy to apply them to specific Agent
Accounts. Outbound rules are currently evaluated from the sending application's enabled outbound rules.
The `application_id` and `organization_id` are derived from your API key and are read-only.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- match
- actions
properties:
name:
type: string
description: A human-readable name for the rule.
example: Block spam domains
description:
type: string
example: Rejects messages from known spam domains at the SMTP level.
priority:
type: integer
minimum: 0
maximum: 1000
default: 10
example: 1
enabled:
type: boolean
default: true
example: true
trigger:
type: string
enum:
- inbound
- outbound
default: inbound
description: |-
When the rule is evaluated. `inbound` runs the rule on incoming messages; `outbound` runs the rule
on sends before they're submitted to the email provider. Inbound rules accept only `from.*`
conditions. Outbound rules accept `from.*`, `recipient.*`, and `outbound.type`.
example: inbound
match:
type: object
required:
- conditions
properties:
operator:
type: string
enum:
- any
- all
description: Optional. When omitted, the rule defaults to `all`.
example: any
conditions:
type: array
minItems: 1
items:
type: object
required:
- field
- operator
- value
properties:
field:
type: string
enum:
- from.address
- from.domain
- from.tld
- recipient.address
- recipient.domain
- recipient.tld
- outbound.type
description: |-
The field to match against. `from.*` fields match the normalized sender address,
domain, or top-level domain. Inbound rules accept only `from.*`. Outbound rules also
accept `recipient.*` and `outbound.type`. For outbound rules, `recipient.*` matches
against any recipient — To, CC, BCC, and SMTP envelope recipients. `outbound.type`
classifies the send as `compose` (new message) or `reply` (replying to an existing
thread).
example: from.domain
operator:
type: string
enum:
- is
- is_not
- contains
- in_list
description: |-
How to compare the field value. `outbound.type` supports only `is` and `is_not`;
`contains` and `in_list` are rejected for that field.
example: is
value:
oneOf:
- type: string
- type: array
items:
type: string
description: |-
The value to compare against. For `in_list`, pass an array of List IDs. For
`outbound.type`, pass `compose` or `reply` (case is normalized to lowercase).
example: spam-domain.com
actions:
type: array
minItems: 1
items:
type: object
required:
- type
properties:
type:
type: string
enum:
- block
- mark_as_spam
- assign_to_folder
- mark_as_read
- mark_as_starred
- archive
- trash
example: block
value:
type: string
description: |-
Required when `type` is `assign_to_folder` — the target folder by name. Use a custom
folder's name (or its full path for a nested folder, e.g. `Clients/Acme`), or a system
folder name (`Inbox`, `Sent`, `Drafts`, `Trash`, `Junk`, `Archive`).
example: Receipts
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X POST "https://api.us.nylas.com/v3/rules" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "Block spam domains",
"priority": 1,
"trigger": "inbound",
"match": {
"operator": "any",
"conditions": [
{
"field": "from.domain",
"operator": "is",
"value": "spam-domain.com"
}
]
},
"actions": [
{ "type": "block" }
]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createRule() {
try {
const rule = await nylas.rules.create({
requestBody: {
name: "Block spam domains",
description: "Rejects messages from known spam domains.",
priority: 1,
trigger: "inbound",
match: {
operator: "any",
conditions: [
{
field: "from.domain",
operator: "is",
value: "spam-domain.com",
},
],
},
actions: [{ type: "block" }],
},
});
console.log("Rule:", rule);
} catch (error) {
console.error("Error creating rule:", error);
}
}
createRule();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
rule = nylas.rules.create(
request_body={
"name": "Block spam domains",
"priority": 1,
"trigger": "inbound",
"match": {
"operator": "any",
"conditions": [
{
"field": "from.domain",
"operator": "is",
"value": "spam-domain.com",
},
],
},
"actions": [
{"type": "block"},
],
},
)
print(rule)
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/RuleObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
get:
summary: List rules
tags:
- Rules
operationId: list-rules
description: Returns a list of all rules for your application.
parameters:
- $ref: '#/components/parameters/limit'
- name: page_token
in: query
required: false
schema:
type: string
description: A token to fetch the next page of results. Use the `next_cursor` value from the previous response.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X GET "https://api.us.nylas.com/v3/rules?limit=50" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listRules() {
try {
const rules = await nylas.rules.list({
queryParams: {
limit: 10,
},
});
console.log("Rules:", rules);
} catch (error) {
console.error("Error listing rules:", error);
}
}
listRules();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
rules = nylas.rules.list(
query_params={
"limit": 50,
},
)
print(rules)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
type: array
items:
$ref: '#/components/schemas/RuleObject'
next_cursor:
type: string
description: A token to use for paginating through results. If present, pass this value as `page_token` in the next request.
example: eyJhbGciOiJIUzI1NiJ9
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
/v3/rules/{rule_id}:
parameters:
- schema:
type: string
name: rule_id
in: path
required: true
description: The ID of the rule to access.
get:
summary: Get a rule
tags:
- Rules
operationId: get-rule
description: Returns the specified rule.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X GET "https://api.us.nylas.com/v3/rules/<RULE_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function findRule() {
try {
const rule = await nylas.rules.find({
ruleId: "<RULE_ID>",
});
console.log("Rule:", rule);
} catch (error) {
console.error("Error finding rule:", error);
}
}
findRule();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
rule = nylas.rules.find(
rule_id="<RULE_ID>",
)
print(rule)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/RuleObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
put:
summary: Update a rule
tags:
- Rules
operationId: update-rule
description: |-
Updates the specified rule. All fields are optional — only provided fields are updated. The same validation rules
apply as on create.
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: Block spam domains (updated)
description:
type: string
priority:
type: integer
minimum: 0
maximum: 1000
enabled:
type: boolean
trigger:
type: string
enum:
- inbound
- outbound
description: |-
The trigger the rule listens for. Inbound rules accept only `from.*` conditions. Outbound
rules accept `from.*`, `recipient.*`, and `outbound.type`.
match:
type: object
properties:
operator:
type: string
enum:
- any
- all
description: Optional. When omitted, the rule defaults to `all`.
conditions:
type: array
items:
type: object
properties:
field:
type: string
enum:
- from.address
- from.domain
- from.tld
- recipient.address
- recipient.domain
- recipient.tld
- outbound.type
description: |-
`from.*` fields match the normalized sender and are valid on both triggers.
`recipient.*` fields and `outbound.type` apply only to `outbound` rules.
`recipient.*` matches any recipient on the send, including To, CC, BCC, and SMTP
envelope recipients.
operator:
type: string
enum:
- is
- is_not
- contains
- in_list
description: '`outbound.type` accepts only `is` and `is_not`.'
value:
oneOf:
- type: string
- type: array
items:
type: string
description: |-
For `in_list`, pass an array of List IDs. For `outbound.type`, pass `compose` or
`reply` (normalized to lowercase).
actions:
type: array
items:
type: object
properties:
type:
type: string
enum:
- block
- mark_as_spam
- assign_to_folder
- mark_as_read
- mark_as_starred
- archive
- trash
value:
type: string
description: |-
Required when `type` is `assign_to_folder` — the target folder by name. Use a custom
folder's name (or its full path for a nested folder, e.g. `Clients/Acme`), or a system
folder name (`Inbox`, `Sent`, `Drafts`, `Trash`, `Junk`, `Archive`).
example: Receipts
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X PUT "https://api.us.nylas.com/v3/rules/<RULE_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateRule() {
try {
const rule = await nylas.rules.update({
ruleId: "<RULE_ID>",
requestBody: {
enabled: false,
priority: 5,
},
});
console.log("Updated rule:", rule);
} catch (error) {
console.error("Error updating rule:", error);
}
}
updateRule();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
rule = nylas.rules.update(
rule_id="<RULE_ID>",
request_body={
"enabled": False,
},
)
print(rule)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/RuleObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
delete:
summary: Delete a rule
tags:
- Rules
operationId: delete-rule
description: |-
Deletes the specified rule. This action is irreversible. Policies that reference the rule no longer apply it
during inbound processing, and outbound sends no longer evaluate it after deletion.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X DELETE "https://api.us.nylas.com/v3/rules/<RULE_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deleteRule() {
try {
const result = await nylas.rules.destroy({
ruleId: "<RULE_ID>",
});
console.log("Deleted rule:", result);
} catch (error) {
console.error("Error deleting rule:", error);
}
}
deleteRule();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.rules.destroy(
rule_id="<RULE_ID>",
)
print(response)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
examples:
OK:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
/v3/grants/{grant_id}/rule-evaluations:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: The ID of the grant to list rule evaluations for.
get:
summary: List rule evaluations
tags:
- Rules
operationId: list-rule-evaluations
description: |-
Returns a paginated list of rule evaluation records for the specified grant. Each record captures
which rules were evaluated against an inbound message, SMTP envelope, or outbound send, the
normalized sender or recipient data that was matched, which rules matched, and which actions were
applied.
Rule evaluations are created automatically as inbound mail is processed and as outbound sends are
evaluated, and serve as an audit trail for the Rules engine. Records are returned in reverse
chronological order (most recent first).
parameters:
- $ref: '#/components/parameters/limit'
- name: page_token
in: query
required: false
schema:
type: string
description: A cursor to fetch the next page of results. Use the `next_cursor` value from the previous response.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X GET "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/rule-evaluations?limit=50" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listRuleEvaluations() {
try {
const evaluations = await nylas.rules.listEvaluations({
identifier: "<NYLAS_GRANT_ID>",
queryParams: {
limit: 10,
},
});
console.log("Rule evaluations:", evaluations);
} catch (error) {
console.error("Error listing rule evaluations:", error);
}
}
listRuleEvaluations();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
evaluations = nylas.rules.list_evaluations(
grant_id="<NYLAS_GRANT_ID>",
query_params={
"limit": 50,
},
)
print("Rule evaluations:", evaluations)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
type: array
items:
$ref: '#/components/schemas/GrantRuleEvaluationObject'
next_cursor:
type: string
description: |-
A cursor for paginating through results. Present when there are more results; pass this
value as `page_token` in the next request.
example: eyJsYXN0X2lkIjoiYjIzZGM0NWUtNjdmOC05MDEyLWJjZGUtMzQ1Njc4OWFiY2RmIn0=
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
/v3/lists:
post:
summary: Create a list
tags:
- Lists
operationId: create-list
description: |-
Creates a list for your application. Lists are typed collections of values (domains, TLDs, or email addresses)
that can be referenced by rules using the `in_list` condition operator.
The list's `type` is set at creation and cannot be changed.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- type
properties:
name:
type: string
minLength: 1
maxLength: 256
example: Blocked domains
description:
type: string
example: Domains we've identified as sending unwanted mail.
type:
type: string
enum:
- domain
- tld
- address
description: The kind of values the list holds. Immutable after creation.
example: domain
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X POST "https://api.us.nylas.com/v3/lists" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "Blocked domains",
"description": "Domains we have identified as sending unwanted mail.",
"type": "domain"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createList() {
try {
const list = await nylas.lists.create({
requestBody: {
name: "Blocked domains",
description: "Domains we have identified as sending unwanted mail.",
type: "domain",
},
});
console.log("List:", list);
} catch (error) {
console.error("Error creating list:", error);
}
}
createList();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
nylas_list = nylas.lists.create(
request_body={
"name": "Blocked domains",
"description": "Domains we have identified as sending unwanted mail.",
"type": "domain",
},
)
print(nylas_list)
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/ListObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
get:
summary: List lists
tags:
- Lists
operationId: list-lists
description: Returns all lists for your application.
parameters:
- $ref: '#/components/parameters/limit'
- name: page_token
in: query
required: false
schema:
type: string
description: A token to fetch the next page of results. Use the `next_cursor` value from the previous response.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X GET "https://api.us.nylas.com/v3/lists?limit=50" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listAgentLists() {
try {
const lists = await nylas.lists.list({
queryParams: {
limit: 10,
},
});
console.log("Lists:", lists);
} catch (error) {
console.error("Error listing lists:", error);
}
}
listAgentLists();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
lists = nylas.lists.list(
query_params={
"limit": 50,
},
)
print(lists)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
type: array
items:
$ref: '#/components/schemas/ListObject'
next_cursor:
type: string
description: A token to use for paginating through results. If present, pass this value as `page_token` in the next request.
example: eyJhbGciOiJIUzI1NiJ9
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
/v3/lists/{list_id}:
parameters:
- schema:
type: string
name: list_id
in: path
required: true
description: The ID of the list to access.
get:
summary: Get a list
tags:
- Lists
operationId: get-list
description: Returns the specified list.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X GET "https://api.us.nylas.com/v3/lists/<LIST_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function findList() {
try {
const list = await nylas.lists.find({
listId: "<LIST_ID>",
});
console.log("List:", list);
} catch (error) {
console.error("Error finding list:", error);
}
}
findList();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
nylas_list = nylas.lists.find(
list_id="<LIST_ID>",
)
print(nylas_list)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/ListObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
put:
summary: Update a list
tags:
- Lists
operationId: update-list
description: |-
Updates the specified list. Only `name` and `description` can be updated. The list `type` is immutable after
creation.
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 256
example: Blocked domains (updated)
description:
type: string
example: Updated description.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X PUT "https://api.us.nylas.com/v3/lists/<LIST_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "Blocked domains (updated)",
"description": "Updated description."
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateList() {
try {
const list = await nylas.lists.update({
listId: "<LIST_ID>",
requestBody: {
name: "Updated list name",
description: "Updated description.",
},
});
console.log("Updated list:", list);
} catch (error) {
console.error("Error updating list:", error);
}
}
updateList();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
nylas_list = nylas.lists.update(
list_id="<LIST_ID>",
request_body={
"name": "Blocked domains (updated)",
"description": "Updated description.",
},
)
print(nylas_list)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/ListObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
delete:
summary: Delete a list
tags:
- Lists
operationId: delete-list
description: |-
Deletes the specified list. This action is irreversible and cascades to all items in the list. Rules that
reference the list through an `in_list` condition no longer match its values after deletion.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X DELETE "https://api.us.nylas.com/v3/lists/<LIST_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deleteList() {
try {
const result = await nylas.lists.destroy({
listId: "<LIST_ID>",
});
console.log("Deleted list:", result);
} catch (error) {
console.error("Error deleting list:", error);
}
}
deleteList();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.lists.destroy(
list_id="<LIST_ID>",
)
print(response)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
examples:
OK:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
/v3/lists/{list_id}/items:
parameters:
- schema:
type: string
name: list_id
in: path
required: true
description: The ID of the list whose items you want to manage.
post:
summary: Add items to a list
tags:
- Lists
operationId: add-list-items
description: |-
Adds items to the specified list. Values are normalized (lowercased and trimmed) and validated against the list's
`type` — `domain` lists accept domain names, `tld` lists accept top-level domains, and `address` lists accept full
email addresses. Duplicate additions are silently ignored.
The response returns the updated List object with a refreshed `items_count`. You can submit up to 1000 items per
request, and each item value can be at most 500 characters. Values that exceed this length return a `400`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
maxItems: 1000
items:
type: string
maxLength: 500
example:
- spam-domain.com
- another-bad-domain.net
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X POST "https://api.us.nylas.com/v3/lists/<LIST_ID>/items" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"items": ["spam-domain.com", "another-bad-domain.net"]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function addItems() {
try {
const list = await nylas.lists.addItems({
listId: "<LIST_ID>",
requestBody: {
items: ["spam-domain.com", "another-bad-domain.net"],
},
});
console.log("Updated list:", list);
} catch (error) {
console.error("Error adding items:", error);
}
}
addItems();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
nylas_list = nylas.lists.add_items(
list_id="<LIST_ID>",
request_body={
"items": ["spam-domain.com", "another-bad-domain.net"],
},
)
print(nylas_list)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/ListObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
get:
summary: List items in a list
tags:
- Lists
operationId: list-list-items
description: Returns the items in the specified list.
parameters:
- $ref: '#/components/parameters/limit'
- name: page_token
in: query
required: false
schema:
type: string
description: A token to fetch the next page of results. Use the `next_cursor` value from the previous response.
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X GET "https://api.us.nylas.com/v3/lists/<LIST_ID>/items?limit=50" \
-H "Authorization: Bearer <NYLAS_API_KEY>"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listItems() {
try {
const items = await nylas.lists.listItems({
listId: "<LIST_ID>",
queryParams: {
limit: 10,
},
});
console.log("List items:", items);
} catch (error) {
console.error("Error listing items:", error);
}
}
listItems();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
items = nylas.lists.list_items(
list_id="<LIST_ID>",
query_params={
"limit": 50,
},
)
print(items)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
type: array
items:
$ref: '#/components/schemas/ListItemObject'
next_cursor:
type: string
description: A token to use for paginating through results. If present, pass this value as `page_token` in the next request.
example: eyJhbGciOiJIUzI1NiJ9
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
delete:
summary: Remove items from a list
tags:
- Lists
operationId: remove-list-items
description: |-
Removes the specified items from the list. Values not currently in the list are silently ignored. The response
returns the updated List object with a refreshed `items_count`. You can submit up to 1000 items per request.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
maxItems: 1000
items:
type: string
example:
- spam-domain.com
x-code-samples:
- lang: bash
label: cURL
source: |
curl -X DELETE "https://api.us.nylas.com/v3/lists/<LIST_ID>/items" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"items": ["spam-domain.com"]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function removeItems() {
try {
const list = await nylas.lists.removeItems({
listId: "<LIST_ID>",
requestBody: {
items: ["another-bad-domain.net"],
},
});
console.log("Updated list:", list);
} catch (error) {
console.error("Error removing items:", error);
}
}
removeItems();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
nylas_list = nylas.lists.remove_items(
list_id="<LIST_ID>",
request_body={
"items": ["spam-domain.com"],
},
)
print(nylas_list)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
$ref: '#/components/schemas/ListObject'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
security:
- NYLAS_API_KEY: []
/v3/grants/{grant_id}/messages:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or
use `/me/` to refer to the grant associated with an access token.
example: nyla@example.com
get:
summary: Return all Messages
tags:
- Messages
operationId: get-messages
description: |-
Returns all messages using [standard pagination](/docs/reference/api/#pagination).
<div id="admonition-warning">
⚠️ <b>Your users receive a large number of messages</b>. If you encounter
<a href="/docs/api/errors/400-response/"><code>429</code> errors</a> or provider
<a href="/docs/dev-guide/platform/rate-limits/">rate limits</a> when listing messages, Nylas
recommends you set the <code>limit</code> parameter to 20 and add
<a href="#query-parameters">query parameters</a> to your request to
limit the results.</div>
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.Read.Shared
- https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- name: any_email
schema:
type: string
in: query
description: |-
Return messages that were sent to or received from this comma-separated list of email addresses
(for example, `leyah@example.com,nyla@example.com`). Nylas returns messages that contain one
of the specified email addresses in the To, From, CC, or BCC fields. You can specify up to 25
email addresses per request.
- name: bcc
schema:
type: string
in: query
description: |-
Return messages that include the specified email address in the BCC list. Because most SMTP
gateways remove BCC information, Nylas usually returns messages sent from the current grant.
For Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of
this query parameter. This is because of a limitation on the provider. Instead, you can use
the `thread_id` to retrieve a specific conversation.
- name: cc
schema:
type: string
in: query
description: |-
Return messages that include the specified email address in the CC list.
For Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of
this query parameter. This is because of a limitation on the provider. Instead, you can use
the `thread_id` to retrieve a specific conversation.
- name: fields
schema:
type: string
enum:
- standard
- include_headers
- include_basic_headers
- include_tracking_options
- raw_mime
x-enumDescriptions:
standard: Returns the standard message payload.
include_headers: Returns messages and their full set of headers.
include_basic_headers: Returns messages with only `Message-ID`, `In-Reply-To`, and `References` in the `headers` array.
include_tracking_options: Returns messages and their tracking settings.
raw_mime: Returns `grant_id`, `object`, `id`, and `raw_mime` fields for each message.
default: standard
in: query
description: |-
Return the specified data for each message.
- `standard`: Returns the standard message payload.
- `include_headers`: Returns messages and their full set of headers.
- `include_basic_headers`: Returns messages with only the three RFC threading headers
(`Message-ID`, `In-Reply-To`, `References`) in the `headers` array. Use this option when you
only need to track message identity and thread relationships — payload size is significantly
smaller than `include_headers`.
- `include_tracking_options`: Returns messages and their [tracking settings](/docs/v3/email/message-tracking/).
- `raw_mime`: Returns the `grant_id`, `object`, `id`, and `raw_mime` fields for each message.
- name: from
schema:
type: string
in: query
description: |-
Return messages sent from the specified email address. If you want to filter for messages sent
from the current grant, use the `in` query parameter and specify the Sent folder instead.
For Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of
this query parameter. This is because of a limitation on the provider. Instead, you can use
the `thread_id` to retrieve a specific conversation.
- name: has_attachment
schema:
type: boolean
in: query
description: When `true`, Nylas returns messages that include attachments.
- name: in
schema:
type: string
in: query
description: |-
Return messages in the specified folder or label, by folder ID.
Required when using `shared_from` or `query_imap`.
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/metadata_pair'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/query_imap_list'
- name: received_after
schema:
type: integer
in: query
description: Return messages received after the specified time, in seconds using the Unix timestamp format.
- name: received_before
schema:
type: integer
in: query
description: Return messages received before the specified time, in seconds using the Unix timestamp format.
- name: search_query_native
schema:
type: string
in: query
description: |-
Specify a URL-encoded search query. Connected providers use their provider-specific syntax,
while Nylas Agent Accounts use Nylas full-text search syntax. The query parameters that you can
use alongside `search_query_native` depend on the provider:
- **Google**: `in`, `limit`, and `page_token`
- **Microsoft**: `in`, `limit`, and `page_token`
- **IMAP/Yahoo/iCloud**: Any parameter
- **EWS**: Any parameter _except_ `thread_id`
- **Nylas Agent Accounts**: Any other parameter supported for Agent Accounts by this endpoint
Required when using `shared_from`.
For an overview of searching messages and threads with `search_query_native` across providers,
see [Searching with Nylas](/docs/dev-guide/best-practices/search/#search-messages-and-threads-using-search_query_native).
If you're using a Nylas Agent Account, see
[Email search for Agent Accounts](/docs/v3/agent-accounts/email-search/) for the complete Nylas
search syntax, examples, and limits.
examples:
Agent Account:
description: Nylas full-text query for messages that contain "charger" or "station".
value: charger%20OR%20station
Google:
description: Google query string for messages with subject "foo" or "bar".
value: subject%3Afoo%20OR%20subject%3Abar
Microsoft:
description: Microsoft Graph query for messages using the `$filter` syntax.
value: '%24filter%3Dfrom%2FemailAddress%2Faddress%20eq%20%27someuser%40example.com%27'
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/shared_folder_id'
- $ref: '#/components/parameters/shared_from'
- name: starred
schema:
type: boolean
in: query
description: |-
When `true`, Nylas returns starred messages.
EWS only supports starred messages on Microsoft Exchange 2010 or later.
- name: subject
schema:
type: string
in: query
description: |-
Return messages with a matching subject. This filter is case-sensitive and returns partial
matches.
- name: thread_id
schema:
type: string
in: query
description: Return messages in the specified thread.
- name: to
schema:
type: string
in: query
description: |-
Return messages sent to the specified email address.
For Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of
this query parameter. This is because of a limitation on the provider. Instead, you can use
the `thread_id` to retrieve a specific conversation.
- name: unread
schema:
type: boolean
in: query
description: When `true`, Nylas returns unread messages.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?limit=5" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchRecentEmails() {
try {
const messages = await nylas.messages.list({
identifier: "<NYLAS_GRANT_ID>",
queryParams: {
limit: 5,
},
});
console.log("Messages:", messages);
} catch (error) {
console.error("Error fetching emails:", error);
}
}
fetchRecentEmails();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
messages = nylas.messages.list(
grant_id,
query_params={
"limit": 5
}
)
print(messages)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nmessages, _ = nylas.messages.list(identifier: \"<NYLAS_GRANT_ID>\")\nmessages.each {|message|\n\tputs \"[#{Time.at(message[:date]).strftime(\"%d/%m/%Y at %H:%M:%S\")}] | \\\n#{message[:id]} | \\\n#{message[:subject]} | \\\n#{message[:folders]}\"\n}\n"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.text.SimpleDateFormat;
public class ReadEmail {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Message> message = nylas.messages().list("<NYLAS_GRANT_ID>");
for(Message email : message.getData()){
String date = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").
format(new java.util.Date((email.getDate() == null ? 1 : 1000L)));
System.out.println(email.getId() + "[" + date + "] | " +
email.getSubject() + " | " +
email.getFolders());
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.*
import java.text.SimpleDateFormat
import java.util.*
fun dateFormatter(milliseconds: String): String {
return SimpleDateFormat("dd/MM/yyyy HH:mm:ss").
format(Date(milliseconds.toLong() * 1000)).
toString()
}
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val messages : List<Message> = nylas.messages().list("<NYLAS_GRANT_ID>").data
for(message in messages){
println("[${message.id}] | " +
"${message.subject} | " +
"${message.folders}")
}
}
responses:
'200':
$ref: '#/components/responses/messages'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/grants/{grant_id}/messages/{message_id}:
parameters:
- $ref: '#/components/parameters/grant_id'
- schema:
type: string
name: message_id
in: path
required: true
description: |-
ID of the message to access. We recommend you URL-encode this field, or you might receive a
[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for example,
`#`).
get:
summary: Return a Message
tags:
- Messages
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.Read.Shared
- https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r
responses:
'200':
$ref: '#/components/responses/message'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-messages-id
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- name: fields
in: query
description: |-
Return the specified data for each message.
- `standard`: Returns the standard message payload.
- `include_headers`: Returns the message and its full set of headers.
- `include_basic_headers`: Returns the message with only the three RFC threading headers
(`Message-ID`, `In-Reply-To`, `References`) in the `headers` array. Use this option when you
only need to track message identity and thread relationships — payload size is significantly
smaller than `include_headers`.
- `include_tracking_options`: Returns the message and its [tracking settings](/docs/v3/email/message-tracking/).
- `raw_mime`: Returns the `grant_id`, `object`, `id`, and `raw_mime` fields for the message.
schema:
type: string
enum:
- standard
- include_headers
- include_basic_headers
- include_tracking_options
- raw_mime
default: standard
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/query_imap_get_by_id'
- $ref: '#/components/parameters/shared_from'
description: Returns the specified message.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchMessageById() {
try {
const message = await nylas.messages.find({
identifier: "<NYLAS_GRANT_ID>",
messageId: "<MESSAGE_ID>",
});
console.log("message:", message);
} catch (error) {
console.error("Error fetching message:", error);
}
}
fetchMessageById();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
message_id = "<MESSAGE_ID>"
message = nylas.messages.find(
grant_id,
message_id,
)
print(message)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nmessage, _ = nylas.messages.find(identifier: \"<NYLAS_GRANT_ID>\", message_id: \"<MESSAGE_ID>\")\n\nputs message"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReturnMessage {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Message> message =
nylas.messages().find("<NYLAS_GRANT_ID>", "<MESSAGE_ID>");
System.out.println(message);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
// Import Nylas packages
import com.nylas.NylasClient
fun main(args: Array<String>) {
// Initialize Nylas client
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val message = nylas.messages().find( "<NYLAS_GRANT_ID>", "<MESSAGE_ID>")
println(message)
}
put:
summary: Update message attributes
tags:
- Messages
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.modify
others: ''
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/message'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: put-messages-id
description: |-
Updates the attributes (folders, stars, read/unread status, and so on) for the specified email
message.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/query_imap_get_by_id'
- $ref: '#/components/parameters/shared_from'
requestBody:
$ref: '#/components/requestBodies/message_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"folders": ["<FOLDER_ID>"]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const folderId = "<FOLDER_ID>";
const messageId = "<MESSAGE_ID>";
const updateMessageFolder = async () => {
try {
const updatedMessage = await nylas.messages.update({
identifier,
messageId,
requestBody: {
folders: [folderId],
},
});
console.log("Message updated:", updatedMessage);
} catch (error) {
console.error("Error updating message folder:", error);
}
};
updateMessageFolder();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
folder_id = "<FOLDER_ID>"
message_id = "<MESSAGE_ID>"
message = nylas.messages.update(
grant_id,
message_id,
request_body={
"folders": [folder_id]
}
)
print(message)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n unread: true,\n starred: true\n}\n\nmessage, _ = nylas.messages.update(identifier: \"<NYLAS_GRANT_ID>\", \n message_id: \"<MESSAGE_ID>\", \n request_body: request_body)\n\nputs message\n\n"
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.List;
public class UpdateMessage {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateMessageRequest request = new UpdateMessageRequest.Builder().
unread(true).
starred(true).
build();
Response<Message> message = nylas.messages().
update("<NYLAS_GRANT_ID>", "<MESSAGE_ID>", request);
System.out.println(message);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.UpdateMessageRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val request : UpdateMessageRequest =
UpdateMessageRequest.Builder().
unread(true).
starred(true).
build()
val message = nylas.messages().update(
"<NYLAS_GRANT_ID>",
"<MESSAGE_ID>", request
)
print(message)
}
delete:
summary: Delete a message
tags:
- Messages
operationId: delete-message
description: |-
Deletes the specified message. If `hard_delete` is not defined or is `false`, Nylas moves the
message to the user's Trash folder.
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.modify
others: https://mail.google.com/
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/hard_delete'
- $ref: '#/components/parameters/shared_from'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deleteMessage() {
try {
const result = await nylas.messages.destroy({
identifier: "<NYLAS_GRANT_ID>",
messageId: "<MESSAGE_ID>",
});
console.log("Result:", result);
} catch (error) {
console.error("Error deleting message:", error);
}
}
deleteMessage();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
message_id = "<MESSAGE_ID>"
result = nylas.messages.destroy(
grant_id,
message_id,
)
print(result)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nstatus, _ = nylas.messages.destroy(identifier: \"<NYLAS_GRANT_ID>\", \n message_id: \"<MESSAGE_ID>\")\n\nputs status\n"
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val message =
nylas.messages().destroy("<NYLAS_GRANT_ID>",
"<MESSAGE_ID>")
println(message)
}
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReturnMessage {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse message = nylas.messages().destroy("<NYLAS_GRANT_ID>",
"<MESSAGE_ID>");
System.out.println(message);
}
}
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/grants/{grant_id}/messages/clean:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
put:
summary: Clean messages
tags:
- Messages
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
microsoft:
min: https://graph.microsoft.com/Mail.Read
yahoo:
min: email, mail-r
ews:
min: ews.messages
responses:
'200':
$ref: '#/components/responses/messages-clean'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: clean-messages
description: |-
Removes extra information from structured messages.
**Note**: Nylas removes all extra information, such as `<script>` and `<style>` tags, regardless
of the configuration.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/shared_from'
requestBody:
$ref: '#/components/requestBodies/messages-clean'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/clean' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"message_id": ["<MESSAGE_ID>"],
"ignore_links": true,
"ignore_images": true,
"images_as_markdown": false,
"ignore_tables": true,
"remove_conclusion_phrases": true,
"html_as_markdown": false
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function cleanMessages() {
try {
const messages = await nylas.messages.cleanMessages({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
messageId: ["<MESSAGE_ID>"],
ignoreImages: true,
ignoreLinks: true,
ignoreTables: true,
imagesAsMarkdown: true,
removeConclusionPhrases: true,
},
});
console.log("Cleaned messages:", messages);
} catch (error) {
console.error("Error cleaning messages:", error);
}
}
cleanMessages();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
api_key = "<NYLAS_API_KEY>"
)
request_body = {
"message_id": ["<MESSAGE_ID>"],
"ignore_images": True,
"ignore_links": True,
"ignore_tables": True,
"images_as_markdown": True,
"remove_conclusion_phrases": True,
}
response = nylas.messages.clean_messages("<NYLAS_GRANT_ID>",
request_body=request_body).data
print(response[0].body)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
message_id: ["<MESSAGE_ID>"],
ignore_images: true,
ignore_links: true,
ignore_tables: true,
images_as_markdown: true,
remove_conclusion_phrases: true
}
cleaned, _request_id = nylas.messages.clean_messages(
identifier: "<NYLAS_GRANT_ID>",
request_body: request_body
)
cleaned.each do |message|
puts message[:conversation]
end
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
public class Clean_Message {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<String> messagesId = List.of("<MESSAGE_ID>");
CleanMessagesRequest requestBody =
new CleanMessagesRequest.Builder(messagesId).
ignoreImages(true).
ignoreLinks(true).
ignoreTables(true).
imagesAsMarkdown(true).
removeConclusionPhrases(true)
.build();
ListResponse<CleanMessagesResponse> clean =
nylas.messages().cleanMessages("<NYLAS_GRANT_ID>", requestBody);
System.out.println(clean.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.CleanMessagesRequest
import com.nylas.models.Message
import com.nylas.resources.Messages
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val messageId = listOf("<MESSAGE_ID>")
val requestBody = CleanMessagesRequest.
Builder(messageId).
ignoreImages(true).
ignoreLinks(true).
ignoreTables(true).
imagesAsMarkdown(true).
removeConclusionPhrases(true).build()
var result = nylas.messages().cleanMessages("<NYLAS_GRANT_ID>",
requestBody)
print(result.data[0].body)
}
/v3/grants/{grant_id}/messages/send:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
- in: header
name: Idempotency-Key
schema:
type: string
maxLength: 256
required: false
description: |-
A unique, client-generated key (max 256 characters) that lets you safely retry this send request
without sending duplicate emails. Nylas caches the response (success or error) for 1 hour, scoped
per grant. A retry with the same key and payload returns the cached response with the
`Idempotent-Response: true` header set. See
[Idempotent send requests](/docs/v3/email/idempotent-send/) for the full retry behavior and
error responses.
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
post:
summary: Send a Message
tags:
- Messages
operationId: send-message
description: |-
Sends the specified message. If you want to send the message immediately, omit the `send_at` field
from your request. If you want to schedule it to be sent later, set `send_at` to the time you want
to send the message, in seconds using the Unix timestamp format.
For more information about scheduling messages, see
[Schedule messages to send in the future](/docs/v3/email/scheduled-send/).
To use a custom hostname for link click or message open tracking, provide
`tracking_options.domain_name`. Nylas validates that the authenticated organization owns an
active certificate for the hostname. If you omit the field, Nylas uses its regional tracking
hostname. Scheduled sends validate an explicit custom hostname when you create the schedule and
revalidate it immediately before delivery. If the hostname is no longer eligible, the scheduled
send fails without falling back to a Nylas hostname.
(Google and Microsoft Graph only) When scheduling a message, you can set `use_draft` to `true` to
save the message in the user's Drafts folder until it's sent.
Nylas also supports sending raw MIME messages. For more information, see [Send messages with MIME data](/docs/v3/email/headers-mime-data/#send-messages-with-mime-data).
### Limitations
Microsoft Graph and iCloud don't support the `List-Unsubscribe-Post` or `List-Unsubscribe` headers.
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.send
others:
- https://www.googleapis.com/auth/gmail.compose
- https://www.googleapis.com/auth/gmail.modify
microsoft:
min:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.Send
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- name: fields
in: query
required: false
schema:
type: string
enum:
- standard
- include_headers
- include_basic_headers
x-enumDescriptions:
standard: Returns the standard send response.
include_headers: Returns the full `headers` array on the send response.
include_basic_headers: Returns only `Message-ID`, `In-Reply-To`, and `References` in the `headers` array.
default: standard
description: |-
Include message headers in the send response. Headers are returned in the same `headers` array
format as [Get Message](/docs/reference/api/messages/get-messages-id/) responses.
- `standard`: Returns the standard send response (no `headers` array).
- `include_headers`: Returns the full set of headers on the response.
- `include_basic_headers`: Returns only the three RFC threading headers (`Message-ID`,
`In-Reply-To`, `References`). Use this option when you only need to track message identity
and thread relationships — payload size is significantly smaller than `include_headers`.
Supported on **synchronous** send only. The parameter has no effect when you set the `send_at`
field on the request (scheduled send is asynchronous and doesn't return headers).
For provider support details, see
[Using email headers and MIME data](/docs/v3/email/headers-mime-data/#provider-support).
requestBody:
$ref: '#/components/requestBodies/message_send'
responses:
'200':
$ref: '#/components/responses/200_messages_send'
'202':
$ref: '#/components/responses/202'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'409':
$ref: '#/components/responses/409_idempotent'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
x-code-samples:
- lang: bash
label: cURL (application/json)
source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n\t\t\"subject\": \"Reaching Out with Nylas\",\n\t\t\"body\": \"Reaching out using the <a href='https://www.nylas.com/products/email-api/'>Nylas Email API</a>\",\n\t\t\"to\": [{\n\t\t\t\"name\": \"Leyah Miller\",\n\t\t\t\"email\": \"leyah@example.com\"\n\t\t}],\n\t\t\"tracking_options\": {\n\t\t\t\"opens\": true,\n\t\t\t\"links\": true,\n\t\t\t\"thread_replies\": true,\n\t\t\t\"label\": \"hey just testing\"\n\t\t}\n\t}'"
- lang: bash (multipart/form-data)
label: cURL (multipart/form-data)
source: "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/send' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: multipart/form-data' \\\n --form 'message=\"{\n\t\\\"subject\\\": \\\"Reaching Out with Nylas\\\",\n\t\\\"body\\\": \\\"Reaching out using the <a href='\\''https://www.nylas.com/products/email-api/'\\''>Nylas Email API</a>\\\",\n\t\\\"to\\\": [{\n\t\t\\\"name\\\": \\\"Leyah Miller\\\",\n\t\t\\\"email\\\": \\\"leyah@example.com\\\"\n\t}]\n }\"'"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function sendEmail() {
try {
const sentMessage = await nylas.messages.send({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
to: [{ name: "Name", email: "<EMAIL>" }],
replyTo: [{ name: "Name", email: "<EMAIL>" }],
replyToMessageId: "<MESSAGE_ID>",
subject: "Your Subject Here",
body: "Your email body here.",
},
});
console.log("Sent message:", sentMessage);
} catch (error) {
console.error("Error sending email:", error);
}
}
sendEmail();
- lang: python
label: Python SDK
source: |
import os
import sys
from nylas import Client
from nylas import utils
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
email = "<EMAIL>"
attachment = utils.file_utils.attach_file_request_builder("Nylas_Logo.png")
message = nylas.messages.send(
grant_id,
request_body={
"to": [{ "name": "Name", "email": email }],
"reply_to": [{ "name": "Name", "email": email }],
"reply_to_message_id": "<MESSAGE_ID>",
"subject": "Your Subject Here",
"body": "Your email body here.",
"attachments": [attachment]
}
)
print(message)
- lang: ruby
label: Ruby SDK
source: |-
require 'nylas'
# Initialize the Nylas client
nylas = Nylas::Client.new(
api_key: '<NYLAS_API_KEY>',
api_uri: '<NYLAS_API_URI>'
)
grant_id = '<NYLAS_GRANT_ID>'
email = '<EMAIL>'
# Prepare the attachment
attachment = Nylas::FileUtils.attach_file_request_builder('Nylas_Logo.png')
# Send the message
message, _request_id = nylas.messages.send(
identifier: grant_id,
request_body: {
to: [{ name: 'Name', email: email }],
reply_to: [{ name: 'Name', email: email }],
reply_to_message_id: '<MESSAGE_ID>',
subject: 'Your Subject Here',
body: 'Your email body here.',
attachments: [attachment]
}
)
puts message
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
import com.nylas.util.FileUtils;
public class SendEmails {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CreateAttachmentRequest attachment = FileUtils.attachFileRequestBuilder("src/main/java/Nylas_Logo.png");
List<CreateAttachmentRequest> request = new ArrayList<>();
request.add(attachment);
List<EmailName> emailNames = new ArrayList<>();
emailNames.add(new EmailName("john.doe@example.com",
"John Doe"));
TrackingOptions options =
new TrackingOptions("hey just testing", true, true, true);
SendMessageRequest requestBody =
new SendMessageRequest.Builder(emailNames).
trackingOptions(options).
subject("Hey Reaching Out with Nylas").
body("Hey I would like to track this link <a href='https://espn.com'>My Example Link</a>.").
attachments(request).
build();
Response<Message> email =
nylas.messages().send("<NYLAS_GRANT_ID>", requestBody);
System.out.println(email.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
import com.nylas.util.FileUtils
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val attachment: CreateAttachmentRequest = FileUtils.attachFileRequestBuilder("src/main/kotlin/Nylas_Logo.png")
val options = TrackingOptions("hey just testing", true, true, true)
val emailNames : List<EmailName> = listOf(EmailName("john.doe@example.com",
"John Doe"))
val requestBody : SendMessageRequest =
SendMessageRequest.Builder(emailNames).
subject("Hey Reaching Out with Nylas").
body("Hey I would like to track this link <a href='https://espn.com'>My Example Link</a>").
trackingOptions(options).
attachments(listOf(attachment)).
build()
val email = nylas.messages().send("<NYLAS_GRANT_ID>",
requestBody)
print(email.data)
}
/v3/grants/{grant_id}/messages/schedules:
get:
tags:
- Messages
x-scopes:
google:
min: ''
others: ''
microsoft:
min: ''
others: ''
summary: Return scheduled messages
description: Returns a list of scheduled messages. You can retrieve both sent and unsent messages.
operationId: get-schedules
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
responses:
'200':
$ref: '#/components/responses/200_schedules'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/schedules' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchMessageSchedules() {
try {
const identifier = "<NYLAS_GRANT_ID>";
const messageSchedules = await nylas.messages.listScheduledMessages({
identifier,
});
console.log("Message Schedules:", messageSchedules);
} catch (error) {
console.error("Error fetching message schedules:", error);
}
}
fetchMessageSchedules();
- lang: python
label: Python SDK
source: |-
import sys
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
messages = nylas.messages.list_scheduled_messages(
grant_id
)
print(messages)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\t api_key: \"<NYLAS_API_KEY>\"\n)\n\nmessages, _ = nylas.messages.list_scheduled_messages(identifier: \"<NYLAS_GRANT_ID>\")\n\nmessages.each {|message|\n puts message\n}"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReturnMessage {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<ScheduledMessage> message = nylas.messages().listScheduledMessages("<NYLAS_GRANT_ID>");
System.out.println(message.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val messages = nylas.messages().listScheduledMessages("<NYLAS_GRANT_ID>").data
print(messages)
}
/v3/grants/{grant_id}/messages/schedules/{scheduleId}:
parameters:
- name: grant_id
in: path
schema:
type: string
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
get:
tags:
- Messages
x-scopes:
google:
min: ''
others: ''
microsoft:
min: ''
others: ''
summary: Return a scheduled message
description: Returns the specified scheduled message. You can retrieve both sent and unsent messages.
operationId: get-schedule-by-id
parameters:
- name: scheduleId
in: path
schema:
type: string
required: true
description: The ID of the scheduled message that you want to retrieve.
responses:
'200':
$ref: '#/components/responses/200_schedule_id'
'404':
$ref: '#/components/responses/404'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/schedules/<SCHEDULE_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const NylasConfig = {
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
};
const nylas = new Nylas(NylasConfig);
async function fetchScheduledMessageById() {
try {
const events = await nylas.messages.findScheduledMessage({
identifier: "<NYLAS_GRANT_ID>",
scheduleId: "<SCHEDULE_ID>",
});
console.log("Events:", events);
} catch (error) {
console.error("Error fetching calendars:", error);
}
}
fetchScheduledMessageById();
- lang: python
label: Python SDK
source: |-
import sys
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
schedule_id = "<SCHEDULE_ID>"
event = nylas.messages.find_scheduled_message(
grant_id,
schedule_id,
)
print(event)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\t api_key: \"<NYLAS_API_KEY>\"\n)\n\nmessages, _ = nylas.messages.find_scheduled_messages(\n identifier: \"<NYLAS_GRANT_ID>\",\n schedule_id: \"<SCHEDULE_ID>\")\n\nmessages.each {|message|\n puts message\n}"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReturnMessage {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<ScheduledMessage> message = nylas.messages().findScheduledMessage(
"<NYLAS_GRANT_ID>",
"<SCHEDULED_MESSAGE_ID>");
System.out.println(message.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val messages = nylas.messages().findScheduledMessage(
"<NYLAS_GRANT_ID>",
"<SCHEDULED_MESSAGE_ID").data
print(messages)
}
delete:
tags:
- Messages
x-scopes:
google:
min: ''
others: ''
microsoft:
min: ''
others: ''
summary: Cancel a scheduled message
description: |-
Cancels the send schedule for a scheduled message. You can use this endpoint up to 10 seconds before
the message has reached its `send_at` time. If you make a `DELETE` request less than 10 seconds
before the `send_at` time, Nylas cannot guarantee the schedule will be cancelled successfully.
operationId: delete-a-scheduled-message
parameters:
- in: path
name: scheduleId
schema:
type: string
required: true
description: The ID of the send schedule you want to cancel.
responses:
'202':
$ref: '#/components/responses/202_schedules_delete'
'404':
$ref: '#/components/responses/404'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/schedules/<SCHEDULE_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const NylasConfig = {
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
};
const nylas = new Nylas(NylasConfig);
async function deleteMessageSchedule() {
try {
const result = await nylas.messages.stopScheduledMessage({
identifier: "<NYLAS_GRANT_ID>",
scheduleId: "<SCHEDULE_ID>",
});
console.log("Result:", result);
} catch (error) {
console.error("Error deleting message:", error);
}
}
deleteMessageSchedule();
- lang: python
label: Python SDK
source: |-
import sys
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
schedule_id = "<SCHEDULE_ID>"
result = nylas.messages.stop_scheduled_message(
grant_id,
schedule_id,
)
print(result)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\t api_key: \"<NYLAS_API_KEY>\"\n)\n\nmessages, _ = nylas.messages.stop_scheduled_messages(\n identifier: \"<NYLAS_GRANT_ID>\",\n schedule_id: \"<SCHEDULE_ID>\")\n\nmessages.each {|message|\n puts message\n}"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReturnMessage {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<StopScheduledMessageResponse> message = nylas.messages().stopScheduledMessage(
"<NYLAS_GRANT_ID>",
"SCHEDULED_MESSAGE_ID",
null);
System.out.println(message.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val messages = nylas.messages().stopScheduledMessage(
"<NYLAS_GRANT_ID>",
"SCHEDULED_MESSAGE_ID").data
print(messages)
}
/v3/grants/{grant_id}/messages/smart-compose:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
post:
summary: Compose a message
tags:
- Smart compose
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.ReadWrite.Shared
- https://graph.microsoft.com/Mail.Read.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/smart_compose_200'
'400':
$ref: '#/components/responses/smart_compose_400'
'401':
$ref: '#/components/responses/401'
'422':
$ref: '#/components/responses/smart_compose_422'
'500':
$ref: '#/components/responses/smart_compose_500'
operationId: post-smart-compose
description: Generates a message based on a prompt.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/smart_compose'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function composeEmail() {
try {
const message = await nylas.messages.smartCompose.composeMessage({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
prompt: "Tell my colleague how we can use Nylas APIs",
},
});
console.log("Message created:", message);
} catch (error) {
console.error("Error creating message:", error);
}
}
composeEmail();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
email = "<EMAIL>"
message = nylas.messages.smart_compose.compose_message(
grant_id,
request_body={
"prompt": "Tell my colleague how we can use Nylas APIs",
}
)
print(message)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
prompt: "Let's talk about Nylas"
}
message, _ = nylas.messages.smart_compose.compose_message(
identifier: "<NYLAS_GRANT_ID>",
request_body: request_body
)
puts message[:suggestion]
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class SmartCompose {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ComposeMessageRequest requestBody = new ComposeMessageRequest("Let's talk about Nylas");
Response<ComposeMessageResponse> message = nylas.messages().smartCompose().composeMessage("<NYLAS_GRANT_ID>", requestBody);
System.out.println(message.getData().getSuggestion());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.ComposeMessageRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val requestBody : ComposeMessageRequest = ComposeMessageRequest("Let's talk about Nylas")
val message = nylas.messages().smartCompose().composeMessage("<NYLAS_GRANT_ID>", requestBody)
print(message.data.suggestion)
}
/v3/grants/{grant_id}/messages/{message_id}/smart-compose:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: message_id
in: path
required: true
description: |-
ID of the message to access. Nylas recommends you URL-encode this field, or you might receive
a [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
post:
summary: Compose a reply
tags:
- Smart compose
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.ReadWrite.Shared
- https://graph.microsoft.com/Mail.Read.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/smart_compose_200'
'400':
$ref: '#/components/responses/smart_compose_400'
'401':
$ref: '#/components/responses/401'
'422':
$ref: '#/components/responses/smart_compose_422'
'500':
$ref: '#/components/responses/smart_compose_500'
operationId: post-smart-compose-reply
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/smart_compose'
description: Generates a reply to the specified message based on a prompt.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function composeEmailReply() {
try {
const message = await nylas.messages.smartCompose.composeMessageReply({
identifier: "<NYLAS_GRANT_ID>",
messageId: "<MESSAGE_ID>",
requestBody: {
prompt: "Respond to the email",
},
});
console.log("Message created:", message);
} catch (error) {
console.error("Error creating message:", error);
}
}
composeEmailReply();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
message_id = "<MESSAGE_ID>"
message = nylas.messages.smart_compose.compose_message_reply(
grant_id,
message_id,
request_body={
"prompt": "Respond to the email",
}
)
print(message)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
prompt: 'reply'
}
message, _ = nylas.messages.smart_compose.compose_message_reply(
identifier: "<NYLAS_GRANT_ID>",
message_id: "<MESSAGE_ID>",
request_body: request_body
)
puts message[:suggestion]
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class SmartCompose {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ComposeMessageRequest requestBody = new ComposeMessageRequest("Reply");
Response<ComposeMessageResponse> message =
nylas.messages().smartCompose().composeMessageReply("<NYLAS_GRANT_ID>",
"<MESSAGE_ID>", requestBody);
System.out.println(message.getData().getSuggestion());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.ComposeMessageRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val requestBody : ComposeMessageRequest =
ComposeMessageRequest("Reply")
val message = nylas.messages().smartCompose().composeMessageReply("<NYLAS_GRANT_ID>",
"<MESSAGE_ID>", requestBody)
print(message.data.suggestion)
}
/v3/domains/{domain_name}/messages/send:
parameters:
- name: domain_name
in: path
schema:
type: string
required: true
description: |-
The verified sender domain Nylas will send the message from. This path parameter is separate from
`tracking_options.domain_name`, which selects the hostname for link click and message open
tracking.
example: sender.example.com
- in: header
name: Idempotency-Key
schema:
type: string
maxLength: 256
required: false
description: |-
A unique, client-generated key (max 256 characters) that lets you safely retry this send request
without sending duplicate emails. Nylas caches the response (success or error) for 1 hour, scoped
per Nylas application (not per domain -- a key collides across all verified domains under the same
application). A retry with the same key and payload returns the cached response with the
`Idempotent-Response: true` header set. See
[Idempotent send requests](/docs/v3/email/idempotent-send/) for the full retry behavior and
error responses.
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
post:
summary: Send a transactional email
tags:
- Transactional send
operationId: send-transactional-email
x-beta: true
description: |-
Sends a message from the specified domain. You can track deliverability (delivered, bounced, complaint, rejected) using [Nylas' notifications](/docs/reference/notifications/#transactional-email-notifications).
The route's `domain_name` value is the verified sender domain. To use a different custom hostname
for link click or message open tracking, provide `tracking_options.domain_name` in the request
body. For example, you can send from `sender.example.com` and track through
`tracking.example.com`. Nylas validates scheduled custom tracking hostnames when you create the
schedule and revalidates them immediately before delivery. If an explicit hostname is no longer
eligible, the send fails without falling back to a Nylas hostname.
<div id="admonition-info">💡 <b>Emails landing in spam?</b> Consider <a href="/docs/v3/agent-accounts/domain-warming/">warming up your email domain</a> to improve deliverability.</div>
x-scopes: []
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from
- to
properties:
attachments:
type: array
description: An array of files to be sent with the message.
items:
type: object
properties:
content:
type: string
description: |-
The Base64-encoded file content. See
[Working with email attachments](/docs/v3/email/attachments/#attachment-schemas-and-size-limits)
for more information.
example: YXR0YWNoDQoNCi0tLS0tLS0tLS0gRm9yd2FyZGVkIG1lc3NhZ2UgL=
content_disposition:
type: string
description: |-
(Not supported for Microsoft and EWS) The content disposition of the file. Usually,
this is `inline` or `attachment`, followed by the file name.
example: attachment; filename="nylas_logo.png"
content_id:
type: string
description: |-
(Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the HTML
message body. To avoid unexpected behavior in threads, make sure to use unique CIDs
across messages of a thread.
example: ce9b9547-9eeb-43b2-ac4e-58768bdf04e4
content_type:
type: string
description: |-
The
[MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)
of the file. This is used by the email client to determine how to display the
attachment.
minLength: 1
example: image/png
filename:
type: string
description: The file name.
minLength: 1
example: nylas_logo.png
bcc:
type: array
description: A list of people to be BCC'd on the message.
items:
type: object
properties:
email:
type: string
description: The recipient's email address.
example: leyah@example.com
name:
type: string
description: The recipient's name.
example: Leyah Miller
body:
type: string
description: The HTML-formatted body of the message.
example: Looking forward to seeing you!
cc:
type: array
description: A list of people to be CC'd on the message.
items:
type: object
properties:
email:
type: string
description: The recipient's email address.
example: leyah@example.com
name:
type: string
description: The recipient's name.
example: Leyah Miller
custom_headers:
type: array
description: An array of custom headers to add to the message.
items:
type: object
properties:
name:
type: string
description: The header name.
example: Email-Campaign
value:
type: string
description: The header value.
example: meetings
from:
type: object
description: Information about the person sending the message.
properties:
email:
type: string
description: |-
The sender's email address. Must belong to an email domain that's been verified
with Nylas.
example: nyla@example.com
name:
type: string
description: The sender's name.
example: Nyla
is_plaintext:
type: boolean
description: |-
When `true`, Nylas sends the message body as plain text and the MIME data doesn't
include an HTML version of the message. When `false`, Nylas sends the message body as
HTML.
default: false
example: true
metadata:
$ref: '#/components/schemas/metadata'
reply_to:
type: array
description: A list of people who should receive replies to the message by default.
items:
type: object
properties:
name:
type: string
description: The name of the person who should receive replies to the message.
example: Leyah Miller
email:
type: string
description: The email address of the person who should receive replies to the message.
example: leyah@example.com
reply_to_message_id:
type: string
description: |-
The ID of the message you are replying to. If you are using a message that was sent using Nylas'
Transactional Send, you may use the ID that was returned in the Nylas response. For all other
messages, this is the [RFC822](https://datatracker.ietf.org/doc/html/rfc822#section-4.6.1)
`Message-ID` header of the message you're replying to.
send_at:
type: integer
description: |-
The time when Nylas should send the message, in seconds using the Unix timestamp format.
Must be at least one minute in the future from the time you make your request. You can
schedule a message to be sent up to 30 days in the future. If the request includes
`tracking_options.domain_name`, Nylas validates the hostname when it creates the schedule
and revalidates it before delivery.
subject:
type: string
description: The subject line of the message.
example: 'Reminder: Annual Philosophy Club meeting'
template:
type: object
description: The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
properties:
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
to:
type: array
description: A list of recipients for the message.
items:
type: object
properties:
email:
type: string
description: The recipient's email address.
example: leyah@example.com
name:
type: string
description: The recipient's name.
example: Leyah Miller
tracking_options:
type: object
description: Tracking settings for the message. See [Track messages](/docs/v3/email/message-tracking/).
properties:
opens:
type: boolean
description: |-
When `true`, enables
[message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the
message. Nylas generates a
[`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications)
when a participant first opens the message.
default: false
links:
type: boolean
description: |-
When `true`, enables
[link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the
message. Nylas generates a
[`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications)
when a participant clicks a link in the message.
default: false
label:
type: string
description: |-
A brief description of the message, why it's being tracked, or the tracking options
enabled.
maxLength: 2048
domain_name:
$ref: '#/components/schemas/tracking_domain_name'
multipart/form-data:
schema:
type: object
properties:
attachment:
type: string
description: The content of the attachment (if available), in binary format.
format: binary
message:
type: object
properties:
bcc:
type: array
description: A list of people to be BCC'd on the message.
items:
type: object
properties:
email:
type: string
description: The recipient's email address.
example: leyah@example.com
name:
type: string
description: The recipient's name.
example: Leyah Miller
body:
type: string
description: The HTML-formatted body of the message.
example: Looking forward to seeing you!
cc:
type: array
description: A list of people to be CC'd on the message.
items:
type: object
properties:
email:
type: string
description: The recipient's email address.
example: leyah@example.com
name:
type: string
description: The recipient's name.
example: Leyah Miller
custom_headers:
type: array
description: An array of custom headers to add to the message.
items:
type: object
properties:
name:
type: string
description: The header name.
example: Email-Campaign
value:
type: string
description: The header value.
example: meetings
from:
type: object
description: Information about the person sending the message.
properties:
email:
type: string
description: |-
The sender's email address. Must belong to an email domain that's been verified
with Nylas.
example: nyla@example.com
name:
type: string
description: The sender's name.
example: Nyla
is_plaintext:
type: boolean
description: |-
When `true`, Nylas sends the message body as plain text and the MIME data doesn't
include an HTML version of the message. When `false`, Nylas sends the message body as
HTML.
default: false
example: true
metadata:
$ref: '#/components/schemas/metadata'
reply_to:
type: array
description: A list of people who should receive replies to the message by default.
items:
type: object
properties:
name:
type: string
description: The name of the person who should receive replies to the message.
example: Leyah Miller
email:
type: string
description: The email address of the person who should receive replies to the message.
example: leyah@example.com
reply_to_message_id:
type: string
description: |-
The ID of the message you are replying to. If you are using a message that was sent using Nylas'
Transactional Send, you may use the ID that was returned in the Nylas response. For all other
messages, this is the [RFC822](https://datatracker.ietf.org/doc/html/rfc822#section-4.6.1)
`Message-ID` header of the message you're replying to.
send_at:
type: integer
description: |-
The time when Nylas should send the message, in seconds using the Unix timestamp format.
Must be at least one minute in the future from the time you make your request. You can
schedule a message to be sent up to 30 days in the future. If the request includes
`tracking_options.domain_name`, Nylas validates the hostname when it creates the schedule
and revalidates it before delivery.
subject:
type: string
description: The subject line of the message.
example: 'Reminder: Annual Philosophy Club meeting'
template:
type: object
description: The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
properties:
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
to:
type: array
description: A list of recipients for the message.
items:
type: object
properties:
email:
type: string
description: The recipient's email address.
example: leyah@example.com
name:
type: string
description: The recipient's name.
example: Leyah Miller
tracking_options:
type: object
description: Tracking settings for the message. See [Track messages](/docs/v3/email/message-tracking/).
properties:
opens:
type: boolean
description: |-
When `true`, enables
[message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the
message. Nylas generates a
[`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications)
when a participant first opens the message.
default: false
links:
type: boolean
description: |-
When `true`, enables
[link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the
message. Nylas generates a
[`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications)
when a participant clicks a link in the message.
default: false
label:
type: string
description: |-
A brief description of the message, why it's being tracked, or the tracking options
enabled.
maxLength: 2048
domain_name:
$ref: '#/components/schemas/tracking_domain_name'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/domains/<DOMAIN_NAME>/messages/send' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"to": [{
"name": "Jane Doe",
"email": "jane.doe@example.com"
}],
"from": {
"name": "ACME Support",
"email": "support@acme.com"
},
"subject": "Welcome to ACME",
"body": "Welcome to ACME! We'\''re here to help you."
}'
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
message = nylas.transactional_send.send(
domain_name="<DOMAIN_NAME>",
request_body={
"to": [{"name": "Jane Doe", "email": "jane.doe@example.com"}],
"from_": {"name": "ACME Support", "email": "support@acme.com"},
"subject": "Welcome to ACME",
"body": "Welcome to ACME! We're here to help you.",
},
)
print(message)
responses:
'200':
description: Success. Returns message.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/transactional_send_message'
request_id:
type: string
description: The request ID.
example: 9ca1d434-5ac7-4331-b8fb-3749c9a758d3
'400':
$ref: '#/components/responses/400'
'409':
$ref: '#/components/responses/409_idempotent'
/v3/grants/{grant_id}/signatures:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
get:
summary: Return all signatures
tags:
- Signatures
x-scopes: {}
responses:
'200':
$ref: '#/components/responses/signatures'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: list-signatures
description: Return all signatures for a grant.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/field_selection'
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
post:
summary: Create a signature
operationId: post-signature
description: |-
Create a signature for a grant. Each grant can have up to 10 signatures.
Nylas sanitizes the HTML content on input to prevent malicious content. Images must use
externally hosted URLs (base64 inline images are not supported). Maximum signature size is 100 KB.
tags:
- Signatures
x-scopes: {}
requestBody:
$ref: '#/components/requestBodies/signature_create'
responses:
'201':
$ref: '#/components/responses/signature'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"name": "Work Signature",
"body": "<div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p><p><a href=\"mailto:nick@nylas.com\">nick@nylas.com</a></p></div>"
}'
/v3/grants/{grant_id}/signatures/{signature_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: signature_id
in: path
required: true
description: ID of the signature to access.
get:
summary: Return a signature
tags:
- Signatures
x-scopes: {}
responses:
'200':
$ref: '#/components/responses/signature'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-signature
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
description: Return a signature by ID.
parameters:
- $ref: '#/components/parameters/field_selection'
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
put:
summary: Update a signature
tags:
- Signatures
x-scopes: {}
responses:
'200':
$ref: '#/components/responses/signature'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: put-signature
description: |-
Update the specified signature. You can update the `name`, `body`, or both. The signature ID
does not change.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
requestBody:
$ref: '#/components/requestBodies/signature_update'
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"name": "Updated Work Signature",
"body": "<div><p><strong>Nick Barraclough</strong></p><p>Senior Product Manager | Nylas</p><p><a href=\"mailto:nick@nylas.com\">nick@nylas.com</a></p></div>"
}'
delete:
summary: Delete a signature
tags:
- Signatures
x-scopes: {}
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: delete-signature
description: |-
Permanently delete a signature. Signatures are also automatically deleted when the parent grant
is deleted.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
/v3/grants/{grant_id}/drafts:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
get:
summary: Return all Drafts
operationId: get-drafts
description: Return all drafts in the user's Drafts folder.
tags:
- Drafts
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.compose
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.Read.Shared
- https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r
responses:
'200':
$ref: '#/components/responses/drafts'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/metadata_pair'
- $ref: '#/components/parameters/field_selection'
- name: subject
in: query
schema:
type: string
description: Return items with a matching subject. The filter is case insensitive and will match partial subjects.
- name: any_email
in: query
description: |-
Return messages that have been sent or received from this comma-separated list of email
addresses (for example, `mail1@example.com,mail2@example.com`). You can specify a maximum of
25 email addresses.
schema:
type: string
- name: to
in: query
description: Return items containing messages sent to this email address.
schema:
type: string
- name: cc
in: query
description: Return items containing messages that were CC'd to this email address.
schema:
type: string
- name: bcc
in: query
description: Return items containing messages that were BCC'd to this email address, likely sent from the parent account. (Most SMTP gateways remove BCC information, so this appears only if the user sent the email message, or received it because they were on the BCC list.)
schema:
type: string
- name: starred
in: query
description: |-
Return items with one or more starred messages. For EWS, this is only supported for Microsoft
Exchange 2010 or later.
schema:
type: boolean
- name: thread_id
in: query
description: Return items with a matching `thread_id`.
schema:
type: string
- name: has_attachment
in: query
description: Return items with attachments.
schema:
type: boolean
- $ref: '#/components/parameters/query_imap_list'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchDrafts() {
try {
const identifier = "<NYLAS_GRANT_ID>";
const threads = await nylas.drafts.list({
identifier,
});
console.log("Recent Drafts:", threads);
} catch (error) {
console.error("Error fetching drafts:", error);
}
}
fetchDrafts();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
drafts = nylas.drafts.list(
grant_id,
)
print(drafts)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\ndrafts, _ = nylas.drafts.list(identifier: \"<NYLAS_GRANT_ID>\")\ndrafts.each {|draft|\n\tputs \"[#{Time.at(draft[:date]).strftime(\"%d/%m/%Y at %H:%M:%S\")}] | \\\n#{draft[:id]} | \\\n#{draft[:subject]} | \\\n#{draft[:folders]}\"\n}\n"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.text.SimpleDateFormat;
public class ListDraft {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Draft> drafts = nylas.drafts().list("<NYLAS_GRANT_ID>");
for (Draft draft : drafts.getData()){
String date = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").
format(new java.util.Date((draft.getDate() * 1000L)));
System.out.printf("[ %s] | %s | %s | %s",
date, draft.getId(), draft.getSubject(), draft.getFolders());
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
import java.text.SimpleDateFormat
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val simpleDateFormat = SimpleDateFormat("dd MMMM yyyy, HH:mm:ss")
val drafts = nylas.drafts().list("<NYLAS_GRANT_ID>")
for(draft in drafts.data){
println("[${simpleDateFormat.format(draft.date * 1000L)}] | " +
"${draft.id} | ${draft.subject} | ${draft.folders}")
}
}
post:
summary: Create a Draft
tags:
- Drafts
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.compose
others: ''
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/draft'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: post-draft
description: |-
Creates a draft.
If you provide `tracking_options.domain_name`, Nylas validates the custom hostname and stores its
canonical value with the draft's link click and message open tracking settings. If you omit the
field, Nylas uses its regional tracking hostname when it creates tracking URLs.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/draft_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"subject": "With Love, From Nylas",
"to": [{
"email": "leyah@example.com",
"name": "Leyah Miller"
}],
"cc": [{
"email": "nyla@example.com",
"name": "Nyla"
}],
"bcc": [{
"email": "nylas-devrel@example.com",
"name": "Nylas DevRel"
}],
"reply_to": [{
"email": "nylas@example.com",
"name": "Nylas"
}],
"body": "This email was sent using the Nylas Email API. Visit https://nylas.com for details.",
"tracking_options": {
"opens": true,
"links": true,
"thread_replies": true,
"label": "Just testing"
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const createDraft = async () => {
try {
const draft = {
subject: "Your Subject Here",
to: [{ name: "Recipient Name", email: "recipient@example.com" }],
body: "Your email body here.",
};
const createdDraft = await nylas.drafts.create({
identifier,
requestBody: draft,
});
console.log("Draft created:", createdDraft);
} catch (error) {
console.error("Error creating draft:", error);
}
};
createDraft();
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas import utils
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
email = "<EMAIL>"
attachment = utils.file_utils.attach_file_request_builder("Nylas_Logo.png")
draft = nylas.drafts.create(
grant_id,
request_body={
"to": [{ "name": "Name", "email": email }],
"reply_to": [{ "name": "Name", "email": email }],
"subject": "Your Subject Here",
"body": "Your email body here.",
"attachments": [attachment]
}
)
print(draft)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nfile = Nylas::FileUtils.attach_file_request_builder(\"Nylas_Logo.png\")\n\nrequest_body = {\n subject: \"From Nylas\",\n body: 'This email was sent using the ' +\n 'Nylas email API. ' + \n 'Visit https://nylas.com for details.',\n to: [{ name: \"Dorothy Vaughan\", \n email: \"dorothy@example.com\"}],\n cc: [{ name: \"George Washington Carver\", \n email: \"carver@example.com\"}],\n bcc: [{ name: \"Albert Einstein\", \n email: \"al@example.com\"}],\n reply_to: [{ name: \"Stephanie Kwolek\", \n email: \"skwolek@example.com\"}],\n tracking_options: {label: \"hey just testing\", \n opens: true, \n links: true,\n thread_replies: true},\n attachments: [file] \n}\n\ndraft, _ = nylas.drafts.create(identifier: \"<NYLAS_GRANT_ID>\", request_body: request_body)\nputs \"Draft \\\"#{draft[:subject]}\\\" was created with ID: #{draft[:id]}\"\n"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import com.nylas.util.FileUtils;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
public class CreateDraft {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CreateAttachmentRequest attachment = FileUtils.attachFileRequestBuilder("src/main/java/Nylas_Logo.png");
List<CreateAttachmentRequest> request = new ArrayList<>();
request.add(attachment);
CreateDraftRequest requestBody = new CreateDraftRequest.Builder().
to(Collections.singletonList(new EmailName("swag@example.com", "Nylas"))).
cc(Collections.singletonList(new EmailName("dorothy@example.com", "Dorothy Vaughan"))).
bcc(Collections.singletonList(new EmailName("Lamarr@example.com", "Hedy Lamarr"))).
subject("With Love, from Nylas").
body("This email was sent using the Nylas email API. Visit https://nylas.com for details.").
attachments(request).
build();
Response<Draft> drafts = nylas.drafts().create("<NYLAS_GRANT_ID>", requestBody);
System.out.println("Draft " + drafts.getData().getSubject() +
" was created with ID " + drafts.getData().getId());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
import com.nylas.util.FileUtils
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val attachment: CreateAttachmentRequest = FileUtils.attachFileRequestBuilder("src/main/kotlin/Nylas_Logo.png")
val requestBody = CreateDraftRequest(
to = listOf(EmailName("swag@example.com", "Nylas")),
cc = listOf(EmailName("dorothy@example.com", "Dorothy Vaughan")),
bcc = listOf(EmailName("Lamarr@example.com", "Hedy Lamarr")),
subject = "With Love, from Nylas",
body = "This email was sent using the Nylas Email API. Visit https://nylas.com for details.",
attachments = listOf(attachment)
)
val draft = nylas.drafts().create("<NYLAS_GRANT_ID>", requestBody).data
print("Draft " + draft.subject + " was created with ID: " + draft.id)
}
/v3/grants/{grant_id}/drafts/{draft_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: draft_id
in: path
required: true
description: |-
ID of the draft to access. Nylas recommends you URL-encode this field, or you might receive a
[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
get:
summary: Return a Draft
tags:
- Drafts
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.compose
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.Read.Shared
- https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r
responses:
'200':
$ref: '#/components/responses/draft'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-draft-id
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/query_imap_get_by_id'
description: Return a draft by ID.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchDraftById() {
try {
const events = await nylas.drafts.find({
identifier: "<NYLAS_GRANT_ID>",
draftId: "<DRAFT_ID>",
});
console.log("Events:", events);
} catch (error) {
console.error("Error fetching calendars:", error);
}
}
fetchDraftById();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
draft_id = "<DRAFT_ID>"
draft = nylas.drafts.find(
grant_id,
draft_id,
)
print(draft)
- lang: ruby
label: Ruby SDK
source: "# Load gems\nrequire 'nylas'\t\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\ndraft, _ = nylas.drafts.find(identifier: \"<NYLAS_GRANT_ID>\", draft_id: \"<DRAFT_ID>\")\n\nputs draft"
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ListDraft {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Draft> draft = nylas.drafts().find("<NYLAS_GRANT_ID>", "<DRAFT_ID>");
assert draft.getData().getTo() != null;
System.out.printf(" %s | %s | %s",
draft.getData().getId(),
draft.getData().getTo().get(0).getEmail(),
draft.getData().getSubject());
}
}
- lang: kotlin
label: Kotlin SDK
source: "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>) {\n\tval nylas: NylasClient = NylasClient(\n\t\t\tapiKey = \"<NYLAS_API_KEY>\"\n\t)\n\n\tval draft = nylas.drafts().find(\"<NYLAS_GRANT_ID>\", \"<DRAFT_ID>\")\n\n\tprintln(\"${draft.data.id} | \" +\n\t\t\t\"${draft.data.to?.get(0)?.email} | \" +\n\t\t\t\"${draft.data.subject}\")\n}"
put:
summary: Update a draft
tags:
- Drafts
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.compose
others: ''
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/draft'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: put-drafts-id
description: |-
Updates the specified draft.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
For tracking settings, an explicit `tracking_options.domain_name` replaces the draft's previous
custom tracking hostname after validation. If you omit `domain_name` while updating other tracking
options, the draft inherits its existing custom hostname. Disabling both `links` and `opens` clears
the stored hostname. If you enable either option again without a hostname, Nylas uses its regional
tracking hostname.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
requestBody:
$ref: '#/components/requestBodies/draft_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"starred": true
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateDraft() {
try {
const calendar = await nylas.drafts.update({
identifier: "<NYLAS_GRANT_ID>",
draftId: "<DRAFT_ID>",
requestBody: {
starred: true,
},
});
console.log("Updated Draft:", calendar);
} catch (error) {
console.error("Error to update draft:", error);
}
}
updateDraft();
- lang: python
label: Python SDK
source: |
from nylas import Client
from nylas.utils.file_utils import attach_file_request_builder
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
attachment = attach_file_request_builder("Nylas_Logo.png")
draft = nylas.drafts.update(
"<NYLAS_GRANT_ID>",
draft_id="<DRAFT_ID>",
request_body={
"subject": "Updated Subject",
"attachments": [attachment]
}
)
print(draft)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nfile = Nylas::FileUtils.attach_file_request_builder(\"Nylas_Logo.png\")\n\nrequest_body = {\n starred: true,\n attachments: [file]\n}\n\ndraft, _ = nylas.drafts.update(identifier: \"<NYLAS_GRANT_ID>\",\n draft_id: \"<DRAFT_ID>\",\n request_body: request_body)\n\nputs draft\n\n"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class UpdateDraft {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateDraftRequest requestBody =
new UpdateDraftRequest.
Builder().
starred(true).
build();
Response<Draft> draft = nylas.drafts().update("<NYLAS_GRANT_ID>",
"<DRAFT_ID>", requestBody);
System.out.printf("%s%s%s%n",
draft.getData().getId(),
draft.getData().getStarred());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
import com.nylas.util.FileUtils
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val attachment: CreateAttachmentRequest = FileUtils.attachFileRequestBuilder("src/main/kotlin/Nylas_Logo.png")
val requestBody = UpdateDraftRequest(
attachments = listOf(attachment)
)
val draft = nylas.drafts().update(identifier = "<NYLAS_GRANT_ID>", draftId = "<NYLAS_DRAFT_ID>", requestBody = requestBody)
println(draft)
}
delete:
summary: Delete a Draft
tags:
- Drafts
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.compose
others: ''
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: delete-drafts-id
description: Permanently deletes the specified draft.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const draftId = "<DRAFT_ID>";
const deleteDraft = async () => {
try {
await nylas.drafts.destroy({ identifier, draftId });
console.log(`Draft with ID ${draftId} deleted successfully.`);
} catch (error) {
console.error(`Error deleting contact with ID ${draftId}:`, error);
}
};
deleteDraft();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
api_key = "<NYLAS_API_KEY>"
)
drafts = nylas.drafts.destroy("<NYLAS_GRANT_ID>", "<DRAFT_ID>")
print(drafts)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
status, _ = nylas.drafts.destroy(identifier: "<NYLAS_GRANT_ID>", draft_id: "<DRAFT_ID>")
if status
puts "Draft successfully deleted"
end
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class SendDraft {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse draft =
nylas.drafts().destroy("<NYLAS_GRANT_ID>", "<DRAFT_ID>");
System.out.println(draft.getRequestId());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val draft = nylas.drafts().destroy("<NYLAS_GRANT_ID>", "<DRAFT_ID>")
print(draft.requestId)
}
post:
summary: Send a Draft
tags:
- Drafts
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.compose
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.Send
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/draft'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
operationId: send-draft-id
description: |-
Sends the specified draft as a message. You can optionally include a `signature_id` to append a
[signature](/docs/v3/email/signatures/) to the message body at send time.
requestBody:
content:
application/json:
schema:
type: object
properties:
signature_id:
type: string
description: |-
The ID of a [signature](/docs/v3/email/signatures/) to append to the message body when
sending. Nylas inserts the signature after a line break at the end of the body, including
after any quoted text. Only use this if the draft was created without a signature, or if
you want to add one at send time.
example: sig_abc123
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const draftId = "<DRAFT_ID>";
const sendDraft = async () => {
try {
const sentMessage = await nylas.drafts.send({ identifier, draftId });
console.log("Draft sent:", sentMessage);
} catch (error) {
console.error("Error sending draft:", error);
}
};
sendDraft();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
draft_id = "<DRAFT_ID>"
draft = nylas.drafts.send(
grant_id,
draft_id
)
print(draft)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\ndraft, _ = nylas.drafts.send(identifier: \"<NYLAS_GRANT_ID>\", draft_id: \"<DRAFT_ID>\")"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class SendDraft {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Message> draft =
nylas.drafts().send("<NYLAS_GRANT_ID>", "<DRAFT_ID>");
System.out.println(draft.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val draft = nylas.drafts().send("<NYLAS_GRANT_ID>", "<DRAFT_ID>")
print(draft.data)
}
/v3/grants/{grant_id}/threads:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
get:
summary: Return all threads
tags:
- Threads
operationId: get-threads
description: |-
Returns all threads.
For Microsoft, IMAP, iCloud, Yahoo, and EWS, threads are ordered reverse chronologically by the latest message received.
For Google, thread ordering is not guaranteed to be reverse chronological due to a Gmail API limitation.
However, setting the `in` query parameter improves the likelihood of reverse chronological ordering significantly (approximately 40%).
While reverse chronological ordering remains unguaranteed even with the `in` parameter, we recommend using it to increase the chance of this ordering pattern.
<div id="admonition-warning">
⚠️ <b>Your users might receive a large number of threaded messages</b>. If you encounter
<a href="/docs/api/errors/400-response/"><code>429</code> errors</a> or provider
<a href="/docs/dev-guide/platform/rate-limits/">rate limits</a> when listing all threads, Nylas
recommends you set the <code>limit</code> parameter to 20 and add
<a href="#query-parameters">query parameters</a> to your request to
limit the results.</div>
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.Read.Shared
- https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- name: any_email
schema:
type: string
in: query
description: |-
Filter for threads that contain messages sent to or received from the email addresses in the
comma-separated list. You may specify a maximum of 25 email addresses per query.
example: mail1@example.com,mail2@example.com
- name: bcc
schema:
type: string
in: query
description: |-
Filter for threads that contain messages BCC'd to the specified email address. Because most
SMTP gateways remove BCC information from sent messages, any messages that Nylas returns are
likely sent from the parent account.
For Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of
this query parameter. This is because of a limitation on the provider. Instead, you can use
the `thread_id` to retrieve a specific conversation.
- name: cc
schema:
type: string
in: query
description: |-
Filter for threads that contain messages CC'd to the specified email address.
For Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of
this query parameter. This is because of a limitation on the provider. Instead, you can use
the `thread_id` to retrieve a specific conversation.
- name: from
schema:
type: string
in: query
description: |-
Filter for threads that include messages sent from the specified email address. If you want
to filter for threads that include messages sent from the current grant, use the `in` query
parameter and specify the Sent folder instead.
For Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of
this query parameter. This is because of a limitation on the provider. Instead, you can use
the `thread_id` to retrieve a specific conversation.
- name: has_attachment
schema:
type: boolean
default: false
in: query
description: When `true`, filters for threads that include attachments.
- name: in
schema:
type: string
in: query
description: |-
Return messages in the specified folder or label, by folder ID.
Required when using `shared_from`.
- name: earliest_message_date
schema:
type: integer
in: query
description: |-
Returns the date when the earliest or first message in the thread was sent or received, in Unix
timestamp format.
- name: latest_message_after
schema:
type: integer
in: query
description: |-
Filter for threads whose most recent message was received after the specified time, in Unix
timestamp format.
- name: latest_message_before
schema:
type: integer
in: query
description: |-
Filter for threads whose most recent message was received before the specified time, in Unix
timestamp format.
- name: limit
schema:
type: integer
default: 20
maximum: 50
in: query
description: |-
The maximum number of objects to return. See [pagination](/docs/reference/api/#pagination)
for more information.
required: false
- $ref: '#/components/parameters/page_token'
- name: search_query_native
schema:
type: string
in: query
description: |-
Specify a URL-encoded search query. Connected providers use their provider-specific syntax,
while Nylas Agent Accounts use Nylas full-text search syntax. The query parameters that you can
use alongside `search_query_native` depend on the provider:
- **Google**: `in`, `limit`, and `page_token`
- **Microsoft**: `in`, `limit`, and `page_token`
- **IMAP/Yahoo/iCloud**: Any parameter
- **EWS**: Any parameter _except_ `thread_id`
- **Nylas Agent Accounts**: Any other parameter supported for Agent Accounts by this endpoint
For an overview of searching messages and threads with `search_query_native` across providers,
see [Searching with Nylas](/docs/dev-guide/best-practices/search/#search-messages-and-threads-using-search_query_native).
If you're using a Nylas Agent Account, see
[Email search for Agent Accounts](/docs/v3/agent-accounts/email-search/) for the complete Nylas
search syntax, examples, and limits.
examples:
Agent Account:
description: Nylas full-text query for threads that contain "charger" or "station".
value: charger%20OR%20station
Google:
description: Google query string for threads with subject "foo" or "bar".
value: subject%3Afoo%20OR%20subject%3Abar
Microsoft:
description: Microsoft Graph query for threads using the `$filter` syntax.
value: '%24filter%3Dfrom%2FemailAddress%2Faddress%20eq%20%27someuser%40example.com%27'
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/shared_folder_id'
- $ref: '#/components/parameters/shared_from'
- name: starred
schema:
type: boolean
in: query
description: Filter for threads that contain one or more starred messages.
- name: subject
schema:
type: string
in: query
description: |-
Return threads that contain messages with a matching subject. This filter is case-sensitive
and returns partial matches.
- name: to
schema:
type: string
in: query
description: |-
Filter for threads that contain messages sent to the specified email address.
For Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of
this query parameter. This is because of a limitation on the provider. Instead, you can use
the `thread_id` to retrieve a specific conversation.
- name: unread
schema:
type: boolean
in: query
description: Filter for threads that contain one or more unread messages.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads?limit=5" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchRecentThreads() {
try {
const identifier = "<NYLAS_GRANT_ID>";
const threads = await nylas.threads.list({
identifier: identifier,
queryParams: {
limit: 5,
},
});
console.log("Recent Threads:", threads);
} catch (error) {
console.error("Error fetching threads:", error);
}
}
fetchRecentThreads();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
threads = nylas.threads.list(
grant_id,
query_params={
"limit": 5
}
)
print(threads)
- lang: ruby
label: Ruby SDK
source: |-
require 'nylas'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
query_params = { limit: 5 }
threads, _ = nylas.threads.list(identifier: "<NYLAS_GRANT_ID>", query_params: query_params)
threads.map.with_index { |thread, i|
puts("Thread #{i}")
participants = thread[:participants]
participants.each{ |participant|
puts(
"Subject: #{thread[:subject]} | "\
"Participant: #{participant[:name]} | "\
"Email: #{participant[:email]}"
)
}
}
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
import com.nylas.models.Thread;
import java.util.List;
public class ReadThreadParameters {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListThreadsQueryParams queryParams = new ListThreadsQueryParams.Builder().limit(5).build();
ListResponse<Thread> threads = nylas.threads().list("<NYLAS_GRANT_ID>", queryParams);
int index = 0;
for(Thread thread : threads.getData()){
System.out.printf("%s ", index);
List<EmailName> participants = thread.getParticipants();
assert participants != null;
for(EmailName participant : participants){
System.out.printf(" Subject: %s | Participant: %s | Email: %s%n",
thread.getSubject(),
participant.getName(),
participant.getEmail());
}
index++;
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.*
import java.util.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val queryParams = ListThreadsQueryParams(limit = 5)
val threads : List<Thread> = nylas.threads().list("<CALENDAR_ID>", queryParams).data
for(i in threads.indices){
print("$i ")
val participants = threads[i].participants
if (participants != null) {
for(participant in participants){
println(" Subject: ${threads[i].subject} + " +
"Name: ${participant.name} + " +
"Email: ${participant.email}")
}
}
}
}
responses:
'200':
$ref: '#/components/responses/threads'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/grants/{grant_id}/threads/{thread_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: thread_id
in: path
required: true
description: |-
ID of the thread to access. Nylas recommends you URL-encode this field, or you might receive a
[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
get:
summary: Return a thread
tags:
- Threads
responses:
'200':
$ref: '#/components/responses/thread'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-threads-id
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/shared_folder_id'
- $ref: '#/components/parameters/shared_from'
description: Returns the specified thread.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads/<THREAD_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchThreadById() {
try {
const thread = await nylas.threads.find({
identifier: "<NYLAS_GRANT_ID>",
threadId: "<THREAD_ID>",
});
console.log("Thread:", thread);
} catch (error) {
console.error("Error fetching thread:", error);
}
}
fetchThreadById();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
thread_id = "<THREAD_ID>"
thread = nylas.threads.find(
grant_id,
thread_id,
)
print(thread)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nthread, _ = nylas.threads.find(identifier: \"<NYLAS_GRANT_ID>\", \n thread_id: \"<THREAD_ID>\")\n\nparticipants = thread[:participants]\n\nparticipants.each{ |participant|\n puts(\"Id: #{thread[:id]} | \"\\\n \"Subject: #{thread[:subject]} | \"\\\n \"Participant: #{participant[:name]} | \"\\\n \"Email: #{participant[:email]}\"\n )\n}\n"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import com.nylas.models.Thread;
public class ReturnThread {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Thread> thread = nylas.threads().find("<NYLAS_GRANT_ID>",
"<THREAD_ID>");
System.out.println(thread);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val thread = nylas.threads().find("<NYLAS_GRANT_ID>", "<THREAD_ID>").data
print(thread)
}
put:
summary: Update a thread
tags:
- Threads
responses:
'200':
$ref: '#/components/responses/thread'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: put-threads-id
description: |-
Updates the specified thread.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/shared_folder_id'
- $ref: '#/components/parameters/shared_from'
requestBody:
$ref: '#/components/requestBodies/thread_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads/<THREAD_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"unread": true,
"starred": false,
"folders": ["<FOLDER_ID>"]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateThread() {
try {
const calendar = await nylas.threads.update({
identifier: "<NYLAS_GRANT_ID>",
threadId: "<THREAD_ID>",
requestBody: {
starred: true,
},
});
console.log("Updated Thread:", calendar);
} catch (error) {
console.error("Error to update thread:", error);
}
}
updateThread();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
thread = nylas.threads.update(
grant_id,
thread_id="<THREAD_ID>",
request_body={
"starred": True
}
)
print(thread)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n unread: true,\n starred: true\n}\n\nthread, _ = nylas.threads.update(identifier: \"<NYLAS_GRANT_ID>\", \n thread_id: \"<THREAD_ID>\",\n request_body: request_body)\n\nputs thread\n"
- lang: java
label: Java SDK
source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport com.nylas.models.Thread;\n\npublic class UpdateThread {\n\tpublic static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n\t\tNylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n\t\tUpdateThreadRequest requestBody =\n\t\t\t\tnew UpdateThreadRequest.\n\t\t\t\tBuilder().\n\t\t\t\tunread(true).\n\t\t\t\tstarred(true).\n\t\t\t\tbuild();\n\n\t\tResponse<Thread> draft = nylas.threads().update(\"<NYLAS_GRANT_ID>\", \"<THREAD_ID>\", requestBody);\n\t\t\n\t\tSystem.out.printf(\"%s%s%s%n\",\n\t\t\tdraft.getData().getId(),\n\t\t\tdraft.getData().getUnread(),\n\t\t\tdraft.getData().getStarred()\n\t\t);\n\t}\n}"
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.UpdateThreadRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val requestBody: UpdateThreadRequest =
UpdateThreadRequest.
Builder().
unread(true).
starred(true).
build()
val thread = nylas.threads().update("<NYLAS_GRANT_ID>", "<THREAD_ID>", requestBody)
print("${thread.data.id} ${thread.data.unread} ${thread.data.starred} ")
}
delete:
summary: Delete a thread
tags:
- Threads
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: delete-threads-id
description: Moves the specified thread to the Trash, including all messages in the thread.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/shared_folder_id'
- $ref: '#/components/parameters/shared_from'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads/<THREAD_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const threadId = "<THREAD_ID>";
const deleteThread = async () => {
try {
await nylas.threads.destroy({ identifier, threadId });
console.log(`Thread with ID ${threadId} deleted successfully.`);
} catch (error) {
console.error(`Error deleting thread with ID ${threadId}:`, error);
}
};
deleteThread();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
thread_id = "<THREAD_ID>"
request = nylas.threads.destroy(
grant_id,
thread_id,
)
print(request)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\nthread, _ = nylas.threads.destroy(identifier: \"<NYLAS_GRANT_ID>\", \n thread_id: \"<THREAD_ID>\")\n\nputs thread\n"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import com.nylas.models.Thread;
public class ReturnThread {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse thread = nylas.threads().destroy("<NYLAS_GRANT_ID>",
"<THREAD_ID>");
System.out.println(thread);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val thread = nylas.threads().destroy("<NYLAS_GRANT_ID>", "<THREAD_ID>")
print(thread)
}
/v3/grants/{grant_id}/folders:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
get:
summary: Return all folders
tags:
- Folders
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.labels
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.ReadWrite.Shared
- https://graph.microsoft.com/Mail.Read.Shared
yahoo:
min: email, mail-r
responses:
'200':
$ref: '#/components/responses/folders'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-folder
description: Returns all folders for all providers. Nylas flattens sub-folders into a single list.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/include_hidden_folders'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/parent_id'
- $ref: '#/components/parameters/shared_from'
- $ref: '#/components/parameters/single_level'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchFolders() {
try {
const folders = await nylas.folders.list({
identifier: "<NYLAS_GRANT_ID>",
});
console.log("folders:", folders);
} catch (error) {
console.error("Error fetching folders:", error);
}
}
fetchFolders();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
folder_id = "<FOLDER_ID>"
folder = nylas.folders.list(
grant_id
)
print(folder)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
folders, _ = nylas.folders.list(identifier: "<NYLAS_GRANT_ID>")
folders.each { |folder|
puts "#{folder[:id]} | #{folder[:name]}"
}
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReturnFolders {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Folder> folders =
nylas.folders().list("<NYLAS_GRANT_ID>");
for(Folder folder : folders.getData()){
System.out.println(folder.getId() + " | " + folder.getName());
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val labels = nylas.folders().list("<NYLAS_GRANT_ID>")
for (label in labels.data){
println(label.id + " | " + label.name)
}
}
post:
summary: Create a Folder
operationId: post-folder
description: Creates a folder.
tags:
- Folders
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.labels
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
requestBody:
$ref: '#/components/requestBodies/folder_create'
responses:
'200':
$ref: '#/components/responses/folder'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/shared_from'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"text_color": "#000000",
"name": "new folder",
"background_color": "#73AFFF"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const createFolder = async () => {
try {
const folder = await nylas.folders.create({
identifier,
requestBody: {
name: "New Folder",
},
});
console.log("Folder created:", folder);
} catch (error) {
console.error("Error creating folder:", error);
}
};
createFolder();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
folder = nylas.folders.create(
grant_id,
request_body={
"name": 'New Folder',
}
)
print(folder)
- lang: ruby
label: Ruby SDK
source: |-
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
name: "My Custom label"
}
folder = nylas.folders.create(identifier: "<NYLAS_GRANT_ID>",
request_body: request_body)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class CreateFolder {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CreateFolderRequest request =
new CreateFolderRequest("My Custom folder", "", "", "");
Response<Folder> label =
nylas.folders().create("<NYLAS_GRANT_ID>", request);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.CreateFolderRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val request = CreateFolderRequest("My Custom folder")
val folder = nylas.folders().create("<NYLAS_GRANT_ID>", request).data
println(folder.name)
}
/v3/grants/{grant_id}/folders/{folder_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: folder_id
in: path
required: true
description: |-
ID of the folder to access. Nylas recommends you URL-encode this field, or you might receive
a [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
get:
summary: Return a Folder
tags:
- Folders
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.labels
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.ReadWrite.Shared
- https://graph.microsoft.com/Mail.Read.Shared
yahoo:
min: email, mail-r
responses:
'200':
$ref: '#/components/responses/folder'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-folders-id
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/include_hidden_folders'
- $ref: '#/components/parameters/shared_from'
description: Returns the specified folder.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchFolderById() {
try {
const folder = await nylas.folders.find({
identifier: "<NYLAS_GRANT_ID>",
folderId: "<FOLDER_ID>",
});
console.log("Folder:", folder);
} catch (error) {
console.error("Error fetching folder:", error);
}
}
fetchFolderById();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
folder_id = "<FOLDER_ID>"
message = nylas.folders.find(
grant_id,
folder_id,
)
print(message)
- lang: ruby
label: Ruby SDK
source: |-
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
folder, _ = nylas.folders.find(identifier: "<NYLAS_GRANT_ID>", folder_id: "<FOLDER_ID>")
puts folder
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class GetLabel {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Folder> folder = nylas.folders().find("<NYLAS_GRANT_ID>",
"<FOLDER_ID>");
System.out.println(folder);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val folder = nylas.folders().find("<NYLAS_GRANT_ID>",
"<FOLDER_ID>")
print(folder)
}
put:
summary: Update a folder
tags:
- Folders
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.labels
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/folder'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: put-folders-id
description: |-
Updates the specified folder.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/include_hidden_folders'
- $ref: '#/components/parameters/shared_from'
requestBody:
$ref: '#/components/requestBodies/folder_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Renamed folder"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateFolder() {
try {
const folder = await nylas.folders.update({
identifier: "<NYLAS_GRANT_ID>",
folderId: "<FOLDER_ID>",
requestBody: {
name: "Updated Folder Name",
textColor: "#000000",
backgroundColor: "#434343",
},
});
console.log("Updated Folder:", folder);
} catch (error) {
console.error("Error to update folder:", error);
}
}
updateFolder();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
folder = nylas.folders.update(
grant_id,
folder_id="<FOLDER_ID>",
request_body={
"name": "Updated Folder Name",
"text_color": "#000000",
}
)
print(folder)
- lang: ruby
label: Ruby SDK
source: |-
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
name: "Renamed folder"
}
folder, _ = nylas.folders.update(identifier: "<NYLAS_GRANT_ID>",
folder_id: "Label_19", request_body: request_body)
puts folder
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class UpdateLabel {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateFolderRequest updateRequest = new UpdateFolderRequest.Builder().
name("Renamed ").build();
Response<Folder> folder = nylas.folders().update("<NYLAS_GRANT_ID>",
"<FOLDER_ID>", updateRequest);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.UpdateFolderRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val requestBody = UpdateFolderRequest.Builder().
name("Renamed Folder").build();
val folder = nylas.folders().update("<NYLAS_GRANT_ID>",
"<FOLDER_ID>", requestBody)
print(folder.data)
}
delete:
summary: Delete a Folder
tags:
- Folders
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.labels
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
yahoo:
min: email, mail-r, mail-w
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: delete-folders-id
description: Deletes the specified folder.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/shared_from'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const folderId = "<FOLDER_ID>";
const deleteFolder = async () => {
try {
await nylas.folders.destroy({ identifier, folderId });
console.log(`Folder with ID ${folderId} deleted successfully.`);
} catch (error) {
console.error(`Error deleting folder with ID ${folderId}:`, error);
}
};
deleteFolder();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
folder_id = "<FOLDER_ID>"
request = nylas.folders.destroy(
grant_id,
folder_id,
)
print(request)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
folder, _ = nylas.folders.destroy(identifier: "<NYLAS_GRANT_ID>",
folder_id: "<FOLDER_ID>")
puts folder
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class DestroyLabel {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse folder = nylas.folders().destroy("<NYLAS_GRANT_ID>",
"<FOLDER_ID>");
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val folder = nylas.folders().destroy("<NYLAS_GRANT_ID>",
"<FOLDER_ID>")
print(folder)
}
/v3/grants/{grant_id}/attachments/{attachment_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: attachment_id
in: path
required: true
description: |-
ID of the attachment to access. Nylas recommends you URL-encode this field, or you might receive
a [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
- schema:
type: string
name: message_id
in: query
required: true
description: ID of the message the specified attachment belongs to.
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/query_imap_get_by_id'
get:
summary: Return Attachment metadata
tags:
- Attachments
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.ReadWrite.Shared
- https://graph.microsoft.com/Mail.Read.Shared
yahoo:
min: email, mail-r
responses:
'200':
$ref: '#/components/responses/attachment'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-attachments-id
description: Returns the metadata of the specified attachment.
x-code-samples:
- lang: bash
label: cURL
source: |
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>?message_id=<MESSAGE_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchAttachmentById() {
try {
const attachment = await nylas.attachments.find({
identifier: "<NYLAS_GRANT_ID>",
attachmentId: "<ATTACHMENT_ID>",
queryParams: {
messageId: "<MESSAGE_ID>",
},
});
console.log("Attachment:", attachment);
} catch (error) {
console.error("Error fetching attachment:", error);
}
}
fetchAttachmentById();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
folder_id = "<FOLDER_ID>"
attachment_id = "<ATTACHMENT_ID>"
attachment = nylas.attachments.find(
grant_id,
attachment_id,
query_params= {
"message_id": "<MESSAGE_ID>",
}
)
print(attachment)
- lang: ruby
label: Ruby SDK
source: |-
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
query_params = {
message_id: "<MESSAGE_ID>"
}
attachment = nylas.attachments.find(identifier: "<NYLAS_GRANT_ID>",
attachment_id: "<ATTACHMENT_ID>", query_params: query_params)
puts attachment
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class attachment {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError, NylasOAuthError {
NylasClient nylas = new NylasClient.Builder("NYLAS_API_KEY").build();
FindAttachmentQueryParams queryParams = new FindAttachmentQueryParams("<MESSAGE_ID>");
Attachment attachment = nylas.attachments().find("<NYLAS_GRANT_ID>", "<ATTACHMENT_ID>", queryParams).getData();
System.out.println(attachment);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.FindAttachmentQueryParams
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val queryParams = FindAttachmentQueryParams("<MESSAGE_ID>")
val attachment = nylas.attachments().find("<NYLAS_GRANT_ID>", "<ATTACHMENT_ID>", queryParams)
print(attachment)
}
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/grants/{grant_id}/attachments/{attachment_id}/download:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: attachment_id
in: path
required: true
description: |-
ID of the attachment to access. Nylas recommends you URL-encode this field, or you might receive
a [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
- schema:
type: string
name: message_id
in: query
required: true
description: ID of the message the specified attachment belongs to.
get:
summary: Download an Attachment
tags:
- Attachments
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.readonly
others: https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.Read
others:
- https://graph.microsoft.com/Mail.ReadWrite
- https://graph.microsoft.com/Mail.ReadWrite.Shared
- https://graph.microsoft.com/Mail.Read.Shared
responses:
'200':
$ref: '#/components/responses/attachment_file'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-attachments-id-download
parameters:
- name: query_imap
schema:
type: boolean
default: false
in: query
required: false
description: |-
(IMAP, Yahoo, and iCloud only) When `true`, Nylas downloads the attachment directly from the
IMAP server instead of the Nylas database.
description: Returns and downloads the specified attachment.
x-code-samples:
- lang: bash
label: cURL
source: |
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID>' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import fs from "fs";
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function downloadAttachment() {
try {
const attachmentBytes = await nylas.attachments.downloadBytes({
identifier: "<NYLAS_GRANT_ID>",
attachmentId: "<ATTACHMENT_ID>",
queryParams: {
messageId: "<MESSAGE_ID>",
},
});
const fileName = "attachment";
await fs.promises.writeFile(fileName, attachmentBytes);
console.log(`File saved as ${fileName}`);
} catch (error) {
console.error("Error fetching attachment:", error);
}
}
downloadAttachment();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
attachment_id = "<ATTACHMENT_ID>"
attachment = nylas.attachments.download(
grant_id,
attachment_id,
query_params= {
"message_id": "<MESSAGE_ID>",
}
)
with open("attachment", 'wb') as f:
f.write(attachment.content)
- lang: ruby
label: Ruby SDK
source: |-
require 'nylas'
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
query_params = {
message_id: "<MESSAGE_ID>"
}
attachment = nylas.attachments.download(identifier: "<NYLAS_GRANT_ID>",
attachment_id: "<ATTACHMENT_ID>", query_params: query_params)
File.open("./image.png", "wb") do |file|
file.write(attachment)
end
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
import okhttp3.ResponseBody;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.io.IOException;
public class attachment_download {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasOAuthError, IOException {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
FindAttachmentQueryParams queryParams = new FindAttachmentQueryParams("<MESSAGE_ID>");
ResponseBody attachment = nylas.attachments().download("<NYLAS_GRANT_ID>", "<ATTACHMENT_ID>", queryParams);
try {
FileOutputStream out = new FileOutputStream("src/main/resources/image.png");
out.write(attachment.bytes());
out.close();
} catch (FileNotFoundException e) {
System.out.println("File not found");
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.FindAttachmentQueryParams
import java.io.File
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val queryParams = FindAttachmentQueryParams("<MESSAGE_ID>")
val attachment = nylas.attachments().download("<NYLAS_GRANT_ID>", "<ATTACHMENT_ID>", queryParams)
File("src/main/resources/Image.png").writeBytes(attachment.bytes())
}
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/grants/{grant_id}/attachment-uploads:
post:
summary: Create an attachment upload session
tags:
- Attachments
operationId: create-attachment-upload-session
x-beta: true
description: |-
Create a resumable upload session for a large attachment (up to 150 MB). Returns a pre-signed URL
where you upload the file bytes directly using `PUT`.
Upload sessions expire **one hour** after creation. Once you upload the file to the returned URL,
call the [complete endpoint](/docs/reference/api/attachments/complete-attachment-upload-session/)
to finalize the upload. After completion, reference the `attachment_id` in a send or draft request.
**Supported providers:** Microsoft (Outlook / Exchange via Graph) only. Grants for Google, IMAP,
Yahoo, iCloud, and EWS are rejected with a `401 Unauthorized` error.
**Required Microsoft scopes** (at least one): `Mail.Send`, `Mail.ReadWrite`, or `Mail.ReadWrite.Shared`.
For the full flow, prerequisites, and error handling, see
[Send large attachments](/docs/v3/email/send-large-attachments/).
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
parameters:
- name: grant_id
in: path
required: true
schema:
type: string
description: The ID of the grant to create the upload session for.
requestBody:
required: true
description: Attachment upload session details.
content:
application/json:
schema:
type: object
required:
- filename
- content_type
properties:
filename:
type: string
description: The name of the file as it will appear in the email. No allowlist or sanitization is applied.
example: quarterly-report.pdf
content_type:
type: string
description: The MIME type of the file (for example, `application/pdf`, `image/png`). No MIME allowlist is applied — any non-empty string is accepted and passed through to storage.
example: application/pdf
size:
type: integer
format: int64
description: |-
Expected file size in bytes. Recommended — when provided, Nylas validates that the
uploaded object matches this size at completion. If omitted, the size-match check
is skipped and any non-zero upload is accepted. Maximum: `157286400` (150 MB).
example: 5242880
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachment-uploads' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \
--data-raw '{
"filename": "document.pdf",
"content_type": "application/pdf",
"size": 1048576
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createUploadSession() {
try {
const session = await nylas.attachments.createUploadSession({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
filename: "quarterly-report.pdf",
contentType: "application/pdf",
size: 5242880,
},
});
console.log("Upload session:", session);
} catch (error) {
console.error("Error creating upload session:", error);
}
}
createUploadSession();
responses:
'201':
description: Upload session created.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
data:
type: object
properties:
attachment_id:
type: string
description: Unique identifier for the upload session (UUID v4). Use this value when completing the session and when referencing the attachment in a send or draft.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
method:
type: string
description: The HTTP method to use when uploading the file to `url`. Always `PUT`.
example: PUT
url:
type: string
description: Google Cloud Storage resumable upload URL. `PUT` the file bytes directly here — no Nylas authorization header is required, because this is a GCS-signed URL.
example: https://storage.googleapis.com/upload/storage/v1/b/BUCKET/o?uploadType=resumable&upload_id=...
headers:
type: object
description: Headers to include when uploading to `url`.
additionalProperties:
type: string
example:
Content-Type: application/pdf
expires_at:
type: string
format: date-time
description: When the upload session expires (RFC 3339). One hour from creation by default.
example: '2026-04-22T19:00:00Z'
max_size:
type: integer
format: int64
description: Maximum allowed file size in bytes.
example: 157286400
size:
type: integer
format: int64
description: Expected file size in bytes, echoing the request. `0` if `size` was not provided on session creation.
example: 5242880
content_type:
type: string
description: MIME type of the file.
example: application/pdf
filename:
type: string
description: Name of the file.
example: quarterly-report.pdf
grant_id:
type: string
description: The grant ID the upload session belongs to.
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
attachment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
method: PUT
url: https://storage.googleapis.com/upload/storage/v1/b/BUCKET/o?uploadType=resumable&upload_id=...
headers:
Content-Type: application/pdf
expires_at: '2026-04-22T19:00:00Z'
max_size: 157286400
size: 5242880
content_type: application/pdf
filename: quarterly-report.pdf
grant_id: abc123
'400':
description: |-
Bad request. Returned when `filename` or `content_type` is missing, when `size` is
negative or zero, when `size` exceeds the 150 MB maximum, or when the request body is not valid JSON.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
error:
type: object
properties:
type:
type: string
example: invalid_request
message:
type: string
example: file_size exceeds maximum allowed size of 157286400 bytes
'401':
description: |-
Unauthorized. Returned when the grant cannot be resolved, the provider is not Microsoft,
or the grant lacks the required scopes (`Mail.Send`, `Mail.ReadWrite`, or `Mail.ReadWrite.Shared`).
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
error:
type: object
properties:
type:
type: string
example: unauthorized
message:
type: string
example: unauthorized
'500':
description: Internal error. Returned on storage or database failures (for example, the GCS resumable upload URL could not be initiated).
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
error:
type: object
properties:
type:
type: string
example: internal_error
message:
type: string
/v3/grants/{grant_id}/attachment-uploads/{attachment_id}/complete:
post:
summary: Complete an attachment upload session
tags:
- Attachments
operationId: complete-attachment-upload-session
x-beta: true
description: |-
Finalize an attachment upload session after the file has been uploaded to the pre-signed URL.
Nylas verifies that the upload succeeded in storage and, if `size` was declared on session
creation, that the uploaded byte count matches the declared size.
After completion, reference the attachment in a [send](/docs/reference/api/messages/send-message/)
or [draft](/docs/reference/api/drafts/put-drafts-id/) request by passing
`{ "id": "<attachment_id>" }` in the `attachments` array.
**Retention note:** By default, the uploaded file is deleted from storage when `expires_at`
passes (one hour after session creation). Plan your send to occur inside this window. The
attachment metadata row is retained for 60 days for observability.
For the full upload flow, see
[Send large attachments](/docs/v3/email/send-large-attachments/).
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
parameters:
- name: grant_id
in: path
required: true
schema:
type: string
description: The ID of the grant the upload session belongs to.
- name: attachment_id
in: path
required: true
schema:
type: string
description: The ID of the attachment upload session to complete.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachment-uploads/<ATTACHMENT_ID>/complete' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function completeUploadSession() {
try {
const result = await nylas.attachments.completeUploadSession({
identifier: "<NYLAS_GRANT_ID>",
attachmentId: "<ATTACHMENT_ID>",
});
console.log("Completed:", result);
} catch (error) {
console.error("Error completing upload session:", error);
}
}
completeUploadSession();
responses:
'200':
description: Upload session completed successfully. The attachment is now ready to use in a send or draft.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
data:
type: object
properties:
attachment_id:
type: string
description: 'The attachment ID. Pass this value as `{ "id": "<attachment_id>" }` in the `attachments` array of a send or draft request.'
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
grant_id:
type: string
status:
type: string
description: Upload session status. Always `ready` on success.
enum:
- ready
example: ready
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
attachment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
grant_id: abc123
status: ready
'401':
$ref: '#/components/responses/401'
'404':
description: The `attachment_id` does not exist.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
error:
type: object
properties:
type:
type: string
example: not_found
message:
type: string
'409':
description: 'The upload session has already been completed (`status: ready`) or has failed (`status: failed`).'
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
error:
type: object
properties:
type:
type: string
example: invalid_request
message:
type: string
example: upload session is already complete
'410':
description: |-
The upload session has expired. Returned when the session was previously marked `expired`
by the cleanup job, or when `expires_at` has already passed at the time `/complete` is called.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
error:
type: object
properties:
type:
type: string
example: invalid_request
message:
type: string
example: upload session has expired
'422':
description: |-
Upload verification failed. Returned when the file is not found in storage,
when the uploaded size does not match the `size` declared on session creation, or
when no `size` was declared and the uploaded object is empty.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
error:
type: object
properties:
type:
type: string
example: invalid_request
message:
type: string
example: uploaded object not found in storage
'500':
description: Internal error. Returned on storage or database failures during verification.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
error:
type: object
properties:
type:
type: string
example: internal_error
message:
type: string
/v3/grants/{grant_id}/calendars:
parameters:
- $ref: '#/components/parameters/grant_id'
get:
summary: Return all calendars
tags:
- Calendar
operationId: get-all-calendars
description: (Not supported for IMAP) Returns all calendars.
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.readonly
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/metadata_pair'
- $ref: '#/components/parameters/page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchFiveAvailableCalendars() {
try {
const calendars = await nylas.calendars.list({
identifier: "<NYLAS_GRANT_ID>",
queryParams: {
limit: 5,
},
});
console.log("Available Calendars:", calendars);
} catch (error) {
console.error("Error fetching calendars:", error);
}
}
fetchFiveAvailableCalendars();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
calendars = nylas.calendars.list(grant_id)
print(calendars)
- lang: ruby
label: Ruby SDK
source: "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\t\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\n# Build the query without parameters\nlistCalendersQueryParams = {}\n\n# Build the query with parameters\nreturnFiveCalendars = {\n\tlimit: 5\n}\n\n# Get a list of calendars\ncalendars, _request_ids = nylas.calendars.list(identifier: \"<NYLAS_GRANT_ID>\", \n\t\tquery_params: listCalendersQueryParams)\n\n# Loop the calendars\ncalendars.each {|calendar|\n\tputs(\"Name: #{calendar[:name]} | \" \\\n\t\t\t\"Description: #{calendar[:description]} | \" \\\n\t\t\t\"Is Read Only?: #{calendar[:read_only]} | \" \\\n\t\t\t\"Metadata: #{calendar[:metadata]}\")\n}\n\n# Build the event parameters with metadata\nCalendarsMetadata = {\n\tmetadata_pair: {\"key1\":\"This is my metadata\"}\n}\n\n# Get a list of calendars\ncalendars, _request_ids = nylas.calendars.list(identifier: \"<NYLAS_GRANT_ID>\", \n\t\tquery_params: CalendarsMetadata)\n\nputs \"\" \ncalendars.each {|calendar|\n\tputs calendar\n}"
- lang: kotlin
label: Kotlin SDK
source: |
// Import Nylas packages
import com.nylas.NylasClient
import com.nylas.models.*
import com.nylas.resources.Calendars
fun main(args: Array<String>) {
// Initialize Nylas client
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
// Build the query without parameters
val calendarQueryParams: ListCalendersQueryParams = ListCalendersQueryParams()
// Build the query with parameters
val returnFiveCalendars: ListCalendersQueryParams = ListCalendersQueryParams(5)
// Get all calendars
val calendars: List<Calendar> = nylas.calendars().
list("<NYLAS_GRANT_ID>",
calendarQueryParams).data
for(calendar in calendars){
println("Id: " + calendar.id +
" | Name: " + calendar.name +
" | Description: " + calendar.description +
" | Is Read Only?: " + calendar.readOnly +
" | Metadata: " + calendar.metadata)
}
// Build the event parameters with metadata
val calendarsMetadata: ListCalendersQueryParams = ListCalendersQueryParams(
metadataPair = mapOf("key1" to "This is my metadata"))
val calendarsMeta: List<Calendar> = nylas.calendars().
list("<NYLAS_GRANT_ID>",
calendarsMetadata).data
println()
println(calendarsMeta)
}
- lang: java
label: Java SDK
source: |
// Import packages
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.List;
import java.util.Map;
public class ReturnCalendars {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
// Initialize the Nylas client
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Build the query without parameters
ListCalendersQueryParams listCalendersQueryParams =
new ListCalendersQueryParams();
// Build the query with parameters
ListCalendersQueryParams returnFiveCalendars = new ListCalendersQueryParams.
Builder().limit(5).build();
// Get all calendars
List<Calendar> calendars = nylas.calendars().
list("<NYLAS_GRANT_ID>", listCalendersQueryParams).getData();
// Loop the calendars
for (Calendar calendar : calendars){
// Print out the response
System.out.println("Id: " + calendar.getId() +
" | Name: " + calendar.getName() +
" | Description: " + calendar.getDescription() +
" | Is Read Only?: " + calendar.getReadOnly() +
" | Metadata: " + calendar.getMetadata());
}
// Build the event parameters with metadata
ListCalendersQueryParams CalendarsMetadata = new ListCalendersQueryParams.
Builder().
metadataPair(
Map.of("key1",
"This is my metadata")
).
build();
// Get all calendars that correspond to the metadata
List<Calendar> metaCalendars = nylas.calendars().
list("<NYLAS_GRANT_ID>", CalendarsMetadata).
getData();
// Print out the response
System.out.println();
System.out.println(metaCalendars);
}
}
responses:
'200':
$ref: '#/components/responses/calendars'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
post:
summary: Create a calendar
tags:
- Calendar
operationId: create-calendar
description: Creates a calendar.
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar
others: ''
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
requestBody:
$ref: '#/components/requestBodies/calendar_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "My New Calendar",
"description": "Description of my new calendar",
"location": "Location description",
"timezone": "America/Los_Angeles"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createCalendar() {
try {
const calendar = await nylas.calendars.create({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
name: "Nylas DevRel",
description: "Nylas Developer Relations",
},
});
console.log("Calendar:", calendar);
} catch (error) {
console.error("Error to create calendar:", error);
}
}
createCalendar();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
calendar = nylas.calendars.create(
grant_id,
request_body={
"name": 'Nylas DevRel',
"description": 'Nylas Developer Relations'
}
)
print(calendar)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nquery_params = {\n\tcalendar_id: \"<CALENDAR_ID>\"\n}\n\nrequest_body = {\n\t\"name\": \"My New Calendar\",\n\t\"description\": \"Description of my new calendar\",\n\t\"location\": \"Location description\",\n\t\"timezone\": \"America/Toronto\",\n\t\"metadata\": { \"key1\":\"This is my metadata\" }\n}\n\ncalendar, _request_ids = nylas.calendars.create(\n\t\tidentifier: \"<NYLAS_GRANT_ID>\", \n\t\trequest_body: request_body)\n\nputs calendar"
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val requestBody = CreateCalendarRequest(
"My New Calendar",
"Description of my new calendar",
"Location description",
"America/Toronto",
mapOf("key1" to "This is my metadata")
)
val calendar: Response<Calendar> = nylas.calendars().
create("<NYLAS_GRANT_ID>", requestBody)
print(calendar.data)
}
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.Map;
public class CreateCalendar {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CreateCalendarRequest requestBody = new CreateCalendarRequest.Builder("My New Calendar")
.description("Description of my new calendar")
.location("Location description")
.timezone("America/Toronto")
.metadata(Map.of("key1", "This is my metadata"))
.build();
Response<Calendar> calendar = nylas.calendars().
create("<NYLAS_GRANT_ID>", requestBody);
System.out.println(calendar.getData());
}
}
responses:
'200':
$ref: '#/components/responses/calendar'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/grants/{grant_id}/calendars/{calendar_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: calendar_id
in: path
required: true
description: |-
ID of the calendar to access. You can use `primary` to refer to the primary calendar associated
with a grant. Nylas recommends you URL-encode this field, or you might receive a
[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for example,
`#`).
get:
summary: Return a calendar
tags:
- Calendar
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.readonly
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
responses:
'200':
$ref: '#/components/responses/calendar'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-calendars-id
description: Returns the specified calendar.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchCalendar() {
try {
const calendar = await nylas.calendars.find({
identifier: "<NYLAS_GRANT_ID>",
calendarId: "<CALENDAR_ID>",
});
console.log("Calendar:", calendar);
} catch (error) {
console.error("Error fetching calendars:", error);
}
}
fetchCalendar();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
calendar = nylas.calendars.find(
grant_id,
"<CALENDAR_ID>"
)
print(calendar)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\ncalendar, _request_ids = nylas.calendars.find(\n\t\tidentifier: \"<NYLAS_GRANT_ID>\", \n\t\tcalendar_id: \"<CALENDAR_ID>\"\n)\n\nputs calendar"
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class GetCalendar {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Calendar> calendar = nylas.calendars().find("<NYLAS_GRANT_ID>", "<CALENDAR_ID>");
System.out.println("Id: " + calendar.getData().getId() +
" | Name: " + calendar.getData().getName() +
" | Description: " + calendar.getData().getDescription());
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val calendar: Response<Calendar> = nylas.calendars().find("<NYLAS_GRANT_ID>", "<CALENDAR_ID>")
println("Id: " + calendar.data.id +
" | Name: " + calendar.data.name +
" | Description: " + calendar.data.description)
}
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
put:
summary: Update a calendar
tags:
- Calendar
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar
others: ''
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
responses:
'200':
$ref: '#/components/responses/calendar'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: put-calendars-id
description: |-
Updates the specified calendar.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "My New Calendar",
"description": "Description of my new calendar",
"location": "Location description",
"timezone": "America/Los_Angeles"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateCalendar() {
try {
const calendar = await nylas.calendars.update({
identifier: "<NYLAS_GRANT_ID>",
calendarId: "<CALENDAR_ID>",
requestBody: {
name: "Nylas DevRel Calendar",
description: "Nylas Developer Relations",
},
});
console.log("Updated Calendar:", calendar);
} catch (error) {
console.error("Error to update calendar:", error);
}
}
updateCalendar();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
calendar = nylas.calendars.update(
grant_id,
calendar_id="<CALENDAR_ID>",
request_body={
"name": 'Nylas DevRel Calendar',
"description": 'Nylas Developer Relations'
}
)
print(calendar)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nrequest_body = {\n\t\"name\": \"\\\"New Test Calendar (changed)\\\"\",\n\t\"description\": \"\\\"this calendar has been updated!\\\"\",\n}\n\ncalendar, _request_ids = nylas.calendars.update(\n\t\tidentifier: \"<NYLAS_GRANT_ID>\", \n\t\tcalendar_id: \"<CALENDAR_ID\", \n\t\trequest_body: request_body)\n\nputs calendar"
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class UpdateCalendar {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateCalendarRequest requestBody = new UpdateCalendarRequest.Builder().
name("My New Calendar").
description("Description of my new calendar").
location("Location description").
timezone("America/Los_Angeles").
build();
Response<Calendar> calendar = nylas.calendars().update(
"<CALENDAR_ID>",
"<CALENDAR_ID>",
requestBody);
System.out.println(calendar.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.*
import com.nylas.resources.Calendars
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val requestBody = UpdateCalendarRequest.Builder().
name("\"New Test Calendar (changed)\"").
description("\"this calendar has been updated!\"").
location("Location description").
timezone("America/Los_Angeles").
build()
val calendar: Response<Calendar> = nylas.calendars().update(
"<CALENDAR_ID>",
"<CALENDAR_ID>",
requestBody)
print(calendar.data)
}
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
requestBody:
$ref: '#/components/requestBodies/calendar_update'
delete:
summary: Delete a calendar
tags:
- Calendar
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar
others: ''
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: delete-calendars-id
description: |-
Deletes the specified calendar. You _cannot_ delete the primary calendar associated with an
account (`"is_primary": true`).
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deleteCalendar() {
try {
const calendar = await nylas.calendars.destroy({
identifier: "<NYLAS_GRANT_ID>",
calendarId: "<CALENDAR_ID>",
});
console.log("Calendar:", calendar);
} catch (error) {
console.error("Error to create calendar:", error);
}
}
deleteCalendar();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
calendar_id = "<CALENDAR_ID>"
request = nylas.calendars.destroy(
grant_id,
calendar_id,
)
print(request)
- lang: ruby
label: Ruby SDK
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
# Create new calendar
calendar, = nylas.calendars.destroy(identifier: "<NYLAS_GRANT_ID>",
calendar_id: "<CALENDAR_ID>")
# Print calendar information
puts calendar
- lang: java
label: Java SDK
source: |-
// Import packages
import com.nylas.NylasClient;
import com.nylas.models.*;
public class DeleteCalendar {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Delete the requested calendar
try {
nylas.calendars().destroy("<NYLAS_GRANT_ID>", "<CALENDAR_ID>", null);
System.out.println("Deleted successfully");
}
catch(Exception e) {
System.out.println("There was an error " + e);
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
// Import Nylas packages
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
// Initialize Nylas client
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
try {
val calendar: DeleteResponse = nylas.calendars().destroy("<NYLAS_GRANT_ID>", "<CALENDAR_ID>")
println("Deleted successfully")
}catch (e: NylasApiError){
println("There was an error $e")
}
}
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
/v3/calendars/availability:
post:
summary: Get availability
tags:
- Calendar
operationId: post-availability
description: |-
Returns availability information for the specified user or group of users. All participants' email
addresses must be associated with valid Nylas grants, and should be unique within their application.
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.readonly
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
content:
application/json:
schema:
type: object
required:
- duration_minutes
- end_time
- participants
- start_time
properties:
availability_rules:
type: object
$ref: '#/components/schemas/availability_rules'
duration_minutes:
type: integer
description: |-
The duration of each time slot, in minutes. The duration must be a multiple of 5
minutes.
example: 30
end_time:
type: integer
description: |-
The end of the time slot that Nylas checks availability for, in seconds using the Unix
timestamp format. The time must be a multiple of 5 minutes.
example: 1659733200
interval_minutes:
type: integer
description: |-
Nylas generates a time slot every `interval_minutes` (for example, every 30 minutes)
and returns only slots when all participants are free. The interval must be a multiple
of 5 minutes.
example: 30
participants:
type: array
description: A list of participants to get availability information for.
items:
type: object
properties:
calendar_ids:
type: array
description: |-
A list of calendar IDs associated with the participant's email address. If not
defined, Nylas uses the participant's primary calendar ID.
items:
type: string
example:
- primary
email:
type: string
description: |-
The participant's email address. The email address must be associated with a valid
Nylas grant, and should be unique within its application.
example: nyla@example.com
grant_id:
type: string
description: The participant's Nylas grant ID.
open_hours:
type: array
description: |-
An array of the participant's open hours. Nylas searches for free time slots
within these hours.
items:
$ref: '#/components/schemas/availability_open_hours'
only_specific_time_availability:
type: boolean
description: |-
When `true`, Nylas checks availability only against this participant's
`specific_time_availability` entries and ignores their regular `open_hours`.
default: false
example: true
specific_time_availability:
type: array
description: |-
An array of date and time ranges when the participant is available. Use with
`only_specific_time_availability` set to `true` to restrict availability
to only these windows.
items:
$ref: '#/components/schemas/availability_specific_time_availability'
round_to:
type: integer
description: |-
Nylas rounds each time slot to the nearest `round_to` value. For example, if a time
slot starts at 9:05a.m. and `round_to` is set to `15`, Nylas rounds it to 9:15a.m. The
round to value must be a multiple of 5 minutes.
default: 15
example: 15
start_time:
type: integer
description: |-
The beginning of the time slot that Nylas checks availability for, in seconds using
the Unix timestamp format. The time must be a multiple of 5 minutes.
example: 1659366000
examples:
- Collective request:
participants:
- email: nyla@example.com
calendar_ids:
- primary
open_hours:
- days:
- 0
- 1
- 2
timezone: America/Toronto
start: '9:00'
end: '17:00'
- email: leyah@example.com
start_time: 1659366000
end_time: 1659733200
interval_minutes: 30
duration_minutes: 30
round_to: 15
availability_rules:
availability_method: collective
buffer:
before: 15
after: 15
x-code-samples:
- lang: bash
label: cURL
source: "curl --compressed --request POST \\\n\t--url 'https://api.us.nylas.com/v3/calendars/availability' \\\n\t--header 'Accept: application/json' \\\n\t--header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n\t--header 'Content-Type: application/json' \\\n\t--data '{\n\t\t\"participants\": [\n\t\t\t{\n\t\t\t\t\"email\": \"leyah@example.com\",\n\t\t\t\t\"calendar_ids\": [\"leyah@example.com\"],\n\t\t\t\t\"open_hours\": [{\n\t\t\t\t\t\"days\": [0,1,2],\n\t\t\t\t\t\"timezone\": \"America/Toronto\",\n\t\t\t\t\t\"start\": \"9:00\",\n\t\t\t\t\t\"end\": \"17:00\",\n\t\t\t\t\t\"exdates\": []\n\t\t\t\t}]\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"email\": \"nyla@example.com\",\n\t\t\t}\n\t\t],\n\t\t\"start_time\": 1600890600,\n\t\t\"end_time\": 1600999200,\n\t\t\"interval_minutes\": 30,\n\t\t\"duration_minutes\": 30,\n\t\t\"round_to\": 15,\n\t\t\"availability_rules\": {\n\t\t\t\"availability_method\": \"collective\",\n\t\t\t\"buffer\": {\n\t\t\t\t\"before\": 15,\n\t\t\t\t\"after\": 15\n\t\t\t},\n\t\t\t\"default_open_hours\": [\n\t\t\t\t{\n\t\t\t\t\t\"days\": [0,1,2],\n\t\t\t\t\t\"timezone\": \"America/Toronto\",\n\t\t\t\t\t\"start\": \"9:00\",\n\t\t\t\t\t\"end\": \"17:00\",\n\t\t\t\t\t\"exdates\": []\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"days\": [3,4,5],\n\t\t\t\t\t\"timezone\": \"America/Toronto\",\n\t\t\t\t\t\"start\": \"10:00\",\n\t\t\t\t\t\"end\": \"18:00\",\n\t\t\t\t\t\"exdates\": []\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t}'"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const email = "<EMAIL>";
async function getCalendarAvailability() {
try {
const calendar = await nylas.calendars.getAvailability({
requestBody: {
startTime: 1630435200,
endTime: 1630521600,
durationMinutes: 15,
participants: [{ email }],
},
});
console.log("Calendar:", calendar);
} catch (error) {
console.error("Error to create calendar:", error);
}
}
getCalendarAvailability();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
email = "<EMAIL>"
availability = nylas.calendars.get_availability(
request_body={
"start_time": 1630435200,
"end_time": 1630521600,
"duration_minutes": 15,
"participants": [{"email": email}]
}
)
print(availability)
- lang: ruby
label: Ruby SDK
source: "# Load gems\nrequire 'nylas'\nrequire 'date'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\t\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\n# Get today’s date\ntoday = Date.today\n\n# When do we start and end searching for availability\nstart_time = Time.local(today.year, today.month, today.day, 8, 0,0).strftime(\"%s\").to_i\nend_time = Time.local(today.year, today.month, today.day, 17, 0,0).strftime(\"%s\").to_i\n\n# Body of our request\nrequest_body = {\n\t\"participants\": [{\n\t\t\"email\": \"<NYLAS_GRANT_ID>\",\n\t\t\"calendar_ids\": [\n\t\t\t\"<CALENDAR_ID>\"\n\t\t],\n\t}],\n\t\"start_time\": start_time,\n\t\"end_time\": end_time,\n\t\"duration_minutes\": 60,\n}\n\n# Call the get_availability endpoint\navailable, _request_ids = nylas.calendars.get_availability(request_body: request_body)\n\n# Display available spots\navailable[:time_slots].each {|slots|\n\tputs \"From: #{Time.at(slots[:start_time]).to_datetime.strftime(\"%H:%M:%S\")}\" \\\n\t \" To: #{Time.at(slots[:end_time]).to_datetime.strftime(\"%H:%M:%S\")}\"\n}"
- lang: java
label: Java SDK
source: |-
// Import Nylas packages
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneOffset;
import java.time.temporal.ChronoUnit;
import java.util.ArrayList;
import java.util.List;
import java.text.SimpleDateFormat;
public class get_availability {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Get today's date
LocalDate today = LocalDate.now();
// Our day starts at 8:00am
Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);
// Get time as a Unix timestamp
long startTime = sixPmUtc.getEpochSecond();
// Add 9 hours, so our day ends at 5:00pm
Instant sixPmUtcPlus = sixPmUtc.plus(9, ChronoUnit.HOURS);
long endTime = sixPmUtcPlus.getEpochSecond();
List<String> calendars = new ArrayList<>();
calendars.add("<CALENDAR_ID>");
AvailabilityParticipant participant = new AvailabilityParticipant.Builder("<PARTICIPANT_EMAIL>")
.calendarIds(calendars)
.build();
List<AvailabilityParticipant> participants = new ArrayList<>();
participants.add(participant);
GetAvailabilityRequest availability = new GetAvailabilityRequest.Builder(
Math.toIntExact(startTime),
Math.toIntExact(endTime),
participants,
60).build();
Response<GetAvailabilityResponse> available = nylas.calendars().getAvailability(availability);
assert available.getData().getTimeSlots() != null;
for(TimeSlot times : available.getData().getTimeSlots()){
String initDate = new SimpleDateFormat("HH:mm:ss").
format(new java.util.Date((times.getStartTime() * 1000L)));
String endDate = new SimpleDateFormat("HH:mm:ss").
format(new java.util.Date((times.getEndTime() * 1000L)));
System.out.println("From " + initDate + " To: " + endDate);
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
// Import Nylas packages
import com.nylas.NylasClient
import com.nylas.models.*
// Import Java Packages
import java.text.SimpleDateFormat
import java.time.LocalDateTime
import java.time.ZoneOffset
fun main(args: Array<String>) {
// Initialize Nylas client
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
// Get today's day
var startDate = LocalDateTime.now()
// Set time. As we're using UTC we need to add the hours in difference
// from our own Timezone
startDate = startDate.withHour(12);
startDate = startDate.withMinute(0);
startDate = startDate.withSecond(0);
val endDate = startDate.withHour(21);
val calendars : List<String> = listOf("<CALENDAR_ID>")
val participant = AvailabilityParticipant("<NYLAS_GRANT_ID>", calendars, null)
val participants : List<AvailabilityParticipant> = listOf(participant)
val request = GetAvailabilityRequest(startDate.toEpochSecond(ZoneOffset.UTC).toInt(),
endDate.toEpochSecond(ZoneOffset.UTC).toInt(), participants, 60)
val available : Response<GetAvailabilityResponse> = nylas.calendars().
getAvailability(request)
for(slot in available.data.timeSlots!!){
println("From: " + SimpleDateFormat("HH:mm:ss").format((slot.startTime * 1000L)) +
" to: " + SimpleDateFormat("HH:mm:ss").format((slot.endTime * 1000L)))
}
}
responses:
'200':
$ref: '#/components/responses/availability'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/grants/{grant_id}/calendars/free-busy:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
post:
summary: Get free/busy schedule
tags:
- Calendar
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.readonly
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
operationId: post-calendars-free-busy
description: |-
(Not supported for iCloud) Returns the free/busy schedule for the specified
list of email addresses.
### Keep in mind
- The grant ID included in the request _must_ have access to view the provided email addresses'
free/busy data. This is usually configured by the provider.
- All specified email addresses must use the same provider.
- This endpoint always returns `200 OK`, even if one of the responses returns an error. Be sure
to check for any errors in the list of responses.
- Microsoft's availability calculation is limited to a maximum of 1,000 entries per time slot for
each email address included in the request.
- The free/busy response does not include all-day room resource bookings on Google or Microsoft.
- You can include up to 20 email addresses for Microsoft Graph, and up to 50 email addresses for Google in a single request.
x-code-samples:
- lang: bash
label: cURL
source: "curl --compressed --request POST \\\n\t--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy' \\\n\t--header 'Accept: application/json' \\\n\t--header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n\t--header 'Content-Type: application/json' \\\n\t--data '{\n\t\t\"start_time\": 1682467200,\n\t\t\"end_time\": 1682550000,\n\t\t\"emails\": [\"leyah@example.com\"]\n\t}'"
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const email = "<EMAIL>";
async function getFreeBusyCalendarInfo() {
try {
const calendar = await nylas.calendars.getFreeBusy({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
startTime: 1630435200,
endTime: 1630521600,
emails: [email],
},
});
console.log("Calendar:", calendar);
} catch (error) {
console.error("Error to create calendar:", error);
}
}
getFreeBusyCalendarInfo();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
email = "<EMAIL>"
free_busy = nylas.calendars.get_free_busy(
grant_id,
request_body={
"start_time":1630435200,
"end_time":1630521600,
"emails":[email]
}
)
print(free_busy)
- lang: ruby
label: Ruby SDK
source: "# Load gems\nrequire 'nylas'\nrequire 'date'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\n# Get today’s date\ntoday = Date.today\n\n# When do we start and end searching for availability\nstart_time = Time.local(today.year, today.month, today.day, 8, 0,0).strftime(\"%s\").to_i\nend_time = Time.local(today.year, today.month, today.day, 17, 0,0).strftime(\"%s\").to_i\n\n# Body of our request\nrequest_body = {\n\t\t\"emails\": [\n\t\t\"<EMAIL_ACCOUNT>\"\n\t],\n\t\"start_time\": start_time,\n\t\"end_time\": end_time\n}\n\n# Call the get_availability endpoint\navailable, _request_ids = nylas.calendars.get_free_busy(identifier: \"<NYLAS_GRANT_ID>\", \nrequest_body: request_body)\n\n# Display available spots\navailable.each {|time_slots|\n\ttime_slots[:time_slots].each {|slots|\n\t\tputs \"From: #{Time.at(slots[:start_time]).to_datetime.strftime(\"%H:%M:%S\")}\" \\\n \"To: #{Time.at(slots[:end_time]).to_datetime.strftime(\"%H:%M:%S\")}\"\n\t}\n}\n"
- lang: java
label: Java SDK
source: |-
// Import Nylas packages
import com.nylas.NylasClient;
import com.nylas.models.*;
// Import Java packages
import java.text.SimpleDateFormat;
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneOffset;
import java.time.temporal.ChronoUnit;
import java.util.ArrayList;
import java.util.List;
public class FreeBusy {
public static void main(String[] args) throws Exception {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
LocalDate today = LocalDate.now();
// Our day starts at 8:00am
Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);
int startTime = (int) sixPmUtc.getEpochSecond();
// Add 10 hours, so our day ends at 6:00pm
Instant sixPmUtcPlus = sixPmUtc.plus(10, ChronoUnit.HOURS);
int endTime = (int) sixPmUtcPlus.getEpochSecond();
// Add emails to check Free/Busy
List<String> emails = new ArrayList<>();
emails.add("<EMAIL>");
GetFreeBusyRequest request = new GetFreeBusyRequest(startTime, endTime, emails);
Response<List<GetFreeBusyResponse>> response = nylas.calendars().
getFreeBusy("<NYLAS_GRANT_ID>", request);
for(GetFreeBusyResponse freeBusy : response.getData()) {
if (freeBusy.getObject() == FreeBusyType.FREE_BUSY) {
GetFreeBusyResponse.FreeBusy freeBusyData = (GetFreeBusyResponse.FreeBusy) freeBusy;
List<FreeBusyTimeSlot> times = freeBusyData.getTimeSlots();
for(FreeBusyTimeSlot time : times){
// Format dates in a readable way
String startDate = new SimpleDateFormat("HH:mm:ss").
format(new java.util.Date((time.getStartTime() * 1000L)));
String endDate = new SimpleDateFormat("HH:mm:ss").
format(new java.util.Date((time.getEndTime() * 1000L)));
// Print out the time slots
System.out.println("From: " + startDate + " to: " + endDate);
}
} else if (freeBusy.getObject() == FreeBusyType.ERROR) {
GetFreeBusyResponse.FreeBusyError freeBusyError = (GetFreeBusyResponse.FreeBusyError) freeBusy;
} else {
throw new Exception("Unknown free busy type");
}
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |
// Import Nylas packages
import com.nylas.NylasClient
import com.nylas.models.*
// Import Kotlin/Java Packages
import java.lang.Exception
import java.time.LocalDateTime
import java.time.ZoneOffset
import java.util.*
fun main(args: Array<String>) {
// Initialize Nylas client
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
// Get today's day
var startDate = LocalDateTime.now()
// Set time. As we're using UTC we need to add the hours in difference
// from our own Timezone
startDate = startDate.withHour(13);
startDate = startDate.withMinute(0);
startDate = startDate.withSecond(0);
val endDate = startDate.withHour(23);
val emails : List<String> = listOf("<USER_EMAIL>")
// Make the request for Free/Busy
val request : GetFreeBusyRequest = GetFreeBusyRequest(
startDate.toEpochSecond(ZoneOffset.UTC).toInt(),
endDate.toEpochSecond(ZoneOffset.UTC).toInt(), emails)
// Call the Free/Busy endpoint
val response : Response<List<GetFreeBusyResponse>> = nylas.calendars().
getFreeBusy("<NYLAS_GRANT_ID>", request)
// Loop the list of Free/Busy objects
for(freeBusy in response.data){
if(freeBusy.getObject() == FreeBusyType.FREE_BUSY){
// Get the free/busy data
val freeBusyData: GetFreeBusyResponse.FreeBusy = freeBusy as
GetFreeBusyResponse.FreeBusy
// Get the busy time slots
val times : List<FreeBusyTimeSlot> = freeBusyData.timeSlots
// Loop the busy times
for(time : FreeBusyTimeSlot in times){
// Format dates in a readable way
val startTime = Date(time.startTime.toLong() * 1000)
val endTime = Date(time.endTime.toLong() * 1000)
// Print out the time slots
println("From: $startTime to $endTime")
}
}else if(freeBusy.getObject() == FreeBusyType.ERROR){
val freeBusyData: GetFreeBusyResponse.FreeBusyError = freeBusy as
GetFreeBusyResponse.FreeBusyError
}else{
throw Exception("Unknown free busy type")
}
}
}
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters: []
requestBody:
$ref: '#/components/requestBodies/freebusy'
responses:
'200':
$ref: '#/components/responses/freebusy'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/grants/{grant_id}/events:
parameters:
- $ref: '#/components/parameters/grant_id'
get:
summary: Return all events
tags:
- Events
operationId: get-all-events
description: Returns all events on the user's calendars.
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events.readonly
others:
- https://www.googleapis.com/auth/calendar.events
- https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/attendees'
- $ref: '#/components/parameters/busy'
- $ref: '#/components/parameters/calendar_id'
- $ref: '#/components/parameters/description'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/event_type'
- $ref: '#/components/parameters/expand_recurring'
- $ref: '#/components/parameters/ical_uid'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/location'
- $ref: '#/components/parameters/master_event_id'
- $ref: '#/components/parameters/metadata_pair'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/show_cancelled'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/tentative_as_busy'
- $ref: '#/components/parameters/title'
- $ref: '#/components/parameters/updated_after'
- $ref: '#/components/parameters/updated_before'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>&start=<TIMESTAMP>&end=<TIMESTAMP>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchAllEventsFromCalendar() {
try {
const events = await nylas.events.list({
identifier: "<NYLAS_GRANT_ID>",
queryParams: {
calendarId: "<CALENDAR_ID>",
},
});
console.log("Events:", events);
} catch (error) {
console.error("Error fetching calendars:", error);
}
}
fetchAllEventsFromCalendar();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
events = nylas.events.list(
grant_id,
query_params={
"calendar_id": "<CALENDAR_ID>"
}
)
print(events)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nquery_params = {\n\tcalendar_id: \"<CALENDAR_ID>\"\n}\n\n# Read events from our main calendar in the specified date and time\nevents, _request_ids = nylas.events.list(identifier: \"<NYLAS_GRANT_ID>\", query_params: query_params)\n\nevents.each {|event|\n\tcase event[:when][:object]\n\t\twhen 'timespan'\n\t\t\tstart_time = Time.at(event[:when][:start_time]).strftime(\"%d/%m/%Y at %H:%M:%S\")\n\t\t\tend_time = Time.at(event[:when][:end_time]).strftime(\"%d/%m/%Y at %H:%M:%S\")\n\t\t\tevent_date = \"The time of the event is from: #{start_time} to #{end_time}\"\n\t\twhen 'datespan'\n\t\t\tstart_time = event[:when][:start_date]\n\t\t\tend_time = event[:when][:end_date]\n\t\t\tevent_date = \"The date of the event is from: #{start_time} to: #{end_time}\"\n\t\twhen 'date'\n\t\t\tstart_time = event[:when][:date]\n\t\t\tevent_date = \"The date of the event is: #{start_time}\"\n\t\tend\n\t\tevent[:participants].each {|participant|\n\t\t\tparticipant_details += \"Email: #{participant[:email]} \" \\\n\t\t\t\"Name: #{participant[:name]} Status: #{participant[:status]} - \"\n\t\t}\n\t\tprint \"Id: #{event[:id]} | Title: #{event[:title]} | #{event_date} | \" \n\t\tputs \"Participants: #{participant_details.chomp(' - ')}\"\n\t\tputs \"\\n\"\n}"
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.*
import java.util.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val eventquery: ListEventQueryParams = ListEventQueryParams(calendarId = "<CALENDAR_ID>")
// Get a list of events
val myevents: List<Event> = nylas.events().list(
"<NYLAS_GRANT_ID>",
queryParams = eventquery).data
// Loop through the events
for(event in myevents){
print("Id: " + event.id + " | ");
print("Title: " + event.title);
// Get the details of Date and Time of each event.
when(event.getWhen().getObject().toString()) {
"DATE" -> {
val datespan = event.getWhen() as When.Date
print(" | The date of the event is: " + datespan.date);
}
"DATESPAN" -> {
val datespan = event.getWhen() as When.Datespan
print(" | The date of the event is: " + datespan.startDate);
}
"TIMESPAN" -> {
val timespan = event.getWhen() as When.Timespan
val startDate = Date(timespan.startTime.toLong() * 1000)
val endDate = Date(timespan.endTime.toLong() * 1000)
print(" | The time of the event is from: $startDate to $endDate");
}
}
print(" | Participants: ");
// Get a list of the event participants
val participants = event.participants
// Loop through and print their email, name and status
for(participant in participants) {
print(" Email: " + participant.email + " Name: " + participant.name +
" Status: " + participant.status)
}
println("\n")
}
}
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.When;
import com.nylas.models.*;
import java.text.SimpleDateFormat;
import java.util.List;
import java.util.Objects;
public class read_calendar_events {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Build the query parameters to filter our the results
ListEventQueryParams listEventQueryParams = new ListEventQueryParams.Builder("<CALENDAR_ID>").build();
// Read the events from our main calendar
List<Event> events = nylas.events().list("<NYLAS_GRANT_ID>", listEventQueryParams).getData();
for (Event event : events) {
System.out.print("Id: " + event.getId() + " | ");
System.out.print("Title: " + event.getTitle());
// Dates are handled differently depending on the event type
switch (Objects.requireNonNull(event.getWhen().getObject()).getValue()) {
case "datespan" -> {
When.Datespan date = (When.Datespan) event.getWhen();
System.out.print(" | The date of the event is from: " +
date.getStartDate() + " to " +
date.getEndDate());
}
case "date" -> {
When.Date date = (When.Date) event.getWhen();
System.out.print(" | The date of the event is: " +date.getDate());
}
case "timespan" -> {
When.Timespan timespan = (When.Timespan) event.getWhen();
String initDate = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").
format(new java.util.Date((timespan.getStartTime() * 1000L)));
String endDate = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").
format(new java.util.Date((timespan.getEndTime() * 1000L)));
System.out.print(" | The time of the event is from: " +
initDate + " to " + endDate);
}
}
System.out.print(" | Participants: ");
for(Participant participant : event.getParticipants()){
System.out.print(" Email: " + participant.getEmail() +
" Name: " + participant.getName() +
" Status: " + participant.getStatus());
}
System.out.println("\n");
}
}
}
responses:
'200':
$ref: '#/components/responses/events'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
post:
summary: Create an event
tags:
- Events
operationId: create-event
description: |-
Creates an event.
### Microsoft limitations
Microsoft ignores the `notify_participants` field and always sends email notifications about
changes to events.
### iCloud limitations
- iCloud ignores the `notify_participants` field and always sends email notifications about changes
to events.
- Email addresses that are registered with iCloud will not receive `notify_participants`
notifications containing the event. These events are automatically added to the iCloud calendar.
- Participants' information might be replaced by their iCloud alias. For example, if the organizer's
email address is `example@icloud.com` and their iCloud account was registered with
`example@gmail.com`, you might encounter cases where `example@icloud.com` is replaced with
`example@gmail.com`.
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/calendar_id'
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/notify_participants'
- $ref: '#/components/parameters/tentative_as_busy'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/event_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"title": "Annual Philosophy Club Meeting",
"busy": true,
"conferencing": {
"provider": "Zoom Meeting",
"autocreate": {
"conf_grant_id": "<NYLAS_GRANT_ID>",
"conf_settings": {
"settings": {
"join_before_host": true,
"waiting_room": false,
"mute_upon_entry": false,
"auto_recording": "none"
}
}
}
},
"participants": [
{
"name": "Leyah Miller",
"email": "leyah@example.com"
},
{
"name": "Nyla",
"email": "nyla@example.com"
}
],
"resources": [{
"name": "Conference room",
"email": "conference-room@example.com"
}],
"description": "Come ready to talk philosophy!",
"when": {
"start_time": 1674604800,
"end_time": 1722382420,
"start_timezone": "America/New_York",
"end_timezone": "America/New_York"
},
"location": "New York Public Library, Cave room",
"recurrence": [
"RRULE:FREQ=WEEKLY;BYDAY=MO",
"EXDATE:20211011T000000Z"
],
}'
- lang: bash
label: cURL (manual conferencing)
source: |-
curl --compressed --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"title": "Annual Philosophy Club Meeting",
"busy": true,
"conferencing": {
"provider": "Google Meet",
"details": {
"url": "https://meet.google.com/***-****-***",
"pin": "xyz",
"phone": ["+1 234 555 6789"]
}
},
"participants": [
{
"name": "Leyah Miller",
"email": "leyah@example.com"
},
{
"name": "Nyla",
"email": "nyla@example.com"
}
],
"description": "Come ready to talk philosophy!",
"when": {
"start_time": 1674604800,
"end_time": 1722382420,
"start_timezone": "America/New_York",
"end_timezone": "America/New_York"
},
"location": "New York Public Library, Cave room",
"recurrence": [
"RRULE:FREQ=WEEKLY;BYDAY=MO",
"EXDATE:20211011T000000Z"
],
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const now = Math.floor(Date.now() / 1000); // Time in Unix timestamp format (in seconds)
async function createAnEvent() {
try {
const event = await nylas.events.create({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
title: "Build With Nylas",
when: {
startTime: now,
endTime: now + 3600,
},
},
queryParams: {
calendarId: "<CALENDAR_ID>",
},
});
console.log("Event:", event);
} catch (error) {
console.error("Error creating event:", error);
}
}
createAnEvent();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
events = nylas.events.create(
grant_id,
request_body={
"title": 'Build With Nylas',
"when": {
"start_time": 1609372800,
"end_time": 1609376400
},
},
query_params={
"calendar_id": "<CALENDAR_ID>"
}
)
print(events)
- lang: ruby
label: Ruby SDK
source: |
require 'nylas'
require 'date'
nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")
query_params = {
calendar_id: "<CALENDAR_ID>"
}
today = Date.today
start_time = Time.local(today.year, today.month, today.day, 13, 0, 0).to_i
end_time = Time.local(today.year, today.month, today.day, 13, 30, 0).to_i
request_body = {
when: {
start_time: start_time,
end_time: end_time
},
title: "Let's learn some Nylas Ruby SDK!",
location: "Nylas' Headquarters",
description: "Using the Nylas API with the Ruby SDK is easy.",
participants: [{
name: "Blag",
email: "atejada@gmail.com",
status: 'noreply'
}]
}
event, _request_id = nylas.events.create(
identifier: "<NYLAS_GRANT_ID>",
query_params: query_params,
request_body: request_body
)
puts event
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.*
import java.time.LocalDateTime
import java.time.ZoneOffset
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
var startDate = LocalDateTime.now()
// Set the time. Because we're using UTC, we need to add the difference in hours from our own timezone.
startDate = startDate.withHour(13);
startDate = startDate.withMinute(0);
startDate = startDate.withSecond(0);
val endDate = startDate.withMinute(30);
// Convert the dates from Unix timestamp format to integer.
val iStartDate: Int = startDate.toEpochSecond(ZoneOffset.UTC).toInt()
val iEndDate: Int = endDate.toEpochSecond(ZoneOffset.UTC).toInt()
// Create the timespan for the event.
val eventWhenObj: CreateEventRequest.When = CreateEventRequest.When.
Timespan(iStartDate, iEndDate);
// Define the title, location, and description of the event.
val title: String = "Let's learn about the Nylas Kotlin/Java SDK!"
val location: String = "Blag's Den!"
val description: String = "Using the Nylas API with the Kotlin/Java SDK is easy."
// Create the list of participants.
val participants: List<CreateEventRequest.Participant> = listOf(CreateEventRequest.
Participant("<PARTICIPANT_EMAIL>", ParticipantStatus.NOREPLY, "<PARTICIPANT_NAME>"))
// Create the event request. This adds date/time, title, location, description, and participants.
val eventRequest: CreateEventRequest = CreateEventRequest(eventWhenObj, title, location, description, participants)
// Set the event parameters.
val eventQueryParams: CreateEventQueryParams = CreateEventQueryParams("<CALENDAR_ID>")
val event: Response<Event> = nylas.events().create("<NYLAS_GRANT_ID>",
eventRequest, eventQueryParams)
}
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneOffset;
import java.time.temporal.ChronoUnit;
import java.util.*;
public class create_calendar_events {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Get today's date
LocalDate today = LocalDate.now();
// Set time. Because we're using UTC we need to add the hours in difference from our own timezone.
Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);
// Set the date and time for the event. We add 30 minutes to the starting time.
Instant sixPmUtcPlus = sixPmUtc.plus(30, ChronoUnit.MINUTES);
// Get the Date and Time as a Unix timestamp
long startTime = sixPmUtc.getEpochSecond();
long endTime = sixPmUtcPlus.getEpochSecond();
// Define title, location, and description of the event
String title = "Let's learn some about the Nylas Java SDK!";
String location = "Nylas Headquarters";
String description = "Using the Nylas API with the Java SDK is easy.";
// Create the timespan for the event
CreateEventRequest.When.Timespan timespan = new CreateEventRequest.
When.Timespan.
Builder(Math.toIntExact(startTime), Math.toIntExact(endTime)).
build();
// Create the list of participants.
List<CreateEventRequest.Participant> participants_list = new ArrayList<>();
participants_list.add(new CreateEventRequest.
Participant("johndoe@example.com", ParticipantStatus.NOREPLY,
"John Doe", "", ""));
// Build the event details.
CreateEventRequest createEventRequest = new CreateEventRequest.Builder(timespan)
.participants(participants_list)
.title(title)
.location(location)
.description(description)
.build();
// Build the event parameters. In this case, the Calendar ID.
CreateEventQueryParams createEventQueryParams = new CreateEventQueryParams.Builder("<CALENDAR_ID>").build();
// Create the event itself
Event event = nylas.events().create(
"<NYLAS_GRANT_ID>",
createEventRequest,
createEventQueryParams).getData();
}
}
responses:
'200':
$ref: '#/components/responses/event'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/grants/{grant_id}/events/import:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
get:
summary: Import events
tags:
- Events
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events.readonly
others:
- https://www.googleapis.com/auth/calendar.events
- https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
responses:
'200':
$ref: '#/components/responses/events'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: import-events
description: |-
Returns a list of recurring events, recurring event exceptions, and single events from the
specified calendar within a given time frame. This is useful when you want to import, store, and
synchronize events from the time frame to your application (for example, to enrich events with
custom data or integrate events into your own calendaring solution).
If you want to retrieve a list of all events from a calendar, use the
[Get all Events endpoint](/docs/reference/api/events/get-all-events/) instead.
### Limitations
- Nylas might return multiple instances of a single recurring event if the results are paginated.
- The number of events Nylas returns might be lower than `max_results`, even if others match your
query parameters.
- Events are not guaranteed to be sorted by their start time.
- Nylas does not support [metadata](/docs/reference/api/#metadata) for this endpoint.
- Support for Microsoft Graph is in beta.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/max_results'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/calendar_id'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/field_selection'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/import?calendar_id=<CALENDAR_ID>&start=<TIMESTAMP>&end=<TIMESTAMP>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function importEvents() {
try {
const events = await nylas.events.listImportEvents({
identifier: "<NYLAS_GRANT_ID>",
queryParams: {
calendarId: "primary",
start: 1748908800,
end: 1748995200,
},
});
console.log("Imported events:", events);
} catch (error) {
console.error("Error importing events:", error);
}
}
importEvents();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
events = nylas.events.list_import_events(
identifier="<NYLAS_GRANT_ID>",
query_params={
"calendar_id": "<CALENDAR_ID>",
"start": 1763119800,
"end": 1765711800,
},
)
print("Imported events:", events)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Event;
import com.nylas.models.ListImportEventQueryParams;
import com.nylas.models.ListResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class ImportEvents {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListImportEventQueryParams queryParams = new ListImportEventQueryParams.Builder("primary")
.start(1748908800)
.end(1748995200)
.build();
ListResponse<Event> events = nylas.events().listImportEvents("<NYLAS_GRANT_ID>", queryParams);
System.out.println("Imported events: " + events.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.ListImportEventQueryParams
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val queryParams = ListImportEventQueryParams.Builder("primary")
.start(1748908800)
.end(1748995200)
.build()
val events = nylas.events().listImportEvents("<NYLAS_GRANT_ID>", queryParams)
println("Imported events: ${events.data}")
}
/v3/grants/{grant_id}/events/{event_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: leyah@example.com
- schema:
type: string
name: event_id
in: path
required: true
description: |-
ID of the event to access. Nylas recommends you URL-encode this field, or you might receive a
[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
get:
summary: Return an event
tags:
- Events
operationId: get-events-id
description: Returns the specified event.
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events.readonly
others:
- https://www.googleapis.com/auth/calendar.events
- https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/calendar_id_no_validate'
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/tentative_as_busy'
responses:
'200':
$ref: '#/components/responses/event'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchEventById() {
try {
const events = await nylas.events.find({
identifier: "<NYLAS_GRANT_ID>",
eventId: "<EVENT_ID>",
queryParams: {
calendarId: "<CALENDAR_ID>",
},
});
console.log("Events:", events);
} catch (error) {
console.error("Error fetching calendars:", error);
}
}
fetchEventById();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
event_id = "<EVENT_ID>"
calendar_id = "<CALENDAR_ID>"
event = nylas.events.find(
grant_id,
event_id,
query_params={
"calendar_id": calendar_id
}
)
print(event)
- lang: ruby
label: Ruby SDK
source: "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\tapi_key: \"<NYLAS_API_KEY>\"\n)\n\n# Query parameters\nquery_params = {\n calendar_id: \"<CALENDAR_ID>\"\n}\n\n# Read the event from the calendar\nevent, _request_id = nylas.events.find(identifier: \"<NYLAS_GRANT_ID>\",\nevent_id: \"<EVENT_ID>\", query_params: query_params)\n\nputs event\n"
- lang: java
label: Java SDK
source: |-
// Import Nylas packages
import com.nylas.NylasClient;
import com.nylas.models.When;
import com.nylas.models.*;
public class ReadEvent {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
FindEventQueryParams queryParams = new FindEventQueryParams("<CALENDAR_ID>");
Response<Event> event = nylas.events().find("<NYLAS_GRANT_ID>", "<EVENT_ID>", queryParams);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
// Import Nylas packages
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>){
val nylas: NylasClient = NylasClient(
apiKey = "<NYLAS_API_KEY>"
)
val queryParams = FindEventQueryParams("<CALENDAR_ID>")
val event : Response<Event> = nylas.events().find("<NYLAS_GRANT_ID>", "<EVENT_ID>", queryParams)
}
put:
summary: Update an event
tags:
- Events
operationId: put-events-id
description: |-
Updates the specified event, conference, or metadata.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
### Limitations
Nylas handles updating and deleting events similarly to other endpoints, with the following
restrictions:
- You can't update events where `read_only` is `true`.
- You can't update events where the parent calendar's `read_only` field is `true`.
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/calendar_id_no_validate'
- $ref: '#/components/parameters/field_selection'
- $ref: '#/components/parameters/notify_participants'
- $ref: '#/components/parameters/tentative_as_busy'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/event_create'
responses:
'200':
$ref: '#/components/responses/event'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"title": "Birthday Party",
"busy": true,
"participants": [{
"name": "Leyah Miller",
"email": "leyah@example.com",
"comment": "Might be late."
}],
"resources": [{
"name": "Conference room",
"email": "conference-room@example.com"
}],
"description": "Come ready to skate",
"when": {
"start_time": 1406887200,
"end_time": 1417435200,
"start_timezone": "America/New_York",
"end_timezone": "America/New_York"
},
"location": "Roller Rink",
"recurrence": [
"RRULE:FREQ=WEEKLY;BYDAY=MO",
"EXDATE:20211011T000000Z"
],
"conferencing": {
"provider": "Zoom Meeting",
"autocreate": {
"conf_grant_id": "<NYLAS_GRANT_ID>",
"conf_settings": {
"settings": {
"join_before_host": true,
"waiting_room": false,
"mute_upon_entry": false,
"auto_recording": "none"
}
}
}
},
"reminder_minutes": "[20]",
"reminder_method": "popup"
}'
- lang: bash
label: cURL (manual conferencing)
source: |
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"conferencing": {
"provider": "Google Meet",
"details": {
"url": "https://meet.google.com/***-****-***",
"pin": "xyz",
"phone": ["+1 234 555 6789"]
}
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function addParticipantToAndEvent() {
try {
const event = await nylas.events.update({
identifier: "<NYLAS_GRANT_ID>",
eventId: "<EVENT_ID>",
requestBody: {
participants: [
{
name: "Nylas DevRel",
email: "devrel-@-nylas.com",
},
],
},
queryParams: {
calendarId: "<CALENDAR_ID>",
},
});
} catch (error) {
console.error("Error adding participant to event:", error);
}
}
addParticipantToAndEvent();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
event_id = "<EVENT_ID>"
event = nylas.events.update(
grant_id,
event_id,
request_body={
"participants": [{
"name": "Nylas DevRel",
"email": "devrel-@-nylas.com"
}]
},
query_params={
"calendar_id": "<CALENDAR_ID>"
}
)
print(event)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nrequest_body = {\n\tlocation: \"Nylas' Theatre\",\n}\n\nquery_params = {\n\tcalendar_id: \"<CALENDAR_ID>\"\n}\n\nevents, _request_ids = nylas.events.update(\n\t\tidentifier: \"<NYLAS_GRANT_ID>\", \n\t\tevent_id: \"<EVENT_ID>\", \n\t\tquery_params: query_params,\n\t\trequest_body: request_body)\n"
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class update_calendar_events {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateEventQueryParams params = new UpdateEventQueryParams("<CALENDAR_ID>", Boolean.FALSE);
UpdateEventRequest requestBody = new UpdateEventRequest.Builder().location("Nylas' Theatre'").build();
Response<Event> event = nylas.events().update(
"<NYLAS_GRANT_ID>",
"<EVENT_ID>",
requestBody,
params);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val queryParams = UpdateEventQueryParams("<CALENDAR_ID>", false)
val requestBody : UpdateEventRequest = UpdateEventRequest.Builder().
location("Nylas' Theatre").
build()
val response : Response<Event> = nylas.events().update(
"<NYLAS_GRANT_ID>",
"<EVENT_ID>",
requestBody,
queryParams)
}
delete:
summary: Delete an event
tags:
- Events
operationId: delete-events-id
description: |-
Delete the specified event.
Google sends deleted events to the "Trash" folder, and you can read them for a period of time using
the `show_cancelled` query parameter.
Microsoft deletes events immediately.
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/calendar_id_no_validate'
- $ref: '#/components/parameters/notify_participants'
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deleteEvent() {
try {
const event = await nylas.events.destroy({
identifier: "<NYLAS_GRANT_ID>",
eventId: "<EVENT_ID>",
queryParams: {
calendarId: "<CALENDAR_ID>",
},
});
console.log("Event deleted:", event);
} catch (error) {
console.error("Error to delete event:", error);
}
}
deleteEvent();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
event_id = "<EVENT_ID>"
event = nylas.events.destroy(
grant_id,
event_id,
query_params={
"calendar_id": "<CALENDAR_ID>"
}
)
print(event)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nquery_params = {\n calendar_id: \"<CALENDAR_ID>\"\n}\n\nresult, _request_ids = nylas.events.destroy(\n identifier: \"<NYLAS_GRANT_ID>\", \n event_id: \"<EVENT_ID>\",\n query_params: query_params)\n\nputs result\n"
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class delete_calendar_events {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DestroyEventQueryParams queryParams = new DestroyEventQueryParams("<CALENDAR_ID>", Boolean.FALSE);
DeleteResponse event = nylas.events().destroy(
"<NYLAS_GRANT_ID>",
"<EVENT_ID>",
queryParams);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val queryParams = DestroyEventQueryParams("<CALENDAR_ID>", false)
val event = nylas.events().destroy(
"<NYLAS_GRANT_ID>",
"<EVENT_ID>",
queryParams)
}
/v3/grants/{grant_id}/events/{event_id}/send-rsvp:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: event_id
in: path
required: true
description: |-
ID of the event to access. Nylas recommends you URL-encode this field, or you might receive a
[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
post:
summary: Send RSVP
tags:
- Events
x-scopes:
google:
min: https://www.googleapis.com/auth/gmail.send
others:
- https://www.googleapis.com/auth/gmail.compose
- https://www.googleapis.com/auth/gmail.modify
microsoft:
min: https://graph.microsoft.com/Mail.ReadWrite
others: https://graph.microsoft.com/Mail.ReadWrite.Shared
operationId: send-rsvp
description: |-
(Not supported for iCloud) Sends a response to an event that you're added to as a participant. You
can't directly update events as a participant.
For most events on EWS, if you decline the event by sending a "no" RSVP response, it's removed from
your calendar. If an EWS administrator disabled the option to remove declined events from calendars,
the event remains on the calendar with the "no" RSVP status.
Due to a provider limitation, Microsoft Graph might not update the event status properly.
Google allows the meeting organizer to reply "yes", "maybe", and "no" to event invitations. However,
other providers do not allow meeting organizers to reply to their own event.
Nylas sends calendar RSVPs to the event organizer as email updates.
This can duplicate the RSVP email sent by the calendar provider.
If you want to stop Nylas from sending the RSVP email,
you can set the `skip_nylas_email` field to `true` in the query parameters.
If your application does not implement the
[scopes that allow you to send messages](/docs/dev-guide/scopes/#email-api-scopes), Nylas updates
the RSVP for the event and returns a `200` with an error message. Event participants on the same provider
will see the update, but participants on other providers will not.
parameters:
- $ref: '#/components/parameters/calendar_id'
- $ref: '#/components/parameters/skip_nylas_email'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/event_send_rsvp'
responses:
'200':
$ref: '#/components/responses/events-send_rsvp'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>/send-rsvp?calendar_id=<CALENDAR_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"status": "yes"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function sendEventRSVP() {
try {
const response = await nylas.events.sendRsvp({
identifier: "<NYLAS_GRANT_ID>",
eventId: "<EVENT_ID>",
requestBody: {
status: "yes",
},
queryParams: {
calendarId: "<CALENDAR_ID>",
},
});
console.log("Event RSVP:", response);
} catch (error) {
console.error("Error sending RSVP:", error);
}
}
sendEventRSVP();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
response = nylas.events.send_rsvp(
identifier="<NYLAS_GRANT_ID>",
event_id="<EVENT_ID>",
request_body={"status": "yes"},
query_params={"calendar_id": "<CALENDAR_ID>"},
)
print(response)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nrequest_body = {\n status: \"yes\"\n}\n\nquery_params = {\n calendar_id: \"<CALENDAR_ID>\"\n}\n\nevent_rsvp = nylas.events.send_rsvp(\n identifier: \"<NYLAS_GRANT_ID>\",\n event_id: \"<EVENT_ID>\", \n request_body: request_body,\n query_params: query_params)\n \nputs event_rsvp"
- lang: java
label: Java SDK
source: |-
import com.nylas.NylasClient;
import com.nylas.models.*;
public class rsvp {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
SendRsvpRequest requestBody = new SendRsvpRequest(RsvpStatus.YES);
SendRsvpQueryParams queryParams = new SendRsvpQueryParams("<CALENDAR_ID>");
DeleteResponse rsvp = nylas.events().sendRsvp(
"<NYLAS_GRANT_ID>",
"<EVENT_ID>",
requestBody,
queryParams);
System.out.println(rsvp);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
import com.nylas.models.RsvpStatus
import com.nylas.models.SendRsvpQueryParams
import com.nylas.models.SendRsvpRequest
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val requestBody : SendRsvpRequest = SendRsvpRequest(RsvpStatus.YES)
val queryParams : SendRsvpQueryParams = SendRsvpQueryParams("<CALENDAR_ID>")
val rsvp = nylas.events().sendRsvp(
"<NYLAS_GRANT_ID>",
"<EVENT_ID>",
requestBody,
queryParams)
print(rsvp)
}
/v3/grants/{grant_id}/resources:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
get:
summary: Return room resource information
tags:
- Room resources
operationId: list-room-resources
description: Returns information about all room resources.
x-scopes:
google:
min: https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly
others: ''
microsoft:
min: https://graph.microsoft.com/Place.Read.All
others: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/resources' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/resources'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/grants/{grant_id}/contacts:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
post:
summary: Create contact
operationId: post-contact
description: Create a contact in a user's address book.
tags:
- Contacts
x-scopes:
google:
min: https://www.googleapis.com/auth/contacts
others: ''
microsoft:
min: https://graph.microsoft.com/Contacts.ReadWrite
others: ''
requestBody:
$ref: '#/components/requestBodies/contact_create'
responses:
'200':
$ref: '#/components/responses/contact'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"birthday": "1960-12-31",
"company_name": "Nylas",
"emails": [
{
"email": "leyah.miller@example.com",
"type": "work"
},
{
"email": "leyah@example.com",
"type": "home"
}
],
"given_name": "Leyah",
"groups": [
{
"id": "starred"
},
{
"id": "friends"
}
],
"im_addresses": [
{
"type": "jabber",
"im_address": "leyah_jabber"
},
{
"type": "msn",
"im_address": "leyah_msn"
}
],
"job_title": "Software Engineer",
"manager_name": "Bill",
"middle_name": "Allison",
"nickname": "Allie",
"notes": "Loves Ramen",
"office_location": "123 Main Street",
"phone_numbers": [
{
"number": "+1-555-555-5555",
"type": "work"
},
{
"number": "+1-555-555-5556",
"type": "home"
}
],
"physical_addresses": [
{
"type": "work",
"street_address": "123 Main Street",
"postal_code": "94107",
"state": "CA",
"country": "USA",
"city": "San Francisco"
},
{
"type": "home",
"street_address": "456 Main Street",
"postal_code": "94107",
"state": "CA",
"country": "USA",
"city": "San Francisco"
}
],
"source": "address_book",
"surname": "Miller",
"web_pages": [
{
"type": "work",
"url": "<WEBPAGE_URL>"
},
{
"type": "home",
"url": "<WEBPAGE_URL>"
}
]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createContact() {
try {
const contact = await nylas.contacts.create({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
givenName: "My",
middleName: "Nylas",
surname: "Friend",
notes: "Make sure to keep in touch!",
emails: [{ type: "work", email: "swag@example.com" }],
phoneNumbers: [{ type: "work", number: "(555) 555-5555" }],
webPages: [{ type: "other", url: "nylas.com" }],
},
});
console.log("Contact:", JSON.stringify(contact));
} catch (error) {
console.error("Error to create contact:", error);
}
}
createContact();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
contact = nylas.contacts.create(
grant_id,
request_body={
"middle_name": "Nylas",
"surname": "Friend",
"notes": "Make sure to keep in touch!",
"emails": [{"type": "work", "email": "swag@example.com"}],
"phone_numbers": [{"type": "work", "number": "(555) 555-5555"}],
"web_pages": [{"type": "other", "url": "nylas.com"}]
}
)
print(contact)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nrequest_body = {\n given_name: \"My\",\n middle_name: \"Nylas\",\n surname: \"Friend\", \n emails: [{email: \"nylas-friend@example.com\", type: \"work\"}],\n notes: \"Make sure to keep in touch!\",\n phone_numbers: [{number: \"555 555-5555\", type: \"business\"}],\n web_pages: [{url: \"https://www.nylas.com\", type: \"homepage\"}]\n}\n\ncontact, _ = nylas.contacts.create(identifier: \"<NYLAS_GRANT_ID>\", request_body: request_body)\n\nputs contact"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;
public class CreateAContact {
public static void main(String[] args) throws
NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
List<ContactEmail> contactEmails = new ArrayList<>();
contactEmails.add(new ContactEmail("swag@nylas.com", "work"));
List<WebPage> contactWebpages = new ArrayList<>();
contactWebpages.add(new WebPage("https://www.nylas.com", "work"));
CreateContactRequest requestBody = new CreateContactRequest.Builder().
emails(contactEmails).
companyName("Nylas").
givenName("Nylas' Swag").
notes("This is good swag").
webPages(contactWebpages).
build();
Response<Contact> contact = nylas.contacts().create("<NYLAS_GRANT_ID>", requestBody);
System.out.println(contact);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.ContactEmail
import com.nylas.models.CreateContactRequest
import com.nylas.models.WebPage
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val emails : List<ContactEmail> = listOf(ContactEmail("swag@nylas.com", "work"))
val webpage : List<WebPage> = listOf(WebPage("https://www.nylas.com", "work"))
val contactRequest = CreateContactRequest.Builder().
emails(emails).
companyName("Nylas").
givenName("Nylas' Swag").
notes("This is good swag").
webPages(webpage).
build()
val contact = nylas.contacts().create("<NYLAS_GRANT_ID>", contactRequest)
print(contact.data)
}
get:
summary: Return all contacts
tags:
- Contacts
x-scopes:
google:
min:
- https://www.googleapis.com/auth/contacts.readonly
- https://www.googleapis.com/auth/contacts.other.readonly
- https://www.googleapis.com/auth/directory.readonly
others: ''
microsoft:
min:
- https://graph.microsoft.com/Contacts.Read
- https://graph.microsoft.com/People.Read
others: ''
responses:
'200':
$ref: '#/components/responses/contacts'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: list-contact
description: Return all contacts in a user's address book.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/limit_contacts'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/field_selection'
- name: email
in: query
schema:
type: string
description: Returns the contacts containing the specified email address.
- name: phone_number
in: query
schema:
type: string
description: (Google, IMAP, iCloud, Yahoo, and EWS only) Returns contacts containing the specified phone number.
- name: source
in: query
schema:
default: address_book
enum:
- address_book
- domain
- inbox
type: string
description: |-
Returns the specified contacts from the user's address book, domain, or any auto-generated
contacts from messages. If you want to filter for multiple sources, pass a comma-separated list
(for example, `source=address_book,inbox`).
EWS doesn't support `inbox`. Compound source filters are supported for IMAP and iCloud only.
- name: group
in: query
schema:
type: string
description: (Not supported for EWS) Returns the contacts included in the specified Contact Group.
- name: recurse
in: query
schema:
type: string
description: (Microsoft Only) When `true`, returns the contacts in the specified Contact Group subgroups. The recursion goes only one level deep.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchContacts() {
try {
const identifier = "<NYLAS_GRANT_ID>";
const contacts = await nylas.contacts.list({
identifier,
queryParams: {},
});
console.log("Recent Contacts:", contacts);
} catch (error) {
console.error("Error fetching drafts:", error);
}
}
fetchContacts();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
contacts = nylas.contacts.list(
grant_id,
)
print(contacts)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\ncontacts, _ = nylas.contacts.list(identifier: \"<NYLAS_GRANT_ID>\")\n\ncontacts.each {|contact|\n puts \"Name: #{contact[:given_name]} #{contact[:surname]} | \" \\\n \"Email: #{contact[:emails][0][:email]} | ID: #{contact[:id]}\"\n}"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReadAllContacts {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Contact> contacts = nylas.contacts().list("<NYLAS_GRANT_ID>");
for(Contact contact : contacts.getData()) {
System.out.println(contact);
System.out.println("\n");
}
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val contacts = nylas.contacts().list("<NYLAS_GRANT_ID>")
for(contact in contacts.data){
println(contact)
}
}
/v3/grants/{grant_id}/contacts/{contact_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: contact_id
in: path
required: true
description: |-
ID of the contact to access. Nylas recommends you URL-encode this field, or you might receive
a [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for
example, `#`).
get:
summary: Return a contact
tags:
- Contacts
x-scopes:
google:
min:
- https://www.googleapis.com/auth/contacts.readonly
- https://www.googleapis.com/auth/contacts.other.readonly
- https://www.googleapis.com/auth/directory.readonly
others: ''
microsoft:
min:
- https://graph.microsoft.com/Contacts.Read
- https://graph.microsoft.com/People.Read
others: ''
responses:
'200':
$ref: '#/components/responses/contact_with_picture'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: get-contact
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
description: Return a contact by ID.
parameters:
- $ref: '#/components/parameters/field_selection'
- name: profile_picture
in: query
schema:
type: boolean
description: If `true` and `picture_url` is present, the response includes a Base64 binary data blob that you can use to view information as an image file (for example, a JPEG).
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchContactById() {
try {
const contact = await nylas.contacts.find({
identifier: "<NYLAS_GRANT_ID>",
contactId: "<CONTACT_ID>",
queryParams: {},
});
console.log("contact:", contact);
} catch (error) {
console.error("Error fetching contact:", error);
}
}
fetchContactById();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
contact_id = "<CONTACT_ID>"
contact = nylas.contacts.find(
grant_id,
contact_id,
)
print(contact)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\ncontact, _ = nylas.contacts.find(identifier: \"<NYLAS_GRANT_ID>\", contact_id: \"<CONTACT_ID>\")\n\nputs contact"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReturnAContact {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Contact> contact = nylas.contacts().find("<NYLAS_GRANT_ID>", "<CONTACT_ID>");
System.out.println(contact);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
var contact = nylas.contacts().find("<NYLAS_GRANT_ID>", "<CONTACT_ID>")
print(contact)
}
put:
summary: Update a contact
tags:
- Contacts
x-scopes:
google:
min: https://www.googleapis.com/auth/contacts
others: ''
microsoft:
min: https://graph.microsoft.com/Contacts.ReadWrite
others: ''
responses:
'200':
$ref: '#/components/responses/contact'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: put-contact
description: |-
Updates the specified contact from the user's address book.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/field_selection'
requestBody:
$ref: '#/components/requestBodies/contact_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"birthday": "1960-12-31",
"company_name": "Nylas",
"emails": [
{
"email": "leyah.miller@example.com",
"type": "work"
},
{
"email": "leyah@example.com",
"type": "home"
}
],
"given_name": "Leyah",
"groups": [
{
"id": "starred"
},
{
"id": "all"
}
],
"im_addresses": [
{
"type": "jabber",
"im_address": "leyah_jabber"
},
{
"type": "msn",
"im_address": "leyah_msn"
}
],
"job_title": "Software Engineer",
"manager_name": "Bill",
"middle_name": "Allison",
"nickname": "Allie",
"notes": "Loves Ramen",
"office_location": "123 Main Street",
"phone_numbers": [
{
"number": "+1-555-555-5555",
"type": "work"
},
{
"number": "+1-555-555-5556",
"type": "home"
}
],
"physical_addresses": [
{
"type": "work",
"street_address": "123 Main Street",
"postal_code": "94107",
"state": "CA",
"country": "USA",
"city": "San Francisco"
},
{
"type": "home",
"street_address": "456 Main Street",
"postal_code": "94107",
"state": "CA",
"country": "USA",
"city": "San Francisco"
}
],
"source": "address_book",
"surname": "Miller",
"web_pages": [
{
"type": "work",
"url": "<WEBPAGE_URL>"
},
{
"type": "home",
"url": "<WEBPAGE_URL>"
}
]
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateContact() {
try {
const contact = await nylas.contacts.update({
identifier: "<NYLAS_GRANT_ID>",
contactId: "<CONTACT_ID>",
requestBody: {
givenName: "Nyla",
},
});
console.log("Contact:", JSON.stringify(contact));
} catch (error) {
console.error("Error to create contact:", error);
}
}
updateContact();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
contact_id = "<CONTACT_ID>"
contact = nylas.contacts.update(
grant_id,
contact_id,
request_body={
"given_name": "Nyla",
}
)
print(contact)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nrequest_body = {\n notes: \"This is *the best* swag\",\n}\n\ncontact, _ = nylas.contacts.update(identifier: \"<NYLAS_GRANT_ID>\", \n contact_id: \"<CONTACT_ID>\", \n request_body: request_body)\n\nputs contact"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class UpdateContact {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateContactRequest requestBody = new UpdateContactRequest.
Builder().
notes("This is *the best* swag").
build();
Response<Contact> contact = nylas.contacts().update("<NYLAS_GRANT_ID>", "<CONTACT_ID>", requestBody);
System.out.println(contact);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.*
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
val updateRequest = UpdateContactRequest.Builder().
notes("This is *the best* swag").
build()
val contact = nylas.contacts().update("<NYLAS_GRANT_ID>", "<CONTACT_ID>", updateRequest)
print(contact.data)
}
delete:
summary: Delete a contact
tags:
- Contacts
x-scopes:
google:
min: https://www.googleapis.com/auth/contacts
others: ''
microsoft:
min: https://graph.microsoft.com/Contacts.ReadWrite
others: ''
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: delete-contact
description: Delete a contact from the user's address book.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
const identifier = "<NYLAS_GRANT_ID>";
const contactId = "<CONTACT_ID>";
const deleteContact = async () => {
try {
await nylas.contacts.destroy({ identifier, contactId });
console.log(`Contact with ID ${contactId} deleted successfully.`);
} catch (error) {
console.error(`Error deleting contact with ID ${contactId}:`, error);
}
};
deleteContact();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
contact_id = "<CONTACT_ID>"
request = nylas.contacts.destroy(
grant_id,
contact_id,
)
print(request)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\nstatus, _ = nylas.contacts.destroy(identifier: \"<NYLAS_GRANT_ID>\", contact_id: \"<CONTACT_ID>\")\n\nputs status"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class DeleteAContact {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse contact = nylas.contacts().destroy("<NYLAS_GRANT_ID>", "<CONTACT_ID>");
System.out.println(contact);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
var contact = nylas.contacts().destroy("<NYLAS_GRANT_ID>", "<CONTACT_ID>")
print(contact)
}
/v3/grants/{grant_id}/contacts/groups:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
get:
summary: Return all Contact Groups
tags:
- Contacts
x-scopes:
google:
min:
- https://www.googleapis.com/auth/contacts.readonly
- https://www.googleapis.com/auth/contacts.other.readonly
- https://www.googleapis.com/auth/directory.readonly
others: ''
microsoft:
min:
- https://graph.microsoft.com/Contacts.Read
- https://graph.microsoft.com/People.Read
others: ''
responses:
'200':
$ref: '#/components/responses/contact_groups'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: list-contact-groups
description: (Not supported for EWS) Return a list of all Contact Groups associated with a grant.
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/field_selection'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/groups' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listContactGroups() {
try {
const groups = await nylas.contacts.groups({
identifier: "<NYLAS_GRANT_ID>",
});
console.log("Contact groups:", groups);
} catch (error) {
console.error("Error listing contact groups:", error);
}
}
listContactGroups();
- lang: python
label: Python SDK
source: |-
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>"
)
grant_id = "<NYLAS_GRANT_ID>"
contact_groups = nylas.contacts.list_groups(
grant_id,
)
print(contact_groups)
- lang: ruby
label: Ruby SDK
source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\ngroups = nylas.contacts.list_groups(identifier: \"<NYLAS_GRANT_ID>\")\n\nputs groups"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.*;
public class ReadContactGroups {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<ContactGroup> groups = nylas.contacts().listGroups("<NYLAS_GRANT_ID>");
System.out.println(groups);
}
}
- lang: kotlin
label: Kotlin SDK
source: |-
import com.nylas.NylasClient
fun main(args: Array<String>) {
val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
var groups = nylas.contacts().listGroups("<NYLAS_GRANT_ID>")
print(groups)
}
/v3/grants/{grant_id}/notetakers:
parameters:
- $ref: '#/components/parameters/grant_id'
get:
summary: Return all Notetakers
tags:
- Notetaker
operationId: get-all-notetakers
description: Returns a list of all Notetaker bots.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/join_time_start'
- $ref: '#/components/parameters/join_time_end'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/notetaker_order_by'
- $ref: '#/components/parameters/notetaker_order_direction'
- $ref: '#/components/parameters/notetaker_state'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/prev_page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listNotetakers() {
try {
const notetakers = await nylas.notetakers.list({
identifier: "<NYLAS_GRANT_ID>",
queryParams: {
limit: 50,
},
});
console.log("Notetakers:", notetakers);
} catch (error) {
console.error("Error listing notetakers:", error);
}
}
listNotetakers();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
notetakers = nylas.notetakers.list(
identifier="<NYLAS_GRANT_ID>",
query_params={
"limit": 50,
},
)
print("Notetakers:", notetakers)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.ListNotetakersQueryParams;
import com.nylas.models.ListResponse;
import com.nylas.models.Notetaker;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class ListNotetakers {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListNotetakersQueryParams queryParams = new ListNotetakersQueryParams.Builder()
.limit(50)
.build();
ListResponse<Notetaker> notetakers = nylas.notetakers().list(queryParams, "<NYLAS_GRANT_ID>");
System.out.println("Notetakers: " + notetakers.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.ListNotetakersQueryParams
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val queryParams = ListNotetakersQueryParams.Builder()
.limit(50)
.build()
val notetakers = nylas.notetakers().list(queryParams, "<NYLAS_GRANT_ID>")
println("Notetakers: ${notetakers.data}")
}
responses:
'200':
$ref: '#/components/responses/get-notetakers-200'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
post:
summary: Invite Notetaker to meeting
tags:
- Notetaker
operationId: invite-notetaker
description: |-
Adds a Notetaker bot to the specified meeting.
<div id="admonition-info">ℹ️ <b>Nylas doesn't de-duplicate Notetaker bots</b>. Every <code>POST /v3/grants/<NYLAS_GRANT_ID>/notetakers</code> request you make invites a new Notetaker to the specified meeting.</div>
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/notetakers'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"join_time": 1732657774,
"meeting_link": "https://meet.google.com/xyz-abcd-ijk",
"meeting_settings": {
"action_items": true,
"action_items_settings": {
"custom_instructions": "Only return the 5 most important action items."
},
"audio_recording": true,
"leave_after_silence_seconds": 360,
"summary": true,
"summary_settings": {
"custom_instructions": "Return this summary in the MEDPIC sales methodology."
},
"transcription": true,
"transcription_settings": {
"expected_languages": ["en", "es"],
"fallback_language": "en"
},
"video_recording": true
},
"name": "Nylas Notetaker"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function inviteNotetaker() {
try {
const notetaker = await nylas.notetakers.create({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
meetingLink: "https://meet.google.com/abc-defg-hij",
name: "Nylas Notetaker",
meetingSettings: {
videoRecording: true,
audioRecording: true,
transcription: true,
},
},
});
console.log("Notetaker:", notetaker);
} catch (error) {
console.error("Error inviting notetaker:", error);
}
}
inviteNotetaker();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
notetaker = nylas.notetakers.invite(
request_body={
"meeting_link": "https://meet.google.com/abc-defg-hij",
"name": "Nylas Notetaker",
"meeting_settings": {
"video_recording": True,
"audio_recording": True,
"transcription": True,
},
},
identifier="<NYLAS_GRANT_ID>",
)
print("Invited notetaker:", notetaker)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.CreateNotetakerRequest;
import com.nylas.models.Notetaker;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class InviteNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CreateNotetakerRequest.MeetingSettings meetingSettings =
new CreateNotetakerRequest.MeetingSettings.Builder()
.videoRecording(true)
.audioRecording(true)
.transcription(true)
.build();
CreateNotetakerRequest requestBody = new CreateNotetakerRequest.Builder(
"https://meet.google.com/abc-defg-hij")
.name("Nylas Notetaker")
.meetingSettings(meetingSettings)
.build();
Response<Notetaker> notetaker = nylas.notetakers().create(requestBody, "<NYLAS_GRANT_ID>");
System.out.println("Notetaker: " + notetaker.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.CreateNotetakerRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val meetingSettings = CreateNotetakerRequest.MeetingSettings.Builder()
.videoRecording(true)
.audioRecording(true)
.transcription(true)
.build()
val requestBody = CreateNotetakerRequest.Builder("https://meet.google.com/abc-defg-hij")
.name("Nylas Notetaker")
.meetingSettings(meetingSettings)
.build()
val notetaker = nylas.notetakers().create(requestBody, "<NYLAS_GRANT_ID>")
println("Notetaker: ${notetaker.data}")
}
responses:
'201':
$ref: '#/components/responses/invite-to-meeting-201'
'400':
$ref: '#/components/responses/400-2'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
/v3/grants/{grant_id}/notetakers/{notetaker_id}:
parameters:
- $ref: '#/components/parameters/grant_id'
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the Notetaker bot to access.
example: 71c807752c744ad0902f64d43e6cc399
get:
summary: Return a Notetaker
tags:
- Notetaker
operationId: get-notetaker
description: Returns the specified Notetaker bot and its details.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function findNotetaker() {
try {
const notetaker = await nylas.notetakers.find({
identifier: "<NYLAS_GRANT_ID>",
notetakerId: "<NOTETAKER_ID>",
});
console.log("Notetaker:", notetaker);
} catch (error) {
console.error("Error finding notetaker:", error);
}
}
findNotetaker();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
notetaker = nylas.notetakers.find(
notetaker_id="<NOTETAKER_ID>",
identifier="<NYLAS_GRANT_ID>",
)
print("Notetaker:", notetaker)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Notetaker;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class FindNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Notetaker> notetaker = nylas.notetakers().find("<NOTETAKER_ID>", "<NYLAS_GRANT_ID>");
System.out.println("Notetaker: " + notetaker.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val notetaker = nylas.notetakers().find("<NOTETAKER_ID>", "<NYLAS_GRANT_ID>")
println("Notetaker: ${notetaker.data}")
}
responses:
'200':
$ref: '#/components/responses/get-notetaker-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
patch:
summary: Update scheduled Notetaker
tags:
- Notetaker
operationId: update-notetaker
description: Updates the specified scheduled Notetaker bot.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/patch-notetaker'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PATCH \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"join_time": 1732657774,
"meeting_settings": {
"action_items": true,
"action_items_settings": {
"custom_instructions": "Only return the 5 most important action items."
},
"audio_recording": true,
"summary": true,
"summary_settings": {
"custom_instructions": "Return this summary in the MEDPIC sales methodology."
},
"transcription": true,
"transcription_settings": {
"expected_languages": ["en", "es"],
"fallback_language": "en"
},
"video_recording": true
},
"name": "Nylas Notetaker",
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateNotetaker() {
try {
const notetaker = await nylas.notetakers.update({
identifier: "<NYLAS_GRANT_ID>",
notetakerId: "<NOTETAKER_ID>",
requestBody: {
name: "Updated Notetaker name",
meetingSettings: {
transcription: false,
},
},
});
console.log("Updated notetaker:", notetaker);
} catch (error) {
console.error("Error updating notetaker:", error);
}
}
updateNotetaker();
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Notetaker;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
import com.nylas.models.UpdateNotetakerRequest;
public class UpdateNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateNotetakerRequest.MeetingSettings meetingSettings =
new UpdateNotetakerRequest.MeetingSettings.Builder()
.transcription(false)
.build();
UpdateNotetakerRequest requestBody = new UpdateNotetakerRequest.Builder()
.name("Updated Notetaker name")
.meetingSettings(meetingSettings)
.build();
Response<Notetaker> notetaker = nylas.notetakers().update(
"<NOTETAKER_ID>", requestBody, "<NYLAS_GRANT_ID>");
System.out.println("Updated notetaker: " + notetaker.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.UpdateNotetakerRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val meetingSettings = UpdateNotetakerRequest.MeetingSettings.Builder()
.transcription(false)
.build()
val requestBody = UpdateNotetakerRequest.Builder()
.name("Updated Notetaker name")
.meetingSettings(meetingSettings)
.build()
val notetaker = nylas.notetakers().update(
"<NOTETAKER_ID>", requestBody, "<NYLAS_GRANT_ID>")
println("Updated notetaker: ${notetaker.data}")
}
responses:
'200':
$ref: '#/components/responses/get-notetaker-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
delete:
summary: Delete a Notetaker
tags:
- Notetaker
operationId: delete-notetaker
description: Permanently deletes the specified Notetaker and all associated data, including any recordings, transcripts, thumbnails, summaries, and action items. This works regardless of the Notetaker's current state — scheduled, active, or completed. This is a hard delete and cannot be undone. Once deleted, Nylas cannot recover the Notetaker or any of its data.
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request DELETE \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/delete-notetaker-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/v3/grants/{grant_id}/notetakers/{notetaker_id}/history:
parameters:
- $ref: '#/components/parameters/grant_id'
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the Notetaker bot to access.
example: 71c807752c744ad0902f64d43e6cc399
get:
summary: Return Notetaker history
tags:
- Notetaker
operationId: get-notetaker-history
description: Returns the full history of events and state changes for the specified Notetaker bot.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |+
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/history" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
responses:
'200':
$ref: '#/components/responses/get-notetaker-history-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/v3/grants/{grant_id}/notetakers/{notetaker_id}/cancel:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access.
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the Notetaker bot to access.
delete:
summary: Cancel Notetaker before it joins
tags:
- Notetaker
operationId: cancel-notetaker
description: Cancels a Notetaker while its status is `scheduled`, `connecting`, or `waiting_for_entry`, preventing it from joining the meeting. After the Notetaker joins the meeting, use the leave endpoint. To permanently delete a Notetaker in any state, use the delete endpoint instead.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/cancel" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function cancelNotetaker() {
try {
const result = await nylas.notetakers.cancel({
identifier: "<NYLAS_GRANT_ID>",
notetakerId: "<NOTETAKER_ID>",
});
console.log("Cancelled notetaker:", result);
} catch (error) {
console.error("Error cancelling notetaker:", error);
}
}
cancelNotetaker();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.notetakers.cancel(
notetaker_id="<NOTETAKER_ID>",
identifier="<NYLAS_GRANT_ID>",
)
print("Notetaker cancelled:", response)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.DeleteResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class CancelNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse result = nylas.notetakers().cancel("<NOTETAKER_ID>", "<NYLAS_GRANT_ID>");
System.out.println("Cancelled notetaker: " + result);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val result = nylas.notetakers().cancel("<NOTETAKER_ID>", "<NYLAS_GRANT_ID>")
println("Cancelled notetaker: $result")
}
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/cancel-notetaker-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'429':
$ref: '#/components/responses/429'
/v3/grants/{grant_id}/notetakers/{notetaker_id}/leave:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: ID of the grant to access.
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the Notetaker bot to access.
post:
summary: Remove Notetaker from meeting
tags:
- Notetaker
operationId: post-notetaker-leave
description: Sends a request to the specified Notetaker bot to leave the meeting it's currently attending. If the Notetaker's status is `scheduled`, `connecting`, or `waiting_for_entry`, use the cancel endpoint instead.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/leave" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function leaveMeeting() {
try {
const result = await nylas.notetakers.leave({
identifier: "<NYLAS_GRANT_ID>",
notetakerId: "<NOTETAKER_ID>",
});
console.log("Notetaker left meeting:", result);
} catch (error) {
console.error("Error leaving meeting:", error);
}
}
leaveMeeting();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.notetakers.leave(
notetaker_id="<NOTETAKER_ID>",
identifier="<NYLAS_GRANT_ID>",
)
print("Notetaker left meeting:", response)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.LeaveNotetakerResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class LeaveNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<LeaveNotetakerResponse> result = nylas.notetakers().leave(
"<NOTETAKER_ID>", "<NYLAS_GRANT_ID>");
System.out.println("Notetaker left meeting: " + result.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val result = nylas.notetakers().leave("<NOTETAKER_ID>", "<NYLAS_GRANT_ID>")
println("Notetaker left meeting: ${result.data}")
}
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/leave-meeting-200'
'202':
$ref: '#/components/responses/leave-meeting-202'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'429':
$ref: '#/components/responses/429'
/v3/grants/{grant_id}/notetakers/{notetaker_id}/media:
parameters:
- $ref: '#/components/parameters/grant_id'
- name: notetaker_id
schema:
type: string
in: path
required: true
description: ID of the Notetaker bot to access.
get:
summary: Return Notetaker media links
tags:
- Notetaker
operationId: get-notetaker-media
description: Returns a list of links to media generated by the specified Notetaker bot.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/media" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function downloadMedia() {
try {
const media = await nylas.notetakers.downloadMedia({
identifier: "<NYLAS_GRANT_ID>",
notetakerId: "<NOTETAKER_ID>",
});
console.log("Media:", media);
} catch (error) {
console.error("Error downloading media:", error);
}
}
downloadMedia();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
media = nylas.notetakers.get_media(
notetaker_id="<NOTETAKER_ID>",
identifier="<NYLAS_GRANT_ID>",
)
print("Notetaker media:", media)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.NotetakerMediaResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class DownloadNotetakerMedia {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<NotetakerMediaResponse> media = nylas.notetakers().downloadMedia(
"<NOTETAKER_ID>", "<NYLAS_GRANT_ID>");
System.out.println("Media: " + media.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val media = nylas.notetakers().downloadMedia("<NOTETAKER_ID>", "<NYLAS_GRANT_ID>")
println("Media: ${media.data}")
}
responses:
'200':
$ref: '#/components/responses/get-notetaker-media-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/v3/notetakers:
get:
summary: Return all standalone Notetakers
tags:
- Standalone Notetaker
operationId: get-all-standalone-notetakers
description: Returns a list of standalone Notetaker bots.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/join_time_end'
- $ref: '#/components/parameters/join_time_start'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/notetaker_order_by'
- $ref: '#/components/parameters/notetaker_order_direction'
- $ref: '#/components/parameters/notetaker_state'
- $ref: '#/components/parameters/page_token'
- $ref: '#/components/parameters/prev_page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/notetakers" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listStandaloneNotetakers() {
try {
const notetakers = await nylas.notetakers.list({
queryParams: {
limit: 50,
},
});
console.log("Standalone notetakers:", notetakers);
} catch (error) {
console.error("Error listing notetakers:", error);
}
}
listStandaloneNotetakers();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
notetakers = nylas.notetakers.list(
query_params={
"limit": 50,
},
)
print("Standalone notetakers:", notetakers)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.ListNotetakersQueryParams;
import com.nylas.models.ListResponse;
import com.nylas.models.Notetaker;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class ListStandaloneNotetakers {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListNotetakersQueryParams queryParams = new ListNotetakersQueryParams.Builder()
.limit(50)
.build();
// Omit the grant identifier to query the standalone (account-level) Notetakers.
ListResponse<Notetaker> notetakers = nylas.notetakers().list(queryParams);
System.out.println("Standalone notetakers: " + notetakers.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.ListNotetakersQueryParams
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val queryParams = ListNotetakersQueryParams.Builder()
.limit(50)
.build()
// Omit the grant identifier to query the standalone (account-level) Notetakers.
val notetakers = nylas.notetakers().list(queryParams)
println("Standalone notetakers: ${notetakers.data}")
}
responses:
'200':
$ref: '#/components/responses/get-standalone-notetakers-200'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
post:
summary: Invite standalone Notetaker to meeting
tags:
- Standalone Notetaker
operationId: invite-standalone-notetaker
description: |-
Adds a standalone Notetaker bot to the specified meeting.
<div id="admonition-info">ℹ️ <b>Nylas doesn't de-duplicate Notetaker bots</b>. Every <code>POST /v3/notetakers</code> request you make invites a new Notetaker to the specified meeting.</div>
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/notetakers'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/notetakers" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"join_time": 1732657774,
"meeting_link": "https://meet.google.com/xyz-abcd-ijk",
"meeting_settings": {
"action_items": true,
"action_items_settings": {
"custom_instructions": "Only return the 5 most important action items."
},
"audio_recording": true,
"leave_after_silence_seconds": 360,
"summary": true,
"summary_settings": {
"custom_instructions": "Return this summary in the MEDPIC sales methodology."
},
"transcription": true,
"transcription_settings": {
"expected_languages": ["en", "es"],
"fallback_language": "en"
},
"video_recording": true
},
"name": "Nylas Notetaker"
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function inviteStandaloneNotetaker() {
try {
const notetaker = await nylas.notetakers.create({
requestBody: {
meetingLink: "https://meet.google.com/abc-defg-hij",
name: "Nylas Notetaker",
meetingSettings: {
videoRecording: true,
audioRecording: true,
transcription: true,
},
},
});
console.log("Standalone notetaker:", notetaker);
} catch (error) {
console.error("Error inviting notetaker:", error);
}
}
inviteStandaloneNotetaker();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
notetaker = nylas.notetakers.invite(
request_body={
"meeting_link": "https://meet.google.com/abc-defg-hij",
"name": "Nylas Notetaker",
"meeting_settings": {
"video_recording": True,
"audio_recording": True,
"transcription": True,
},
},
)
print("Invited standalone notetaker:", notetaker)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.CreateNotetakerRequest;
import com.nylas.models.Notetaker;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class InviteStandaloneNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CreateNotetakerRequest.MeetingSettings meetingSettings =
new CreateNotetakerRequest.MeetingSettings.Builder()
.videoRecording(true)
.audioRecording(true)
.transcription(true)
.build();
CreateNotetakerRequest requestBody = new CreateNotetakerRequest.Builder(
"https://meet.google.com/abc-defg-hij")
.name("Nylas Notetaker")
.meetingSettings(meetingSettings)
.build();
// Omit the grant identifier to create a standalone (account-level) Notetaker.
Response<Notetaker> notetaker = nylas.notetakers().create(requestBody);
System.out.println("Standalone notetaker: " + notetaker.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.CreateNotetakerRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val meetingSettings = CreateNotetakerRequest.MeetingSettings.Builder()
.videoRecording(true)
.audioRecording(true)
.transcription(true)
.build()
val requestBody = CreateNotetakerRequest.Builder("https://meet.google.com/abc-defg-hij")
.name("Nylas Notetaker")
.meetingSettings(meetingSettings)
.build()
// Omit the grant identifier to create a standalone (account-level) Notetaker.
val notetaker = nylas.notetakers().create(requestBody)
println("Standalone notetaker: ${notetaker.data}")
}
responses:
'201':
$ref: '#/components/responses/invite-to-standalone-meeting-201'
'400':
$ref: '#/components/responses/400-2'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
/v3/notetakers/{notetaker_id}:
parameters:
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the Notetaker bot to access.
example: 71c807752c744ad0902f64d43e6cc399
get:
summary: Return a standalone Notetaker
tags:
- Standalone Notetaker
operationId: get-standalone-notetaker
description: Returns the specified Notetaker bot and its details.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function findStandaloneNotetaker() {
try {
const notetaker = await nylas.notetakers.find({
notetakerId: "<NOTETAKER_ID>",
});
console.log("Standalone notetaker:", notetaker);
} catch (error) {
console.error("Error finding notetaker:", error);
}
}
findStandaloneNotetaker();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
notetaker = nylas.notetakers.find(
notetaker_id="<NOTETAKER_ID>",
)
print("Standalone notetaker:", notetaker)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Notetaker;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class FindStandaloneNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Omit the grant identifier to look up a standalone (account-level) Notetaker.
Response<Notetaker> notetaker = nylas.notetakers().find("<NOTETAKER_ID>");
System.out.println("Standalone notetaker: " + notetaker.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
// Omit the grant identifier to look up a standalone (account-level) Notetaker.
val notetaker = nylas.notetakers().find("<NOTETAKER_ID>")
println("Standalone notetaker: ${notetaker.data}")
}
responses:
'200':
$ref: '#/components/responses/get-standalone-notetaker-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
patch:
summary: Update standalone Notetaker
tags:
- Standalone Notetaker
operationId: update-standalone-notetaker
description: Updates the specified scheduled standalone Notetaker bot.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/patch-notetaker'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PATCH \
--url "https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Nylas Notetaker",
"join_time": 1732657774,
"meeting_settings": {
"action_items": true,
"action_items_settings": {
"custom_instructions": "Only return the 5 most important action items."
},
"audio_recording": true,
"summary": true,
"summary_settings": {
"custom_instructions": "Return this summary in the MEDPIC sales methodology."
},
"transcription": true,
"transcription_settings": {
"expected_languages": ["en", "es"],
"fallback_language": "en"
},
"video_recording": true
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateStandaloneNotetaker() {
try {
const notetaker = await nylas.notetakers.update({
notetakerId: "<NOTETAKER_ID>",
requestBody: {
name: "Updated Notetaker name",
meetingSettings: {
transcription: false,
},
},
});
console.log("Updated notetaker:", notetaker);
} catch (error) {
console.error("Error updating notetaker:", error);
}
}
updateStandaloneNotetaker();
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Notetaker;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
import com.nylas.models.UpdateNotetakerRequest;
public class UpdateStandaloneNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
UpdateNotetakerRequest.MeetingSettings meetingSettings =
new UpdateNotetakerRequest.MeetingSettings.Builder()
.transcription(false)
.build();
UpdateNotetakerRequest requestBody = new UpdateNotetakerRequest.Builder()
.name("Updated Notetaker name")
.meetingSettings(meetingSettings)
.build();
// Omit the grant identifier to update a standalone (account-level) Notetaker.
Response<Notetaker> notetaker = nylas.notetakers().update("<NOTETAKER_ID>", requestBody);
System.out.println("Updated standalone notetaker: " + notetaker.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.UpdateNotetakerRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val meetingSettings = UpdateNotetakerRequest.MeetingSettings.Builder()
.transcription(false)
.build()
val requestBody = UpdateNotetakerRequest.Builder()
.name("Updated Notetaker name")
.meetingSettings(meetingSettings)
.build()
// Omit the grant identifier to update a standalone (account-level) Notetaker.
val notetaker = nylas.notetakers().update("<NOTETAKER_ID>", requestBody)
println("Updated standalone notetaker: ${notetaker.data}")
}
responses:
'200':
$ref: '#/components/responses/get-standalone-notetaker-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
delete:
summary: Delete a standalone Notetaker
tags:
- Standalone Notetaker
operationId: delete-standalone-notetaker
description: Permanently deletes the specified Notetaker and all associated data, including any recordings, transcripts, thumbnails, summaries, and action items. This works regardless of the Notetaker's current state — scheduled, active, or completed. This is a hard delete and cannot be undone. Once deleted, Nylas cannot recover the Notetaker or any of its data.
x-code-samples:
- lang: bash
label: cURL
source: |
curl --request DELETE \
--url "https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/delete-notetaker-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/v3/notetakers/{notetaker_id}/history:
parameters:
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the standalone Notetaker bot to access.
example: 71c807752c744ad0902f64d43e6cc399
get:
summary: Return standalone Notetaker history
tags:
- Standalone Notetaker
operationId: get-standalone-notetaker-history
description: Returns the full history of events and state changes for the specified standalone Notetaker bot.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |+
curl --request GET \
--url "https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>/history" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
responses:
'200':
$ref: '#/components/responses/get-standalone-notetaker-history-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/v3/notetakers/{notetaker_id}/cancel:
parameters:
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the Notetaker bot to access.
delete:
summary: Cancel standalone Notetaker before it joins
tags:
- Standalone Notetaker
operationId: cancel-standalone-notetaker
description: Cancels a standalone Notetaker while its status is `scheduled`, `connecting`, or `waiting_for_entry`, preventing it from joining the meeting. After the Notetaker joins the meeting, use the leave endpoint. To permanently delete a Notetaker in any state, use the delete endpoint instead.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url "https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>/cancel" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function cancelStandaloneNotetaker() {
try {
const result = await nylas.notetakers.cancel({
notetakerId: "<NOTETAKER_ID>",
});
console.log("Cancelled notetaker:", result);
} catch (error) {
console.error("Error cancelling notetaker:", error);
}
}
cancelStandaloneNotetaker();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.notetakers.cancel(
notetaker_id="<NOTETAKER_ID>",
)
print("Standalone notetaker cancelled:", response)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.DeleteResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class CancelStandaloneNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Omit the grant identifier to cancel a standalone (account-level) Notetaker.
DeleteResponse result = nylas.notetakers().cancel("<NOTETAKER_ID>");
System.out.println("Cancelled standalone notetaker: " + result);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
// Omit the grant identifier to cancel a standalone (account-level) Notetaker.
val result = nylas.notetakers().cancel("<NOTETAKER_ID>")
println("Cancelled standalone notetaker: $result")
}
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/cancel-notetaker-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'429':
$ref: '#/components/responses/429'
/v3/notetakers/{notetaker_id}/leave:
parameters:
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the Notetaker bot to access.
post:
summary: Remove standalone Notetaker from meeting
tags:
- Standalone Notetaker
operationId: post-standalone-notetaker-leave
description: Sends a request to the specified standalone Notetaker bot to leave the meeting it's currently attending. If the Notetaker's status is `scheduled`, `connecting`, or `waiting_for_entry`, use the cancel endpoint instead.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>/leave" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function leaveStandaloneMeeting() {
try {
const result = await nylas.notetakers.leave({
notetakerId: "<NOTETAKER_ID>",
});
console.log("Notetaker left meeting:", result);
} catch (error) {
console.error("Error leaving meeting:", error);
}
}
leaveStandaloneMeeting();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.notetakers.leave(
notetaker_id="<NOTETAKER_ID>",
)
print("Standalone notetaker left meeting:", response)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.LeaveNotetakerResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class LeaveStandaloneNotetaker {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Omit the grant identifier to remove a standalone (account-level) Notetaker.
Response<LeaveNotetakerResponse> result = nylas.notetakers().leave("<NOTETAKER_ID>");
System.out.println("Standalone notetaker left meeting: " + result.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
// Omit the grant identifier to remove a standalone (account-level) Notetaker.
val result = nylas.notetakers().leave("<NOTETAKER_ID>")
println("Standalone notetaker left meeting: ${result.data}")
}
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/leave-meeting-200'
'202':
$ref: '#/components/responses/leave-meeting-202'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'429':
$ref: '#/components/responses/429'
/v3/notetakers/{notetaker_id}/media:
parameters:
- schema:
type: string
name: notetaker_id
in: path
required: true
description: ID of the Notetaker bot to access.
get:
summary: Return standalone Notetaker media links
tags:
- Standalone Notetaker
operationId: get-standalone-notetaker-media
description: Returns a list of links to media generated by the specified standalone Notetaker bot.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>/media" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function downloadStandaloneMedia() {
try {
const media = await nylas.notetakers.downloadMedia({
notetakerId: "<NOTETAKER_ID>",
});
console.log("Media:", media);
} catch (error) {
console.error("Error downloading media:", error);
}
}
downloadStandaloneMedia();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
media = nylas.notetakers.get_media(
notetaker_id="<NOTETAKER_ID>",
)
print("Standalone notetaker media:", media)
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.NotetakerMediaResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class DownloadStandaloneNotetakerMedia {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
// Omit the grant identifier for standalone (account-level) Notetaker media.
Response<NotetakerMediaResponse> media = nylas.notetakers().downloadMedia("<NOTETAKER_ID>");
System.out.println("Media: " + media.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
// Omit the grant identifier for standalone (account-level) Notetaker media.
val media = nylas.notetakers().downloadMedia("<NOTETAKER_ID>")
println("Media: ${media.data}")
}
responses:
'200':
$ref: '#/components/responses/get-notetaker-media-200'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/v3/templates:
get:
summary: Return all templates
tags:
- Application-level templates
operationId: list-app-level-templates
description: Returns a list of application-level templates.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/templates" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/templates_list'
'400':
$ref: '#/components/responses/template_400'
post:
summary: Create a template
tags:
- Application-level templates
operationId: create-app-level-template
description: Creates an application-level template.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/template_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/templates" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"body": "<p>Hello from {{user}}</p>",
"name": "Nylas Alias",
"subject": "New notification for {{user}}",
"engine": "mustache"
}'
responses:
'200':
$ref: '#/components/responses/template'
'400':
$ref: '#/components/responses/template_400'
/v3/templates/{template_id}:
parameters:
- schema:
type: string
name: template_id
in: path
required: true
description: The ID of the template to access.
example: 14c00cc8-648c-4381-ad10-52641d9bac8e
get:
summary: Return a template
tags:
- Application-level templates
operationId: get-app-level-template
description: Returns the specified application-level template.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/template'
'400':
$ref: '#/components/responses/template_400'
put:
summary: Update a template
tags:
- Application-level templates
operationId: update-app-level-template
description: Updates the specified application-level template.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/template_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PUT \
--url "https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"body": "<p>Test from {{user.name}}</p>",
"name": "Update Template",
"subject": "Test from {{user.name}}",
"engine": "mustache"
}'
responses:
'200':
$ref: '#/components/responses/template'
'400':
$ref: '#/components/responses/template_400'
delete:
summary: Delete a template
tags:
- Application-level templates
operationId: delete-app-level-template
description: Deletes the specified application-level template.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url "https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/delete_200_simple'
'400':
$ref: '#/components/responses/400'
/v3/templates/render:
post:
summary: Render template as HTML
tags:
- Application-level templates
operationId: render-template-html
description: |-
Renders the HTML content of an application-level template using the provided variables and specified
templating engine.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/template_render_html'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/templates/render" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"body": "<p>Hello from {{user.name}}, test {{ foo }}</p>",
"variables": {
"user": {
"name": "Nylas",
"surname": "Tester"
},
"foo": "hi"
},
"engine": "mustache"
}'
responses:
'200':
$ref: '#/components/responses/template_render_html'
'400':
$ref: '#/components/responses/template_400'
/v3/templates/{template_id}/render:
parameters:
- schema:
type: string
name: template_id
in: path
required: true
description: The ID of the template to access.
example: 14c00cc8-648c-4381-ad10-52641d9bac8e
post:
summary: Render a template
tags:
- Application-level templates
operationId: render-app-level-template
description: Renders the specified application-level template with the provided variables.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/template_render'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>/render" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"variables": {
"user": {
"name": "Nylas",
"surname": "Tester"
}
}
}'
responses:
'200':
$ref: '#/components/responses/template_render'
'400':
$ref: '#/components/responses/template_400'
/v3/grants/{grant_id}/templates:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
get:
summary: Return all templates
tags:
- Grant-level templates
operationId: get-grant-level-templates
description: Returns a list of grant-level templates.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/templates_list'
'400':
$ref: '#/components/responses/template_400'
post:
summary: Create a template
tags:
- Grant-level templates
operationId: create-grant-level-template
description: Creates a grant-level template.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/template_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"body": "<p>Hello from {{user}}</p>",
"name": "Nylas Alias",
"subject": "New notification for {{user}}",
"engine": "mustache"
}'
responses:
'200':
$ref: '#/components/responses/template'
'400':
$ref: '#/components/responses/template_400'
/v3/grants/{grant_id}/templates/{template_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
- schema:
type: string
name: template_id
in: path
required: true
description: The ID of the template to access.
example: 14c00cc8-648c-4381-ad10-52641d9bac8e
get:
summary: Return a template
tags:
- Grant-level templates
operationId: get-grant-level-template
description: Returns the specified grant-level template.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/<TEMPLATE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/template'
'400':
$ref: '#/components/responses/template_400'
put:
summary: Update a template
tags:
- Grant-level templates
operationId: update-grant-level-template
description: Updates the specified grant-level template.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/template_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PUT \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/<TEMPLATE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"body": "<p>Test from {{user.name}}</p>",
"name": "Update Template",
"subject": "Test from {{user.name}}",
"engine": "mustache"
}'
responses:
'200':
$ref: '#/components/responses/template'
'400':
$ref: '#/components/responses/template_400'
delete:
summary: Delete a template
tags:
- Grant-level templates
operationId: delete-grant-level-template
description: Deletes the specified grant-level template.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/<TEMPLATE_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/delete_200_simple'
'400':
$ref: '#/components/responses/400'
/v3/grants/{grant_id}/templates/{template_id}/render:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
- schema:
type: string
name: template_id
in: path
required: true
description: The ID of the template to access.
example: 14c00cc8-648c-4381-ad10-52641d9bac8e
post:
summary: Render a template
tags:
- Grant-level templates
operationId: render-grant-level-template
description: Renders the specified application-level template with the provided variables.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/template_render'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/<TEMPLATE_ID>/render" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"variables": {
"user": {
"name": "Nylas",
"surname": "Tester"
}
}
}'
responses:
'200':
$ref: '#/components/responses/template_render'
'400':
$ref: '#/components/responses/template_400'
/v3/grants/{grant_id}/templates/render:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
post:
summary: Render template as HTML
tags:
- Grant-level templates
operationId: render-grant-level-template-html
description: |-
Renders the HTML content of a grant-level template using the provided variables and specified
templating engine.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/template_render_html'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/render" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"body": "<p>Hello from {{user.name}}, test {{ foo }}</p>",
"variables": {
"user": {
"name": "Nylas",
"surname": "Tester"
},
"foo": "hi"
},
"engine": "mustache"
}'
responses:
'200':
$ref: '#/components/responses/template_render_html'
'400':
$ref: '#/components/responses/template_400'
/v3/workflows:
get:
summary: Return all workflows
tags:
- Application-level workflows
operationId: list-workflows
description: Returns all application-level workflows.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/workflows?limit=10" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/workflows_list'
'400':
$ref: '#/components/responses/workflow_400'
post:
summary: Create a workflow
tags:
- Application-level workflows
operationId: create-workflow
description: |-
Creates an application-level workflow.
<div id="admonition-info">ℹ️ <b>You must have an existing <a href="/docs/reference/api/application-level-templates/">template</a> to create a workflow</b>.</div>
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/workflow_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url "https://api.us.nylas.com/v3/workflows" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Confirmation Workflow",
"trigger_event": "booking.created",
"template_id": "<TEMPLATE_ID>",
"delay": 1,
"is_enabled": true
}'
responses:
'200':
$ref: '#/components/responses/workflow'
'400':
$ref: '#/components/responses/workflow_400'
'404':
$ref: '#/components/responses/workflow_404'
/v3/workflows/{workflow_id}:
parameters:
- schema:
type: string
name: workflow_id
in: path
required: true
description: The ID of the workflow to access.
example: b79c82b2-a51b-4c54-8469-28006a43551a
get:
summary: Return a workflow
tags:
- Application-level workflows
operationId: get-workflow
description: Returns the specified application-level workflow.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/workflows/<WORKFLOW_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/workflow'
'400':
$ref: '#/components/responses/400'
put:
summary: Update a workflow
tags:
- Application-level workflows
operationId: update-workflow
description: Updates the specified application-level workflow.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
requestBody:
$ref: '#/components/requestBodies/workflow_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PUT \
--url "https://api.us.nylas.com/v3/workflows/<WORKFLOW_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Updated Workflow",
"is_enabled": false
}'
responses:
'200':
$ref: '#/components/responses/workflow'
'400':
$ref: '#/components/responses/workflow_400'
'404':
$ref: '#/components/responses/workflow_404'
delete:
summary: Delete a workflow
tags:
- Application-level workflows
operationId: delete-workflow
description: Deletes the specified application-level workflow.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url "https://api.us.nylas.com/v3/workflows/<WORKFLOW_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/delete_200_simple'
'400':
$ref: '#/components/responses/400'
/v3/grants/{grant_id}/workflows:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
get:
summary: Return all workflows
tags:
- Grant-level workflows
operationId: list-grant-workflows
description: Returns all grant-level workflows for the specified grant.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows?limit=10" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/workflows_list'
'400':
$ref: '#/components/responses/400'
post:
summary: Create a workflow
tags:
- Grant-level workflows
operationId: create-grant-workflow
description: |-
Creates a grant-level workflow.
<div id="admonition-info">ℹ️ <b>You must have an existing <a href="/docs/reference/api/grant-level-templates/">template</a> to create a workflow</b>.</div>
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/workflow_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Confirmation Workflow",
"trigger_event": "booking.created",
"template_id": "<TEMPLATE_ID>",
"delay": 1,
"is_enabled": true
}'
responses:
'200':
$ref: '#/components/responses/workflow'
'400':
$ref: '#/components/responses/workflow_400'
'404':
$ref: '#/components/responses/workflow_404'
/v3/grants/{grant_id}/workflows/{workflow_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
- schema:
type: string
name: workflow_id
in: path
required: true
description: The ID of the workflow to access.
example: b79c82b2-a51b-4c54-8469-28006a43551a
get:
summary: Get a workflow
tags:
- Grant-level workflows
operationId: get-grant-workflow
description: Returns the specified grant-level workflow.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows/<WORKFLOW_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/workflow'
'400':
$ref: '#/components/responses/400'
put:
summary: Update a workflow
tags:
- Grant-level workflows
operationId: update-grant-workflow
description: Updates the specified grant-level workflow.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
requestBody:
$ref: '#/components/requestBodies/workflow_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request PUT \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows/<WORKFLOW_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Updated Workflow",
"is_enabled": false
}'
responses:
'200':
$ref: '#/components/responses/workflow'
'400':
$ref: '#/components/responses/workflow_400'
'404':
$ref: '#/components/responses/workflow_404'
delete:
summary: Delete a workflow
tags:
- Grant-level workflows
operationId: delete-grant-workflow
description: Deletes the specified grant-level workflow.
x-scopes:
google:
min: ''
microsoft:
min: ''
yahoo:
min: ''
security:
- NYLAS_API_KEY: []
- ACCESS_TOKEN: []
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request DELETE \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows/<WORKFLOW_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/delete_200_simple'
'400':
$ref: '#/components/responses/400'
/v3/grants/{grant_id}/scheduling/configurations:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
post:
summary: Create Configuration
tags:
- Configurations
operationId: post-configurations
description: |-
Creates a Configuration object that you use to define settings and preferences for a scheduling
session.
### Duplicate email notifications
If the organizer in a scheduling session is a Microsoft account user, both the organizer and all
attendees might receive duplicate email notifications, including booking confirmations, rescheduling
and cancellation notifications, and reminders. This is because of the way Microsoft handles email
notifications. If you set notifications in Scheduler, Microsoft also sends its own notifications
to the event organizer and attendees. Microsoft doesn't provide a way to disable these
notifications.
### Metadata as additional fields
You can add metadata fields (`type: metadata`) to your Configuration to store custom information
about a booking. For example, you can add campaign tags or keywords to track specific bookings.
Booking webhook notifications (`booking.created`, `booking.rescheduled`, `booking.cancelled`,
`booking.pending`, and `booking.reminder`) include your metadata fields in
`booking_info.additional_fields`. Calendar event webhooks (for example, `event.updated`) do _not_
include them, and email notifications and booking forms don't display them.
To identify Scheduler-related changes in event webhooks instead, use the metadata that Scheduler
stamps on the calendar events it creates. For more information, see the
[`event.updated` notification schema](/docs/reference/notifications/events/event-updated/).
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.readonly
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
security:
- NYLAS_API_KEY: []
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/configuration'
title: Standard Configuration
- $ref: '#/components/schemas/group-configuration'
title: Group Configuration
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"requires_session_auth": false,
"participants": [{
"name": "Nyla",
"email": "nyla@example.com",
"is_organizer": true,
"availability": {
"calendar_ids": ["primary"]
},
"booking": {
"calendar_id": "primary"
}
}],
"availability": {
"duration_minutes": 30
},
"event_booking": {
"title": "Testing Scheduler",
"hide_participants": false,
"conferencing": {
"provider": "Zoom Meeting",
"autocreate": {
"conf_grant_id": "<NYLAS_GRANT_ID>",
"conf_settings": {
"settings": {
"join_before_host": true,
"waiting_room": false,
"mute_upon_entry": false,
"auto_recording": "none"
}
}
}
}
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createConfiguration() {
try {
const configuration = await nylas.scheduler.configurations.create({
identifier: "<NYLAS_GRANT_ID>",
requestBody: {
participants: [
{
email: "host@example.com",
isOrganizer: true,
availability: {
calendarIds: ["primary"],
},
booking: {
calendarId: "primary",
},
},
],
availability: {
durationMinutes: 30,
},
eventBooking: {
title: "30-minute meeting",
},
},
});
console.log("Configuration:", configuration);
} catch (error) {
console.error("Error creating configuration:", error);
}
}
createConfiguration();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
configuration = nylas.scheduler.configurations.create(
identifier="<NYLAS_GRANT_ID>",
request_body={
"participants": [
{
"name": "<HOST_NAME>",
"email": "<HOST_EMAIL>",
"is_organizer": True,
"availability": {
"calendar_ids": ["<CALENDAR_ID>"],
},
"booking": {
"calendar_id": "<CALENDAR_ID>",
},
}
],
"availability": {
"duration_minutes": 30,
},
"event_booking": {
"title": "30-minute meeting",
},
},
)
print("Configuration:", configuration)
- lang: ruby
label: Ruby SDK
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
"requires_session_auth": false,
"participants": [
{
"name": "Test",
"email": "nylas_test_8@nylas.com",
"is_organizer": true,
"availability": {
"calendar_ids": [
"primary"
]
},
"booking": {
"calendar_id": "primary"
}
}
],
"availability": {
"duration_minutes": 30
},
"event_booking": {
"title": "My test event",
"hide_participants": false
}
}
# Create a configuration
configuration, _request_ids = nylas.scheduler.configurations.create(identifier: "<NYLAS_GRANT_ID>", request_body: request_body)
puts configuration
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Configuration;
import com.nylas.models.ConfigurationAvailability;
import com.nylas.models.ConfigurationAvailabilityParticipant;
import com.nylas.models.ConfigurationBookingParticipant;
import com.nylas.models.ConfigurationEventBooking;
import com.nylas.models.ConfigurationParticipant;
import com.nylas.models.CreateConfigurationRequest;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
import java.util.Collections;
import java.util.List;
public class CreateConfiguration {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ConfigurationParticipant participant = new ConfigurationParticipant.Builder("host@example.com")
.isOrganizer(true)
.availability(new ConfigurationAvailabilityParticipant.Builder()
.calendarIds(Collections.singletonList("primary"))
.build())
.booking(new ConfigurationBookingParticipant.Builder()
.calendarId("primary")
.build())
.build();
ConfigurationAvailability availability = new ConfigurationAvailability.Builder()
.durationMinutes(30)
.build();
ConfigurationEventBooking eventBooking = new ConfigurationEventBooking.Builder()
.title("30-minute meeting")
.build();
CreateConfigurationRequest requestBody = new CreateConfigurationRequest.Builder(
Collections.singletonList(participant), availability, eventBooking)
.build();
Response<Configuration> configuration = nylas.scheduler().configurations()
.create("<NYLAS_GRANT_ID>", requestBody);
System.out.println("Configuration: " + configuration.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.ConfigurationAvailability
import com.nylas.models.ConfigurationAvailabilityParticipant
import com.nylas.models.ConfigurationBookingParticipant
import com.nylas.models.ConfigurationEventBooking
import com.nylas.models.ConfigurationParticipant
import com.nylas.models.CreateConfigurationRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val participant = ConfigurationParticipant.Builder("host@example.com")
.isOrganizer(true)
.availability(ConfigurationAvailabilityParticipant.Builder()
.calendarIds(listOf("primary"))
.build())
.booking(ConfigurationBookingParticipant.Builder()
.calendarId("primary")
.build())
.build()
val availability = ConfigurationAvailability.Builder()
.durationMinutes(30)
.build()
val eventBooking = ConfigurationEventBooking.Builder()
.title("30-minute meeting")
.build()
val requestBody = CreateConfigurationRequest.Builder(
listOf(participant), availability, eventBooking)
.build()
val configuration = nylas.scheduler().configurations()
.create("<NYLAS_GRANT_ID>", requestBody)
println("Configuration: ${configuration.data}")
}
responses:
'200':
$ref: '#/components/responses/configuration'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
get:
summary: Return all Configuration objects
tags:
- Configurations
operationId: get-configurations
description: Returns all Configuration objects.
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function listConfigurations() {
try {
const configurations = await nylas.scheduler.configurations.list({
identifier: "<NYLAS_GRANT_ID>",
});
console.log("Configurations:", configurations);
} catch (error) {
console.error("Error listing configurations:", error);
}
}
listConfigurations();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
configurations = nylas.scheduler.configurations.list(
identifier="<NYLAS_GRANT_ID>",
query_params={
"limit": 50,
},
)
print("Configurations:", configurations)
- lang: ruby
label: Ruby SDK
source: "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\n# Get a list of configurations\nconfigurations, _request_ids = nylas.scheduler.configurations.list(identifier: \"<NYLAS_GRANT_ID>\")\n\n# Loop the configurations\n\nconfigurations.each {|configuration|\n\tputs(\"ID: #{configuration[:id]} | Slug: #{configuration[:slug]}\")\n}"
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Configuration;
import com.nylas.models.ListResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class ListConfigurations {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ListResponse<Configuration> configurations = nylas.scheduler().configurations()
.list("<NYLAS_GRANT_ID>");
System.out.println("Configurations: " + configurations.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val configurations = nylas.scheduler().configurations().list("<NYLAS_GRANT_ID>")
println("Configurations: ${configurations.data}")
}
responses:
'200':
$ref: '#/components/responses/configurations'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
/v3/grants/{grant_id}/scheduling/configurations/{configuration_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use
`/me/` to refer to the grant associated with an access token.
example: nyla@example.com
- schema:
type: string
name: configuration_id
in: path
required: true
description: The ID of the Configuration object to access.
get:
summary: Return a Configuration
tags:
- Configurations
operationId: get-configurations-id
description: Returns the specified Configuration object.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function findConfiguration() {
try {
const configuration = await nylas.scheduler.configurations.find({
identifier: "<NYLAS_GRANT_ID>",
configurationId: "<CONFIGURATION_ID>",
});
console.log("Configuration:", configuration);
} catch (error) {
console.error("Error finding configuration:", error);
}
}
findConfiguration();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
configuration = nylas.scheduler.configurations.find(
identifier="<NYLAS_GRANT_ID>",
config_id="<SCHEDULER_CONFIG_ID>",
)
print("Configuration:", configuration)
- lang: ruby
label: Ruby SDK
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
configuration, _request_ids = nylas.scheduler.configurations.find(identifier: "<NYLAS_GRANT_ID>", configuration_id: "<SCHEDULER_CONFIG_ID>")
puts configuration
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Configuration;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class FindConfiguration {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
Response<Configuration> configuration = nylas.scheduler().configurations()
.find("<NYLAS_GRANT_ID>", "<CONFIGURATION_ID>");
System.out.println("Configuration: " + configuration.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val configuration = nylas.scheduler().configurations()
.find("<NYLAS_GRANT_ID>", "<CONFIGURATION_ID>")
println("Configuration: ${configuration.data}")
}
responses:
'200':
$ref: '#/components/responses/configuration'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
put:
summary: Update Configuration
tags:
- Configurations
operationId: put-configurations-id
description: |-
Updates the specified Configuration object.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.readonly
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
security:
- NYLAS_API_KEY: []
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/configuration'
title: Standard Configuration
- $ref: '#/components/schemas/group-configuration'
title: Group Configuration
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"event_booking": {
"title": "Testing Scheduler",
"hide_participants": false,
"conferencing": {
"provider": "Zoom Meeting",
"autocreate": {
"conf_grant_id": "<NYLAS_GRANT_ID>",
"conf_settings": {
"settings": {
"join_before_host": true,
"waiting_room": false,
"mute_upon_entry": false,
"auto_recording": "none"
}
}
}
}
}
"scheduler": {
"rescheduling_url": "https://www.example.com/reschdule/:booking_ref",
"cancellation_url": "https://www.example.com/cancel/:booking_ref"
}
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function updateConfiguration() {
try {
const configuration = await nylas.scheduler.configurations.update({
identifier: "<NYLAS_GRANT_ID>",
configurationId: "<CONFIGURATION_ID>",
requestBody: {
availability: {
durationMinutes: 45,
},
},
});
console.log("Updated configuration:", configuration);
} catch (error) {
console.error("Error updating configuration:", error);
}
}
updateConfiguration();
- lang: ruby
label: Ruby SDK
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
"availability": {
"duration_minutes": 60
}
}
configuration, _request_ids = nylas.scheduler.configurations.update(identifier: "<NYLAS_GRANT_ID>", configuration_id: "<SCHEDULER_CONFIG_ID>", request_body: request_body)
puts configuration
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.Configuration;
import com.nylas.models.ConfigurationAvailability;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
import com.nylas.models.UpdateConfigurationRequest;
public class UpdateConfiguration {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ConfigurationAvailability availability = new ConfigurationAvailability.Builder()
.durationMinutes(45)
.build();
UpdateConfigurationRequest requestBody = new UpdateConfigurationRequest.Builder()
.availability(availability)
.build();
Response<Configuration> configuration = nylas.scheduler().configurations()
.update("<NYLAS_GRANT_ID>", "<CONFIGURATION_ID>", requestBody);
System.out.println("Updated configuration: " + configuration.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.ConfigurationAvailability
import com.nylas.models.UpdateConfigurationRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val availability = ConfigurationAvailability.Builder()
.durationMinutes(45)
.build()
val requestBody = UpdateConfigurationRequest.Builder()
.availability(availability)
.build()
val configuration = nylas.scheduler().configurations()
.update("<NYLAS_GRANT_ID>", "<CONFIGURATION_ID>", requestBody)
println("Updated configuration: ${configuration.data}")
}
responses:
'200':
$ref: '#/components/responses/configuration'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
delete:
summary: Delete a Configuration
tags:
- Configurations
operationId: delete-configurations-id
description: |-
Deletes the specified Configuration object. You can't delete a Configuration that has active
sessions.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deleteConfiguration() {
try {
const result = await nylas.scheduler.configurations.destroy({
identifier: "<NYLAS_GRANT_ID>",
configurationId: "<CONFIGURATION_ID>",
});
console.log("Deleted configuration:", result);
} catch (error) {
console.error("Error deleting configuration:", error);
}
}
deleteConfiguration();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.scheduler.configurations.destroy(
identifier="<NYLAS_GRANT_ID>",
config_id="<SCHEDULER_CONFIG_ID>",
)
print("Configuration deleted:", response)
- lang: ruby
label: Ruby SDK
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
_, request_ids = nylas.scheduler.configurations.destroy(identifier: "<NYLAS_GRANT_ID>", configuration_id: "<SCHEDULER_CONFIG_ID>")
puts request_ids
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.DeleteResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class DeleteConfiguration {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse result = nylas.scheduler().configurations()
.destroy("<NYLAS_GRANT_ID>", "<CONFIGURATION_ID>", null);
System.out.println("Deleted configuration: " + result);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val result = nylas.scheduler().configurations()
.destroy("<NYLAS_GRANT_ID>", "<CONFIGURATION_ID>")
println("Deleted configuration: $result")
}
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
/v3/grants/{grant_id}/scheduling/configurations/{configuration_id}/group-events:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: The ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: configuration_id
in: path
required: true
description: The ID of the Configuration object to access.
get:
summary: Get all group events
tags:
- Group Events
operationId: get-group-events
description: Returns all group events within the given time range, from the specified Configuration.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>/group-events"?calendar_id=<CALENDAR_ID>&start_time=<TIMESTAMP>&end_time=<TIMESTAMP>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/group_events'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/calendar_id'
- $ref: '#/components/parameters/start_time'
- $ref: '#/components/parameters/end_time'
post:
summary: Create group event
tags:
- Group Events
operationId: create-group-event
description: Creates a group event in the specified Configuration.
requestBody:
$ref: '#/components/requestBodies/group_event_create'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>/group-events" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"title": "Annual Philosophy Club Meeting",
"busy": true,
"participants": [
{
"name": "Leyah Miller",
"email": "leyah@example.com",
"is_organizer": true
},
{
"name": "Nyla",
"email": "nyla@example.com",
"is_organizer": false
}
],
"description": "Come ready to talk philosophy!",
"when": {
"start_time": 1674604800,
"end_time": 1722382420,
"start_timezone": "America/New_York",
"end_timezone": "America/New_York"
},
"location": "New York Public Library, Cave room",
"recurrence": [
"RRULE:FREQ=WEEKLY;BYDAY=MO",
"EXDATE:20211011T000000Z"
],
"capacity": 100
}'
responses:
'200':
$ref: '#/components/responses/group_event'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
/v3/grants/{grant_id}/scheduling/configurations/{configuration_id}/group-events/{event_id}:
parameters:
- schema:
type: string
name: grant_id
in: path
required: true
description: The ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
- schema:
type: string
name: configuration_id
in: path
required: true
description: The ID of the Configuration object to access.
- schema:
type: string
name: event_id
in: path
required: true
description: The ID of the group event to access.
put:
summary: Update a group event
tags:
- Group Events
operationId: put-group-event
description: |-
Updates the specified group event.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
requestBody:
$ref: '#/components/requestBodies/group_event_update'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request PUT \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>/group-events/<EVENT_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"scheduler": {
"rescheduling_url": "<RESCHEDULING_PAGE_URL>",
"cancellation_url": "<CANCELLATION_PAGE_URL>"
}
}'
responses:
'200':
$ref: '#/components/responses/group_event'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
delete:
summary: Delete a group event
tags:
- Group Events
operationId: delete-group-event
description: Deletes the specified group event.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>/group-events/<EVENT_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
responses:
'200':
$ref: '#/components/responses/200-delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- NYLAS_API_KEY: []
/v3/scheduling/configurations/{configuration_id}/import-group-events:
parameters:
- schema:
type: string
name: configuration_id
in: path
required: true
description: The ID of the Configuration object to access.
post:
summary: Import group events
tags:
- Group Events
operationId: import-group-events
description: |-
Imports existing events to your group events Configuration. You can import up to 20 events per
request.
requestBody:
$ref: '#/components/requestBodies/import_group_event'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url "https://api.us.nylas.com/v3/scheduling/configurations/<SCHEDULER_CONFIG_ID>/import-group-events" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"calendar_id": "<CALENDAR_ID>",
"event_id": "<EVENT_ID>",
"capacity": 10,
"exceptions": [{
"event_id": "<EVENT_ID>",
"capacity": 5
}],
"participants": [{
"name": "Leyah Miller",
"email": "leyah@example.com"
}]
}'
responses:
'200':
$ref: '#/components/responses/import-group-event'
security:
- NYLAS_API_KEY: []
/v3/scheduling/configurations/{configuration_id}/group-events/validate-timeslot:
parameters:
- schema:
type: string
name: configuration_id
in: path
required: true
description: The ID of the Configuration object to access.
post:
summary: Validate time slot
tags:
- Group Events
operationId: validate-time-slot
description: |-
Validates whether the selected group event or time slot has changed, and is invalid. This can happen
because...
- The group event was deleted.
- The group event was updated (for example, the start time was changed).
- The `capacity` for the event was changed.
requestBody:
$ref: '#/components/requestBodies/validate_timeslot'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url "https://api.us.nylas.com/v3/scheduling/configurations/<SCHEDULER_CONFIG_ID>/group-events/validate-timeslot" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"calendar_id": "<CALENDAR_ID>",
"event_id": "<EVENT_ID>",
"capacity": 10,
"end_time": 1738156200,
"start_time": 1738155600,
"emails": [
"email": "leyah@example.com"
]
}'
responses:
'200':
$ref: '#/components/responses/validate-timeslot'
security:
- NYLAS_API_KEY: []
/v3/scheduling/sessions:
post:
summary: Create a session
tags:
- Sessions
operationId: post-sessions
description: |-
Creates a new short-lived session that you can pass to the Scheduling Component to enforce user
authentication. Your request must include the ID of an existing Configuration object.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request POST \
--url "https://api.us.nylas.com/v3/scheduling/sessions" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"configuration_id": "<SCHEDULER_CONFIGURATION_ID>",
"time_to_live": 10
}'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createSession() {
try {
const session = await nylas.scheduler.sessions.create({
requestBody: {
configurationId: "<CONFIGURATION_ID>",
timeToLive: 30,
},
});
console.log("Session:", session);
} catch (error) {
console.error("Error creating session:", error);
}
}
createSession();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
session = nylas.scheduler.sessions.create(
request_body={
"configuration_id": "<SCHEDULER_CONFIG_ID>",
"time_to_live": 30,
},
)
print("Created session:", session)
- lang: ruby
label: Ruby SDK
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
"configuration_id": "<SCHEDULER_CONFIG_ID>",
"time_to_live": 30
}
session, _request_ids = nylas.scheduler.sessions.create(request_body: request_body)
puts session
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.CreateSessionRequest;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
import com.nylas.models.Session;
public class CreateSession {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
CreateSessionRequest requestBody = new CreateSessionRequest.Builder()
.configurationId("<CONFIGURATION_ID>")
.timeToLive(30)
.build();
Response<Session> session = nylas.scheduler().sessions().create(requestBody);
System.out.println("Session: " + session.getData());
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
import com.nylas.models.CreateSessionRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val requestBody = CreateSessionRequest.Builder()
.configurationId("<CONFIGURATION_ID>")
.timeToLive(30)
.build()
val session = nylas.scheduler().sessions().create(requestBody)
println("Session: ${session.data}")
}
security:
- NYLAS_API_KEY: []
parameters: []
requestBody:
$ref: '#/components/requestBodies/session_create'
responses:
'200':
$ref: '#/components/responses/session_create'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/scheduling/sessions/{session_id}:
parameters:
- schema:
type: string
name: session_id
in: path
required: true
description: The ID of the session to modify.
delete:
summary: Delete a session
tags:
- Sessions
operationId: delete-session
description: Deletes a specific session.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request DELETE \
--url "https://api.us.nylas.com/v3/scheduling/sessions/<SCHEDULER_SESSION_ID>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function deleteSession() {
try {
const result = await nylas.scheduler.sessions.destroy({
sessionId: "<SESSION_ID>",
});
console.log("Deleted session:", result);
} catch (error) {
console.error("Error deleting session:", error);
}
}
deleteSession();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.scheduler.sessions.destroy(
session_id="<SESSION_ID>",
)
print("Session deleted:", response)
- lang: ruby
label: Ruby SDK
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
_, request_ids = nylas.scheduler.sessions.destroy(session_id: "<SCHEDULER_SESSION_ID>")
- lang: java
label: Java SDK
source: |
import com.nylas.NylasClient;
import com.nylas.models.DeleteResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class DeleteSession {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DeleteResponse result = nylas.scheduler().sessions().destroy("<SESSION_ID>");
System.out.println("Deleted session: " + result);
}
}
- lang: kotlin
label: Kotlin SDK
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val result = nylas.scheduler().sessions().destroy("<SESSION_ID>")
println("Deleted session: $result")
}
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/session_delete'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
/v3/scheduling/availability:
parameters:
- schema:
type: string
name: start_time
in: query
required: true
description: The time from which to check availability, in seconds using the Unix timestamp format.
- schema:
type: string
name: end_time
in: query
required: true
description: The time until which to check availability, in seconds using the Unix timestamp format.
- schema:
type: string
name: configuration_id
in: query
required: false
description: |-
The ID of the Configuration object used for calculating availability. If you're using session
authentication (`requires_session_auth: true`), the `configuration_id` isn't required.
- schema:
type: string
name: slug
in: query
required: false
description: |-
The Configuration object slug. You can use this with the `client_id` instead of using the
`configuration_id`. If you're using session authentication (`requires_session_auth: true`) or
using the `configuration_id`, `slug` isn't required.
- schema:
type: string
name: client_id
in: query
required: false
description: |-
The client ID that was used to create the Configuration object. Required only if you're using
`slug`.
- schema:
type: string
name: booking_id
in: query
required: false
description: |-
The ID of the booking to reschedule, if you're checking availability to reschedule a round-robin
booking. Required only if `availability_method` is `max-fairness` or `max-availability`. See
[Retrieve booking IDs](/docs/v3/scheduler/retrieve-booking-ids/) for more information.
get:
summary: Get availability
tags:
- Availability
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.readonly
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.Read
others: https://graph.microsoft.com/Calendars.ReadWrite
operationId: get-availability
description: |-
Gets available time slots within the given time range, using the rules defined in the specified
Configuration object. If the Configuration `type` is `group`, Nylas returns only valid group events
within the time range, including recurring events.
Nylas validates the provided session ID and uses it to retrieve the related
[Configuration object](/docs/reference/api/configurations/). If you created a public
Configuration, you don't need to include the `Authorization` request header with a session ID, but
you do need to pass the Configuration object ID as a query parameter.
x-code-samples:
- lang: bash
label: cURL (Public)
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/scheduling/availability?start_time=1709643600&end_time=1709665200&configuration_id=<SCHEDULER_CONFIG_ID>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
- lang: bash
label: cURL (Private)
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/scheduling/availability?start_time=1709643600&end_time=1709665200' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function getAvailability() {
try {
const availability = await nylas.scheduler.availability.get({
queryParams: {
configurationId: "<CONFIGURATION_ID>",
startTime: 1748908800,
endTime: 1748995200,
},
});
console.log("Availability:", availability);
} catch (error) {
console.error("Error getting availability:", error);
}
}
getAvailability();
responses:
'200':
$ref: '#/components/responses/availability'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- SCHEDULER_SESSION_TOKEN: []
/v3/scheduling/bookings:
parameters:
- schema:
type: string
name: timezone
in: query
required: false
description: The timezone to use for the booking. If not provided, Nylas uses the timezone from the Configuration object.
- schema:
type: string
name: configuration_id
in: query
required: false
description: The ID of the Configuration object whose settings are used for calculating availability. If you're using session authentication (`requires_session_auth` is set to `true`), `configuration_id` is not required.
- schema:
type: string
name: slug
in: query
required: false
description: The slug of the Configuration object. You can use this with the `client_id` instead of using the `configuration_id`. If you're using session authentication (`requires_session_auth` is set to `true`) or using the `configuration_id`, `slug` is not required.
- schema:
type: string
name: client_id
in: query
required: false
description: The client ID that was used to create the Configuration object. `client_id` is required only if you're using `slug`.
post:
summary: Book an event
tags:
- Bookings
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
requestBody:
$ref: '#/components/requestBodies/booking_create'
responses:
'200':
$ref: '#/components/responses/booking_create'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
operationId: post-bookings
description: |-
Books an event with the participants listed in the session's
[Configuration object](/docs/reference/api/configurations/), using the details from the
Configuration. The `start_time` and `end_time` must correspond to a valid time slot returned by
the
[Scheduling Availability endpoint](/docs/reference/api/availability/get-availability/)
using the same Configuration.
Nylas validates the session ID and uses it to retrieve the related Configuration object. If you
created a public Configuration, you don't need to include the `Authorization` request header with
a session ID, but you do need to pass the Configuration object ID as a query parameter.
x-code-samples:
- lang: bash
label: cURL (Public)
source: |-
curl --compressed --request POST \
--url 'https://api.us.nylas.com/v3/scheduling/bookings?configuration_id=<SCHEDULER_CONFIG_ID>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"start_time": 1709643600,
"end_time": 1709645400,
"participants": [],
"guest": {
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
}'
- lang: bash
label: cURL (Private)
source: |-
curl --compressed --request POST \
--url 'https://api.us.nylas.com/v3/scheduling/bookings' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
--header 'Content-Type: application/json' \
--data '{
"start_time": 1709643600,
"end_time": 1709645400,
"participants": [],
"guest": {
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
}'
- lang: javascript
label: Node.js SDK (Public)
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createBooking() {
try {
const booking = await nylas.scheduler.bookings.create({
queryParams: {
configurationId: "<SCHEDULER_CONFIG_ID>",
},
requestBody: {
startTime: 1763119800,
endTime: 1763121600,
guest: {
name: "Jane Doe",
email: "jane.doe@example.com",
},
},
});
console.log("Created Booking", booking);
} catch (error) {
console.error("Error creating booking", error);
}
}
createBooking();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
booking = nylas.scheduler.bookings.create(
request_body={
"start_time": 1763119800,
"end_time": 1763121600,
"guest": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
},
},
query_params={
"configuration_id": "<SCHEDULER_CONFIG_ID>",
},
)
print("Created booking:", booking)
- lang: javascript
label: Node.js SDK (Private)
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function createBooking() {
try {
const booking = await nylas.scheduler.bookings.create({
requestBody: {
startTime: 1763119800,
endTime: 1763121600,
guest: {
name: "Jane Doe",
email: "jane.doe@example.com",
},
},
});
console.log("Created Booking", booking);
} catch (error) {
console.error("Error creating booking", error);
}
}
createBooking();
- lang: ruby
label: Ruby SDK (Public)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
"start_time": 1709643600,
"end_time": 1709645400,
"participants": [],
"guest": {
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
}
booking, _request_ids = nylas.scheduler.bookings.create(request_body: request_body, query_params: { configuration_id: "<SCHEDULER_CONFIG_ID>" })
puts booking
- lang: ruby
label: Ruby SDK (Private)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<SCHEDULER_SESSION_ID>"
)
request_body = {
"start_time": 1709643600,
"end_time": 1709645400,
"participants": [],
"guest": {
"name": "Jane Doe",
"email": "jane.doe@example.com"
}
}
booking, _request_ids = nylas.scheduler.bookings.create(request_body: request_body)
puts booking
- lang: java
label: Java SDK (Public)
source: |
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.BookingGuest;
import com.nylas.models.CreateBookingQueryParams;
import com.nylas.models.CreateBookingRequest;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class CreateBookingPublic {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
BookingGuest guest = new BookingGuest("jane.doe@example.com", "Jane Doe");
CreateBookingRequest requestBody = new CreateBookingRequest.Builder()
.startTime("1763119800")
.endTime("1763121600")
.guest(guest)
.build();
// Public Configuration objects need the configuration ID as a query parameter.
CreateBookingQueryParams queryParams = new CreateBookingQueryParams.Builder()
.configurationId("<SCHEDULER_CONFIG_ID>")
.build();
Response<Booking> booking = nylas.scheduler().bookings().create(requestBody, queryParams);
System.out.println("Created booking: " + booking.getData());
}
}
- lang: java
label: Java SDK (Private)
source: |
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.BookingGuest;
import com.nylas.models.CreateBookingRequest;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class CreateBooking {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
// Use a Scheduler session ID as the API key for session-authenticated bookings.
NylasClient nylas = new NylasClient.Builder("<SCHEDULER_SESSION_ID>").build();
BookingGuest guest = new BookingGuest("jane.doe@example.com", "Jane Doe");
CreateBookingRequest requestBody = new CreateBookingRequest.Builder()
.startTime("1763119800")
.endTime("1763121600")
.guest(guest)
.build();
Response<Booking> booking = nylas.scheduler().bookings().create(requestBody);
System.out.println("Created booking: " + booking.getData());
}
}
- lang: kotlin
label: Kotlin SDK (Public)
source: |
import com.nylas.NylasClient
import com.nylas.models.BookingGuest
import com.nylas.models.CreateBookingQueryParams
import com.nylas.models.CreateBookingRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val guest = BookingGuest(email = "jane.doe@example.com", name = "Jane Doe")
val requestBody = CreateBookingRequest.Builder()
.startTime("1763119800")
.endTime("1763121600")
.guest(guest)
.build()
// Public Configuration objects need the configuration ID as a query parameter.
val queryParams = CreateBookingQueryParams.Builder()
.configurationId("<SCHEDULER_CONFIG_ID>")
.build()
val booking = nylas.scheduler().bookings().create(requestBody, queryParams)
println("Created booking: ${booking.data}")
}
- lang: kotlin
label: Kotlin SDK (Private)
source: |
import com.nylas.NylasClient
import com.nylas.models.BookingGuest
import com.nylas.models.CreateBookingRequest
fun main() {
// Use a Scheduler session ID as the API key for session-authenticated bookings.
val nylas = NylasClient.Builder("<SCHEDULER_SESSION_ID>").build()
val guest = BookingGuest(email = "jane.doe@example.com", name = "Jane Doe")
val requestBody = CreateBookingRequest.Builder()
.startTime("1763119800")
.endTime("1763121600")
.guest(guest)
.build()
val booking = nylas.scheduler().bookings().create(requestBody)
println("Created booking: ${booking.data}")
}
security:
- SCHEDULER_SESSION_TOKEN: []
/v3/scheduling/bookings/{booking_id}:
parameters:
- schema:
type: string
name: booking_id
in: path
required: true
description: The ID of the booking object to access.
- schema:
type: string
name: configuration_id
in: query
required: false
description: |-
The ID of the Configuration object used for calculating availability. If you're using session
authentication (`requires_session_auth: true`), the `configuration_id` isn't required.
- schema:
type: string
name: slug
in: query
required: false
description: |-
The Configuration object slug. You can use this with the `client_id` instead of using the
`configuration_id`. If you're using session authentication (`requires_session_auth: true`) or
using the `configuration_id`, `slug` isn't required.
- schema:
type: string
name: client_id
in: query
required: false
description: |-
The client ID that was used to create the Configuration object. Required only if you're using
`slug`.
get:
summary: Return a booking
tags:
- Bookings
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
operationId: get-bookings-id
description: |-
Returns the specified Booking object.
Nylas validates the provided session ID and uses it to retrieve the related
[Configuration object](/docs/reference/api/configurations/). If you created a public
Configuration, you don't need to include the `Authorization` request header with a session ID, but
you do need to pass the Configuration object ID as a query parameter.
x-code-samples:
- lang: bash
label: cURL (Public)
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
- lang: bash
label: cURL (Private)
source: |-
curl --compressed --request GET \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
--header 'Content-Type: application/json'
- lang: javascript
label: Node.js SDK (Public)
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchBookingById() {
try {
const booking = await nylas.scheduler.bookings.find({
queryParams: {
configurationId: "<SCHEDULER_CONFIG_ID>",
},
bookingId: "<BOOKING_ID>",
});
console.log("Booking", booking);
} catch (error) {
console.error("Error fetching booking", error);
}
}
fetchBookingById();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
booking = nylas.scheduler.bookings.find(
booking_id="<BOOKING_ID>",
query_params={
"configuration_id": "<SCHEDULER_CONFIG_ID>",
},
)
print("Booking:", booking)
- lang: javascript
label: Node.js SDK (Private)
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<SCHEDULER_SESSION_ID>",
apiUri: "<NYLAS_API_URI>",
});
async function fetchBookingById() {
try {
const booking = await nylas.scheduler.bookings.find({
bookingId: "<BOOKING_ID>",
});
console.log("Booking", booking);
} catch (error) {
console.error("Error fetching booking", error);
}
}
fetchBookingById();
- lang: ruby
label: Ruby SDK (Public)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
booking, _request_ids = nylas.scheduler.bookings.find(booking_id: "<SCHEDULER_BOOKING_ID>", query_params: { configuration_id: "<SCHEDULER_CONFIG_ID>" })
puts booking
- lang: ruby
label: Ruby SDK (Private)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<SCHEDULER_SESSION_ID>"
)
booking, _request_ids = nylas.scheduler.bookings.find(booking_id: "<SCHEDULER_BOOKING_ID>")
puts booking
- lang: java
label: Java SDK (Public)
source: |
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.FindBookingQueryParams;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class FindBookingPublic {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
FindBookingQueryParams queryParams = new FindBookingQueryParams.Builder()
.configurationId("<SCHEDULER_CONFIG_ID>")
.build();
Response<Booking> booking = nylas.scheduler().bookings().find("<BOOKING_ID>", queryParams);
System.out.println("Booking: " + booking.getData());
}
}
- lang: java
label: Java SDK (Private)
source: |
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class FindBooking {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<SCHEDULER_SESSION_ID>").build();
Response<Booking> booking = nylas.scheduler().bookings().find("<BOOKING_ID>");
System.out.println("Booking: " + booking.getData());
}
}
- lang: kotlin
label: Kotlin SDK (Public)
source: |
import com.nylas.NylasClient
import com.nylas.models.FindBookingQueryParams
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val queryParams = FindBookingQueryParams.Builder()
.configurationId("<SCHEDULER_CONFIG_ID>")
.build()
val booking = nylas.scheduler().bookings().find("<BOOKING_ID>", queryParams)
println("Booking: ${booking.data}")
}
- lang: kotlin
label: Kotlin SDK (Private)
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<SCHEDULER_SESSION_ID>").build()
val booking = nylas.scheduler().bookings().find("<BOOKING_ID>")
println("Booking: ${booking.data}")
}
responses:
'200':
$ref: '#/components/responses/booking_create'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- SCHEDULER_SESSION_TOKEN: []
patch:
summary: Reschedule a booking
tags:
- Bookings
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
operationId: patch-bookings-id
description: |-
Reschedules the specified booking. Nylas also updates the associated event on the provider.
Nylas recommends against changing participants' email addresses while updating a booking, to avoid
confusion.
Nylas validates the provided session ID and uses it to retrieve the related
[Configuration object](/docs/reference/api/configurations/). If you created a public
Configuration, you don't need to include the `Authorization` request header with a session ID, but
you do need to pass the Configuration object ID as a query parameter.
When you make a `PATCH` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/booking_update'
title: Reschedule standard booking
- $ref: '#/components/schemas/booking_update_group'
title: Reschedule group booking
x-code-samples:
- lang: bash
label: cURL (Public)
source: |-
curl --compressed --request PATCH \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"start_time": 1708714800,
"end_time": 1708722000
}'
- lang: bash
label: cURL (Private)
source: |-
curl --compressed --request PATCH \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
--header 'Content-Type: application/json' \
--data '{
"start_time": 1708714800,
"end_time": 1708722000
}'
- lang: javascript
label: Node.js SDK (Public)
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function rescheduleBooking() {
try {
const booking = await nylas.scheduler.bookings.reschedule({
queryParams: {
configurationId: "<SCHEDULER_CONFIG_ID>",
},
bookingId: "booking-id",
requestBody: {
startTime: 1763292600,
endTime: 1763294400,
},
});
console.log("Rescheduled Booking", booking);
} catch (error) {
console.error("Error rescheduling booking", error);
}
}
rescheduleBooking();
- lang: python
label: Python SDK
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
booking = nylas.scheduler.bookings.confirm(
booking_id="<BOOKING_ID>",
request_body={
"salt": "<SALT>",
"status": "confirmed",
},
query_params={
"configuration_id": "<SCHEDULER_CONFIG_ID>",
},
)
print("Confirmed booking:", booking)
- lang: javascript
label: Node.js SDK (Private)
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<SCHEDULER_SESSION_ID>",
apiUri: "<NYLAS_API_URI>",
});
async function rescheduleBooking() {
try {
const booking = await nylas.scheduler.bookings.reschedule({
bookingId: "booking-id",
requestBody: {
startTime: 1763292600,
endTime: 1763294400,
},
});
console.log("Rescheduled Booking", booking);
} catch (error) {
console.error("Error rescheduling booking", error);
}
}
rescheduleBooking();
- lang: ruby
label: Ruby SDK (Public)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
"start_time": 1794828600,
"end_time": 1794830400,
}
booking, _request_ids = nylas.scheduler.bookings.update(booking_id: "<BOOKING_ID>", request_body: request_body, query_params: {"configuration_id": "<CONFIGURATION_ID>"})
puts booking
- lang: ruby
label: Ruby SDK (Private)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<SCHEDULER_SESSION_ID>"
)
request_body = {
"start_time": 1794828600,
"end_time": 1794830400,
}
booking, _request_ids = nylas.scheduler.bookings.update(booking_id: "<BOOKING_ID>", request_body: request_body)
puts booking
- lang: java
label: Java SDK (Public)
source: |
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.RescheduleBookingQueryParams;
import com.nylas.models.RescheduleBookingRequest;
import com.nylas.models.Response;
public class RescheduleBookingPublic {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
RescheduleBookingRequest requestBody = new RescheduleBookingRequest.Builder()
.startTime(1763292600)
.endTime(1763294400)
.build();
RescheduleBookingQueryParams queryParams = new RescheduleBookingQueryParams(
"<SCHEDULER_CONFIG_ID>", "<SCHEDULER_CONFIG_SLUG>", "<NYLAS_CLIENT_ID>");
Response<Booking> booking = nylas.scheduler().bookings().reschedule(
"<BOOKING_ID>", requestBody, queryParams);
System.out.println("Rescheduled booking: " + booking.getData());
}
}
- lang: java
label: Java SDK (Private)
source: |
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.RescheduleBookingRequest;
import com.nylas.models.Response;
public class RescheduleBooking {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<SCHEDULER_SESSION_ID>").build();
RescheduleBookingRequest requestBody = new RescheduleBookingRequest.Builder()
.startTime(1763292600)
.endTime(1763294400)
.build();
Response<Booking> booking = nylas.scheduler().bookings().reschedule("<BOOKING_ID>", requestBody);
System.out.println("Rescheduled booking: " + booking.getData());
}
}
- lang: kotlin
label: Kotlin SDK (Public)
source: |
import com.nylas.NylasClient
import com.nylas.models.RescheduleBookingQueryParams
import com.nylas.models.RescheduleBookingRequest
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val requestBody = RescheduleBookingRequest.Builder()
.startTime(1763292600)
.endTime(1763294400)
.build()
val queryParams = RescheduleBookingQueryParams(
configurationId = "<SCHEDULER_CONFIG_ID>",
slug = "<SCHEDULER_CONFIG_SLUG>",
clientId = "<NYLAS_CLIENT_ID>")
val booking = nylas.scheduler().bookings().reschedule("<BOOKING_ID>", requestBody, queryParams)
println("Rescheduled booking: ${booking.data}")
}
- lang: kotlin
label: Kotlin SDK (Private)
source: |
import com.nylas.NylasClient
import com.nylas.models.RescheduleBookingRequest
fun main() {
val nylas = NylasClient.Builder("<SCHEDULER_SESSION_ID>").build()
val requestBody = RescheduleBookingRequest.Builder()
.startTime(1763292600)
.endTime(1763294400)
.build()
val booking = nylas.scheduler().bookings().reschedule("<BOOKING_ID>", requestBody)
println("Rescheduled booking: ${booking.data}")
}
responses:
'200':
$ref: '#/components/responses/200'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- SCHEDULER_SESSION_TOKEN: []
put:
summary: Confirm a booking
tags:
- Bookings
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
operationId: put-bookings-id
description: |-
Confirms or cancels the specified pending booking. Nylas also updates the associated event on the
provider.
Nylas validates the provided session ID and uses it to retrieve the related
[Configuration object](/docs/reference/api/configurations/). If you created a public
Configuration, you don't need to include the `Authorization` request header with a session ID, but
you do need to pass the Configuration object ID as a query parameter.
When you make a `PUT` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).
requestBody:
$ref: '#/components/requestBodies/booking_confirm'
x-code-samples:
- lang: bash
label: cURL (Public)
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"salt": -zgLLAuk_qtcsw,
"status": "cancelled",
"cancellation_reason": "I am no longer available at this time."
}'
- lang: bash
label: cURL (Private)
source: |-
curl --compressed --request PUT \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
--header 'Content-Type: application/json' \
--data '{
"salt": -zgLLAuk_qtcsw,
"status": "cancelled",
"cancellation_reason": "I am no longer available at this time."
}'
- lang: javascript
label: Node.js SDK (Public)
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<NYLAS_API_KEY>",
apiUri: "<NYLAS_API_URI>",
});
async function confirmBooking() {
try {
const booking = await nylas.scheduler.bookings.confirm({
queryParams: {
configurationId: "<SCHEDULER_CONFIG_ID>",
},
bookingId: "booking-id",
requestBody: {
salt: "-zgLLAuk_qtcsw",
status: "cancelled",
cancellationReason: "I am no longer available at this time.",
},
});
console.log("Confirmed Booking", booking);
} catch (error) {
console.error("Error confirming booking", error);
}
}
confirmBooking();
- lang: javascript
label: Node.js SDK (Private)
source: |
import Nylas from "nylas";
const nylas = new Nylas({
apiKey: "<SCHEDULER_SESSION_ID>",
apiUri: "<NYLAS_API_URI>",
});
async function confirmBooking() {
try {
const booking = await nylas.scheduler.bookings.confirm({
bookingId: "booking-id",
requestBody: {
salt: "-zgLLAuk_qtcsw",
status: "cancelled",
cancellationReason: "I am no longer available at this time.",
},
});
console.log("Confirmed Booking", booking);
} catch (error) {
console.error("Error confirming booking", error);
}
}
confirmBooking();
- lang: ruby
label: Ruby SDK (Public)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
request_body = {
"salt": "-zgLLAuk_qtcsw",
"status": "cancelled",
"cancellation_reason": "I am no longer available at this time."
}
booking, _request_ids = nylas.scheduler.bookings.confirm(booking_id: "<BOOKING_ID>", request_body: request_body, query_params: {"configuration_id": "<CONFIGURATION_ID>"})
puts booking
- lang: ruby
label: Ruby SDK (Private)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<SCHEDULER_SESSION_ID>"
)
request_body = {
"salt": "-zgLLAuk_qtcsw",
"status": "cancelled",
"cancellation_reason": "I am no longer available at this time."
}
booking, _request_ids = nylas.scheduler.bookings.confirm(booking_id: "<BOOKING_ID>", request_body: request_body)
puts booking
- lang: java
label: Java SDK (Public)
source: |
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.ConfirmBookingQueryParams;
import com.nylas.models.ConfirmBookingRequest;
import com.nylas.models.ConfirmBookingStatus;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class ConfirmBookingPublic {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
ConfirmBookingRequest requestBody = new ConfirmBookingRequest.Builder()
.salt("-zgLLAuk_qtcsw")
.status(ConfirmBookingStatus.CANCELLED)
.cancellationReason("I am no longer available at this time.")
.build();
ConfirmBookingQueryParams queryParams = new ConfirmBookingQueryParams.Builder()
.configurationId("<SCHEDULER_CONFIG_ID>")
.build();
Response<Booking> booking = nylas.scheduler().bookings().confirm(
"<BOOKING_ID>", requestBody, queryParams);
System.out.println("Confirmed booking: " + booking.getData());
}
}
- lang: java
label: Java SDK (Private)
source: |
import com.nylas.NylasClient;
import com.nylas.models.Booking;
import com.nylas.models.ConfirmBookingRequest;
import com.nylas.models.ConfirmBookingStatus;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
import com.nylas.models.Response;
public class ConfirmBooking {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<SCHEDULER_SESSION_ID>").build();
ConfirmBookingRequest requestBody = new ConfirmBookingRequest.Builder()
.salt("-zgLLAuk_qtcsw")
.status(ConfirmBookingStatus.CANCELLED)
.cancellationReason("I am no longer available at this time.")
.build();
Response<Booking> booking = nylas.scheduler().bookings().confirm("<BOOKING_ID>", requestBody);
System.out.println("Confirmed booking: " + booking.getData());
}
}
- lang: kotlin
label: Kotlin SDK (Public)
source: |
import com.nylas.NylasClient
import com.nylas.models.ConfirmBookingQueryParams
import com.nylas.models.ConfirmBookingRequest
import com.nylas.models.ConfirmBookingStatus
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val requestBody = ConfirmBookingRequest.Builder()
.salt("-zgLLAuk_qtcsw")
.status(ConfirmBookingStatus.CANCELLED)
.cancellationReason("I am no longer available at this time.")
.build()
val queryParams = ConfirmBookingQueryParams.Builder()
.configurationId("<SCHEDULER_CONFIG_ID>")
.build()
val booking = nylas.scheduler().bookings().confirm("<BOOKING_ID>", requestBody, queryParams)
println("Confirmed booking: ${booking.data}")
}
- lang: kotlin
label: Kotlin SDK (Private)
source: |
import com.nylas.NylasClient
import com.nylas.models.ConfirmBookingRequest
import com.nylas.models.ConfirmBookingStatus
fun main() {
val nylas = NylasClient.Builder("<SCHEDULER_SESSION_ID>").build()
val requestBody = ConfirmBookingRequest.Builder()
.salt("-zgLLAuk_qtcsw")
.status(ConfirmBookingStatus.CANCELLED)
.cancellationReason("I am no longer available at this time.")
.build()
val booking = nylas.scheduler().bookings().confirm("<BOOKING_ID>", requestBody)
println("Confirmed booking: ${booking.data}")
}
responses:
'200':
$ref: '#/components/responses/booking_confirm'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- SCHEDULER_SESSION_TOKEN: []
delete:
summary: Delete a booking
tags:
- Bookings
x-scopes:
google:
min: https://www.googleapis.com/auth/calendar.events
others: https://www.googleapis.com/auth/calendar
microsoft:
min: https://graph.microsoft.com/Calendars.ReadWrite
others: ''
operationId: delete-bookings-id
description: |-
Deletes the specified booking. Nylas also cancels the associated event on the provider.
Nylas validates the provided session ID and uses it to retrieve the related
[Configuration object](/docs/reference/api/configurations/). If you created a public
Configuration, you don't need to include the `Authorization` request header with a session ID, but
you do need to pass the Configuration object ID as a query parameter.
requestBody:
content:
application/json:
schema:
type: object
properties:
cancellation_reason:
type: string
description: The reason that the booking is being cancelled.
example:
cancellation_reason: I am no longer available at this time.
x-code-samples:
- lang: bash
label: cURL (Public)
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
- lang: bash
label: cURL (Private)
source: |-
curl --compressed --request DELETE \
--url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \
--header 'Content-Type: application/json'
- lang: python
label: Python SDK (Private)
source: |
from nylas import Client
nylas = Client(
"<NYLAS_API_KEY>",
"<NYLAS_API_URI>",
)
response = nylas.scheduler.bookings.destroy(
booking_id="<BOOKING_ID>",
request_body={
"cancellation_reason": "Plans changed.",
},
query_params={
"configuration_id": "<SCHEDULER_CONFIG_ID>",
},
)
print("Booking cancelled:", response)
- lang: ruby
label: Ruby SDK (Public)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<NYLAS_API_KEY>"
)
booking, _request_ids = nylas.scheduler.bookings.destroy(booking_id: "<BOOKING_ID>", query_params: {"configuration_id": "<CONFIGURATION_ID>"})
puts booking
- lang: ruby
label: Ruby SDK (Private)
source: |-
# Load gems
require 'nylas'
# Initialize Nylas client
nylas = Nylas::Client.new(
api_key: "<SCHEDULER_SESSION_ID>"
)
booking, _request_ids = nylas.scheduler.bookings.destroy(booking_id: "<BOOKING_ID>")
puts booking
- lang: java
label: Java SDK (Public)
source: |
import com.nylas.NylasClient;
import com.nylas.models.DeleteResponse;
import com.nylas.models.DestroyBookingQueryParams;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class DeleteBookingPublic {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
DestroyBookingQueryParams queryParams = new DestroyBookingQueryParams.Builder()
.configurationId("<SCHEDULER_CONFIG_ID>")
.build();
DeleteResponse result = nylas.scheduler().bookings().destroy("<BOOKING_ID>", queryParams, null);
System.out.println("Deleted booking: " + result);
}
}
- lang: java
label: Java SDK (Private)
source: |
import com.nylas.NylasClient;
import com.nylas.models.DeleteResponse;
import com.nylas.models.NylasApiError;
import com.nylas.models.NylasSdkTimeoutError;
public class DeleteBooking {
public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
NylasClient nylas = new NylasClient.Builder("<SCHEDULER_SESSION_ID>").build();
DeleteResponse result = nylas.scheduler().bookings().destroy("<BOOKING_ID>", null, null);
System.out.println("Deleted booking: " + result);
}
}
- lang: kotlin
label: Kotlin SDK (Public)
source: |
import com.nylas.NylasClient
import com.nylas.models.DestroyBookingQueryParams
fun main() {
val nylas = NylasClient.Builder("<NYLAS_API_KEY>").build()
val queryParams = DestroyBookingQueryParams.Builder()
.configurationId("<SCHEDULER_CONFIG_ID>")
.build()
val result = nylas.scheduler().bookings().destroy("<BOOKING_ID>", queryParams)
println("Deleted booking: $result")
}
- lang: kotlin
label: Kotlin SDK (Private)
source: |
import com.nylas.NylasClient
fun main() {
val nylas = NylasClient.Builder("<SCHEDULER_SESSION_ID>").build()
val result = nylas.scheduler().bookings().destroy("<BOOKING_ID>")
println("Deleted booking: $result")
}
responses:
'200':
description: Delete Succeeded
content:
application/json:
schema:
type: object
required:
- request_id
properties:
request_id:
type: string
description: ID of the request.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- SCHEDULER_SESSION_TOKEN: []
/v3/scheduling/should-redirect/{v2_scheduler_slug}:
parameters:
- schema:
type: string
name: v2_scheduler_slug
in: path
required: true
description: The slug for the v2 Scheduling Page to redirect to v3.
get:
summary: Redirect v2 Scheduling Page
tags:
- v2 Redirects
operationId: v2-redirect
description: Redirects an existing v2 Scheduling Page to a v3 URL.
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --compressed --request GET \
--url "https://api.us.nylas.com/v3/scheduling/should-redirect/<V2_SCHEDULER_SLUG>" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
security:
- NYLAS_API_KEY: []
responses:
'200':
$ref: '#/components/responses/should-redirect'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
/v3/migration-tools/link-v2v3-apps:
post:
operationId: migration_link_v2v3_apps
tags:
- App migration
summary: Link a v2 app to a v3 app
description: |-
Link an existing v2 application to an existing v3 application.
<div id="admonition-warning">⚠️<strong>Your v2 and v3 applications must be in the same data center region to use these tools. </strong> You can only use these tools to migrate a v2 application to a v3 application in the same region. You cannot use these to move a v2 application to a different region.</div>
This is the first step of the migration process, and is how you tell Nylas which v2 application you are migrating.
To use this API you need the v2 source application ID and secret, in the format you use to authorize v2 API calls, and the v3 API key from the v3 destination application.
To verify that you own the v2 source application you're linking, add the `BasicV2` API header. This extra header is required. The `BasicV2` API header contains a Base64-encoded `V2_APP_ID:V2_APP_SECRET`, which is also used for Basic auth for any v2 API call.
```bash
--header 'BasicV2: <base64-encoded V2_APP_ID:V2_APP_SECRET> // Use the -n flag when you Base64 encode
```
No further request body is required. Nylas detects the v3 application ID from the API key, and the v2 application ID from the BasicV2 header.
The API is rate limited to 20 requests per second per Nylas application ID.
security:
- NYLAS_API_KEY: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/ApplicationObject'
description: On success, returns the existing v3 application object with added linked v2 application ID.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/migration-tools/link-v2v3-apps' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'BasicV2: <base64-encoded V2_APP_ID:V2_APP_SECRET>'
/v3/migration-tools/import-v2-app:
post:
operationId: migration_import_v2_app
tags:
- App migration
summary: Import v2 app settings to linked v3 app
description: |-
Import the settings from a v2 Nylas application to its linked v3 application. Before you use this
endpoint, make sure you
[link a v2 application to a v3 application](/docs/reference/api/app-migration/migration_link_v2v3_apps/).
This endpoint imports the following v2 settings, and sets them to the corresponding v3 application
settings:
- Your website URL.
- Your icon URL (used to customize the Hosted OAuth page).
- Redirect URIs for OAuth.
- Integrations and their settings.
- Nylas migrates Google integrations to equivalent v3 connectors.
- If you have v2 Microsoft integrations, you should create a new Azure auth app and update the
connector settings. For detailed instructions, see
[Migrating Microsoft accounts](/docs/v2/upgrade-to-v3/upgrade/migrating-microsoft-accounts/).
- Nylas migrates IMAP, iCloud, and EWS integrations to v3 connectors with auto-generated default
values.
Nylas automatically detects your application ID from the API key and finds its linked v2
application to begin the import process.
This endpoint is rate limited to 20 requests per second, per Nylas application ID.
security:
- NYLAS_API_KEY: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: string
description: Info message about success.
example: 'V2 Application imported successfully to v3 Application: app settings, Connectors, redirect URIs, etc.'
description: Immedieately returns a list of two Jobs, Snapshot and BatchClone. Those Jobs continue to synchronously run in the background.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/migration-tools/import-v2-app' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
/v3/migration-tools/grants/{account_id}/clone:
post:
operationId: migration_clone_single_account
tags:
- App migration
summary: Migrate v2 account to v3 grant
description: |-
Migrates a single v2 connected account to a v3 grant. Use this endpoint to migrate a few accounts
to v3 as a test, then use the
[Batch Clone endpoint](/docs/reference/api/app-migration/migration_snapshot_batch_clone/)
to migrate the rest.
Before you use this endpoint, your v2 Nylas applications need to be linked to their corresponding v3
applications and you need to have a working equivalent
[authentication connector](/docs/reference/api/connectors-integrations/) for each provider
you use. If you need help with this process, [learn how to get support](/docs/support/).
During migration, Nylas maps the v2 provider to its v3 equivalent using the connected account's
v2 authorization type and provider. All sensitive data (such as tokens and passwords) is encrypted
and securely transfered only within the Nylas infrastructure. No secrets exit the internal Nylas
network.
This endpoint is rate limited to 20 requests per second, per Nylas application ID.
### Create placeholder grants
Nylas can migrate existing Microsoft Graph, Office 365, and EWS accounts that use token
authentication. It can't fully migrate
[some types of Microsoft accounts](/docs/v2/upgrade-to-v3/upgrade/migrating-microsoft-accounts/#microsoft-account-import-compatibility-in-v3)
because of provider limitations and scope changes in v3.
By default, Nylas creates an invalid v3 Grant with fake credentials for accounts that it can't
automatically migrate. These grants act as "placeholders" that the user can manually authenticate
to later. You can turn this feature off for Microsoft accounts only by setting the `clone_exchange`
query parameter to `false`, or for all providers by setting `allow_invalid_grant_creation` to
`false`.
security:
- NYLAS_API_KEY: []
parameters:
- $ref: '#/components/parameters/account_id'
- name: allow_invalid_grant_creation
in: query
required: false
description: |-
(Not supported for Microsoft) When `true`, Nylas creates invalid v3 grants with fake credentials
for all connected accounts in your request. These grants act as placeholders that users can
authenticate to later.
schema:
type: boolean
default: true
- name: clone_exchange
in: query
required: false
description: |-
(Microsoft only) When `true`, Nylas creates invalid v3 grants with fake credentials for any
Microsoft accounts that can't be automatically migrated. These grants act as placeholders that
users can authenticate to later.
schema:
type: boolean
default: true
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/GrantObject'
description: On success, returns the v3 Grant object Nylas created as part of the migration.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/migration-tools/grants/<account_id>/clone' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
/v3/migration-tools/snapshot-batch-clone:
post:
operationId: migration_snapshot_batch_clone
tags:
- App migration
summary: Batch clone v2 accounts to v3 grants
description: |-
Starts a batch migration job to clone v2 connected accounts to v3 grants.
Before you use this endpoint, your v2 Nylas applications need to be linked to their corresponding v3
applications and you need to have a working equivalent
[authentication connector](/docs/reference/api/connectors-integrations/) for each provider
you use. If you need help with this process, [learn how to get support](/docs/support/).
When you make a batch clone request, Nylas starts two background jobs:
- A snapshot job that prepares non-sensitive v2 account data for migration.
- A batch clone job that migrates the v2 account data to v3 grants.
Nylas handles all data and logic for these jobs and runs them in the background to they don't block
API responses.
You can filter for certain types of accounts by specifying properties in the body of your request.
Use these options when you want to try migrating certain types of accounts in smaller batches,
or to retry failed migrations. If you don't specify any filters, Nylas uses the default values.
During migration, Nylas maps the v2 provider to its v3 equivalent using the connected account's
v2 authorization type and provider. All sensitive data (such as tokens and passwords) is encrypted
and securely transfered only within the Nylas infrastructure. No secrets exit the internal Nylas
network.
This endpoint is rate limited to 20 requests per second, per Nylas application ID.
### Create placeholder grants
Nylas can migrate existing Microsoft Graph, Office 365, and EWS accounts that use token
authentication. It can't fully migrate
[some types of Microsoft accounts](/docs/v2/upgrade-to-v3/upgrade/migrating-microsoft-accounts/#microsoft-account-import-compatibility-in-v3)
because of provider limitations and scope changes in v3.
By default, Nylas creates an invalid v3 Grant with fake credentials for accounts that it can't
automatically migrate. These grants act as "placeholders" that the user can manually authenticate
to later. You can turn this feature off for Microsoft accounts only by setting the `clone_exchange`
query parameter to `false`, or for all providers by setting `allow_invalid_grant_creation` to
`false`.
parameters:
- name: allow_invalid_grant_creation
in: query
required: false
description: |-
(Not supported for Microsoft) When `true`, Nylas creates invalid v3 grants with fake credentials
for all connected accounts in your request. These grants act as placeholders that users can
authenticate to later.
schema:
type: boolean
default: true
- name: clone_exchange
in: query
required: false
description: |-
(Microsoft only) When `true`, Nylas creates invalid v3 grants with fake credentials for any
Microsoft accounts that can't be automatically migrated. These grants act as placeholders that
users can authenticate to later.
schema:
type: boolean
default: true
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
default: 1000
description: Number of accounts to migrate. Nylas orders the migration records created by the snapshot job, by `imported_at` timestamp from oldest to newest.
example: 10
offset:
type: integer
default: 0
description: Number of accounts to skip. Nylas orders the migration records created by the snapshot job, by `imported_at` timestamp from oldest to newest.
example: 0
providers:
type: array
items:
type: string
default: If none specified, Nylas migrates all supported providers
enum:
- google
- microsoft
- graph
- imap
- icloud
- ews
- virtual-calendar
description: Use this setting to limit the migration job to a specific provider or providers, so you can migrate one type at a time.
example:
- google
- microsoft
mode:
type: string
default: all
enum:
- all
- only_new
- only_failed
description: 'Use this setting to limit the migration job to accounts that have specific statuses, or when retrying failed migrations. - ''all'': No filtering, migrate all accounts that meet the request criteria. - ''only_new'': Migrate only accounts that haven''t attempted migration. - ''only_failed'': Migrate only accounts that attempted migration previously and were marked as failed.'
example: all
security:
- NYLAS_API_KEY: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: object
properties:
clone_job:
$ref: '#/components/schemas/MigrationJob'
snapshot_job:
$ref: '#/components/schemas/MigrationJob'
description: Immediately returns a list of the two jobs for the migration run:, snapshot and batch clone. Those jobs continue to synchronously run in the background.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/migration-tools/snapshot-batch-clone' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"limit": 100,
"providers": [
"google",
"imap",
"graph",
"ews",
"icloud"
],
"mode": "all",
"clone_exchange": false
}'
/v3/migration-tools/jobs:
get:
operationId: migration_get_jobs
tags:
- App migration
summary: Get migration jobs
description: |-
Get information about the migration jobs for your application, including progress and status, for currently running and finished jobs.
Migration Jobs are a background task. After you start one Nylas returns a success response, and the jobs run in the background until they finish. These jobs do not block other API calls, but also do not send a notification when complete. This API allows you to get general information about a them, so you can see their status.
There are two types of migration job: "snapshot" and "migration". A Snapshot job takes a snapshot of the application's v2 account data, and prepares it for migration. A Migration job actually turns the v2 account data into v3 grants.
Jobs have a status, which can be one of the following:
- A _pending_ job is queued and waiting to start.
- A _running_ job is currently in progress.
- A _partial_ job has finished, but was not able to migrate all accounts successfully.
- A _completed_ job has finished and successfully migrated _all_ accounts.
- A _failed_ job has finished but did not migrate any accounts.
You can optionally filter the list of jobs to return only jobs with a specific status or type.
You can also use the `sort_by_completion` argument to return the list of jobs with pending and running jobs first, followed by failed, completed, and partial jobs. Finished jobs are ordered by their completion timestamp (`CompletedAt`) from the most recent to the oldest.
If you don't include any query parameters to filter the results, Nylas returns all jobs.
The API is rate limited to 20 requests per second per Nylas application ID.
parameters:
- name: status
in: query
required: false
description: |-
Filter for jobs by status:
- `completed`: The job finished and all accounts were migrated successfully.
- `failed`: The job finished, but no accounts were migrated.
- `partial`: The job finished. Some accounts were migrated successfully, and some failed.
- `pending`: The job is queued.
- `running`: The job is running.
schema:
type: array
items:
type: string
enum:
- completed
- failed
- partial
- pending
- running
example: running,completed
- name: type
in: query
required: false
description: Filter for jobs by type.
schema:
type: array
items:
type: string
enum:
- migration
- snapshot
example: migration
- name: sort_by_completion
in: query
required: false
description: |-
When `true`, Nylas sorts the jobs it returns in the following order:
1. Jobs with `pending` status.
2. Jobs with `running` status.
3. Jobs with all other statuses, from most to least recent `CompletedAt` time.
schema:
type: boolean
security:
- NYLAS_API_KEY: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: array
items:
$ref: '#/components/schemas/MigrationJob'
description: Returns a list of jobs.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url 'https://api.us.nylas.com/v3/migration-tools/jobs?status=pending%2Crunning%2Cfailed%2Ccompleted&type=snapshot%2Cmigration&sort_by_completion=true' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json'
/v3/migration-tools/translate:
post:
operationId: translate_v2id_to_provider_id
tags:
- Data migration
summary: Translate v2 Nylas ID into v3 Provider ID
description: |-
Use the connected account ID and a resource type, with an optional list of specific Nylas IDs, to get a response that contains a list of of Nylas IDs and their v3 Provider ID equivalents. Use this API as a one-time operation to translate v2 IDs into v3 Provider IDs. Do not use this API in your code logic as it very data intensive.
To use this endpoint, your v2 Nylas application needs to be linked to the equivalent v3 Nylas application. This endpoint does not work for objects in v2 accounts that have the provider set to `Outlook`.
By default, the API returns up to 3000 records for the requested resource type related to the v2 connected account, sorted by `created_at` date. If you specify a list of v2 Nylas IDs, the API returns the v3 Provider IDs for those specific IDs only.
Results are paginated, with a page size of 3000 results. If the response includes a `next_page_number` field, you can use that number in a request to get the next set of results.
Also, there is a possibility to search results created only after certain Unix timestamp, in Nylas v2 database. To use this, add to body payload `start_from_timestamp` valid Unix timestamp.
The API is rate limited to 20 requests per second per Nylas application ID.
### IMAP folder resource ID
When you make a Translate ID request for an IMAP folder (`resource_type: folders`), Nylas returns its name in the `v3_resource_id` field. To get the resource ID for a specific folder, Base64 encode the folder name using the following format: `v0:<NYLAS_GRANT_ID>:<FOLDER_NAME>`.
security:
- NYLAS_API_KEY: []
requestBody:
required: true
description: ''
content:
application/json:
schema:
type: object
required:
- resource_type
- v2_account_id
properties:
resource_type:
example: messages
type: string
description: The resourece(s) to get translations for.
enum:
- messages
- drafts
- threads
- contacts
- contactgroups
- events
- calendars
- folders
v2_account_id:
example: 1kb392012l0mr39hmla2exnxu
type: string
description: The v2 connected account ID to get translations for.
nylas_ids:
type: array
description: (Optional) The list of v2 IDs to translate. If omitted, Nylas returns up to 3000 IDs for the requested resource types related to that v2 connected account. Results are returned sorted by creation date, ascending.
items:
type: string
example:
- 4ro91k0t3ofvzs3b3lij6iqa2
- 5ro92l1t4pfwzt4c4mijk7jb3
- 6ro93m2u5qgxzu5d5nijl8kc4
start_from_timestamp:
example: 1727172308
type: integer
description: (Optional) The Unix timestamp to search for results created after that timestamp.
next_page_number:
example: 2
type: integer
description: (Optional) The page number for the next set of results. This appears in the response only if there are more results available.
responses:
'200':
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
$ref: '#/components/schemas/translate_v2v3_id'
description: Returns a JSON list of translated objects, with mapped v2 and translated v3 ids.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Not Authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/401'
x-code-samples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url 'https://api.us.nylas.com/v3/migration-tools/translate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--data '{
"resource_type": "messages",
"v2_account_id": "<NYLAS_ACCOUNT_ID>",
"nylas_ids": [
"<NYLAS_ACCOUNT_ID>",
"<NYLAS_ACCOUNT_ID>"
]
}'
components:
schemas:
'400':
type: object
required:
- request_id
- error
additionalProperties: false
properties:
request_id:
description: ID of the request
type: string
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
error:
description: Error object
type: object
properties:
type:
type: string
description: Type of error
example: bad_request
message:
description: Informative error message
default: Bad request
type: string
example: Bad request
provider_error:
description: (OPTIONAL) informative error message from provider's side
type: object
example:
error: invalid_grant
provider_error: Bad Request
'401':
type: object
required:
- request_id
- error
additionalProperties: false
properties:
request_id:
description: ID of the request
type: string
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
error:
description: Error object
type: object
properties:
type:
type: string
description: Type of error
example: invalid_request_error
message:
description: Informative error message
default: Authentication error
type: string
example: Authentication error
provider_error:
description: (OPTIONAL) informative error message from provider's side
type: object
example:
error: invalid_grant
provider_error: Bad Request
'404':
type: object
required:
- request_id
- error
additionalProperties: false
properties:
request_id:
description: ID of the request
type: string
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
error:
description: Error object
type: object
properties:
type:
type: string
description: Type of error
example: xyz.not_found_error
message:
description: Informative error message
default: Resource not found
type: string
example: Resource not found
provider_error:
description: (OPTIONAL) informative error message from provider's side
type: object
example:
error: invalid_grant
provider_error: Bad Request
webDesktopCallbackNoSettings:
title: Web or Desktop
properties:
platform:
type: string
description: Platform identifier
enum:
- web
- desktop
id:
type: string
description: The callback URI ID. This must be a universally unique ID (UUID).
example: 0556d035-6cb6-4262-a035-6b77e11cf8fc
url:
type: string
description: |-
Your project's callback URI, including the protocol. Nylas accepts HTTP for localhost development
_only_. Otherwise, you need to use HTTPS.
example: https://yourapp.com/callback
JsCallbackwSettings:
title: JS
properties:
platform:
type: string
description: Platform identifier
enum:
- js
id:
type: string
description: The callback URI ID. This must be a universally unique ID (UUID).
example: 0556d035-6cb6-4262-a035-6b77e11cf8fc
url:
type: string
description: |-
Your project's callback URI, including the protocol. Nylas accepts HTTP for localhost development _only_.
Otherwise, you must use HTTPS.
example: https://yourapp.com/callback
settings:
description: Additional platform settings and configurations for the Javascript callback URI.
type: object
required:
- origin
properties:
origin:
type: string
description: The `origin` is the base URL from which your project or app is served. It is required because it's a critical part of defining your app's trust boundaries to prevent cross-origin issues. Set this when you set up OAuth redirect URIs and other security settings.
example: yourapp.com
iosCallbackwSettings:
title: iOS
properties:
platform:
type: string
description: Platform identifier
enum:
- ios
id:
type: string
description: The callback URI ID. This must be a universally unique ID (UUID).
example: 0556d035-6cb6-4262-a035-6b77e11cf8fc
url:
type: string
description: |-
Your project's callback URI. This can be HTTPS or a deeplink (for example,
`<package/bundle-name>://<deeplink>`).
Nylas accepts HTTP for localhost development _only_. Otherwise, you must use HTTPS.
example: https://yourapp.com/callback
settings:
description: Additional platform settings and configurations for the iOS callback URI.
type: object
required:
- bundle_id
properties:
bundle_id:
type: string
description: The `bundle_id` (Bundle Identifier) is a unique identifier for an iOS app. It's set in the Xcode project and follows a reverse domain name style.
example: com.example.myapp
app_store_id:
type: string
description: Unique identifier for your app on the Apple App Store. This ID is assigned to your app when you submit it to the App Store and it is approved.
example: 1234567890
team_id:
type: string
example: ABCDE12345
description: Unique identifier for your Apple Developer Account or team.
AndroidCallbackwSettings:
title: Android
properties:
platform:
type: string
description: Platform identifier
enum:
- android
id:
type: string
description: The callback URI ID. This must be a universally unique ID (UUID).
example: 0556d035-6cb6-4262-a035-6b77e11cf8fc
url:
type: string
description: |-
Your project's callback URI. This can be HTTPS or a deeplink (for example,
`<package/bundle-name>://<deeplink>`).
Nylas accepts HTTP for localhost development _only_. Otherwise, you must use HTTPS.
example: https://yourapp.com/callback
settings:
description: Additional platform settings and configurations for the Android callback URI.
type: object
required:
- package_name
- sha1_certificate_fingerprint
properties:
package_name:
type: string
description: Find your app's Package Name in the Android Manifest. It's a unique identifier that distinguishes your app on the Google Play Store and on the device. It follows a reverse domain name notation, such as `com.example.myapp`.
example: com.example.myapp
sha1_certificate_fingerprint:
type: string
description: A SHA-1 hash of the app's signing certificate. This ensures that only the _signed_ version of your app can use the redirect URI.
example: AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12
ApplicationObject:
type: object
properties:
application_id:
type: string
description: Application ID
example: ad410018-d306-43f9-8361-fa5d7b2172e0
organization_id:
type: string
description: ID of organization
example: f5db4482-dbbe-4b32-b347-61c260d803ce
region:
type: string
description: Region identifier
example: us
environment:
type: string
description: Environment identifier
enum:
- production
- staging
default_workspace_id:
type: string
readOnly: true
description: |-
The ID of the application's default [workspace](/docs/reference/api/workspaces/), if one exists.
Nylas manages this value, and ignores it in create and update requests.
example: abf6ff99-05ad-4c0a-aaf8-400aacf2470a
v2_application_id:
type: string
description: Linked v2 Application ID
example: 9nsr7pjw1e1g6hgy9l1znjql7
branding:
type: object
properties:
name:
type: string
description: Name of the application
example: My application
icon_url:
type: string
description: URL points to application icon.
example: https://my-app.com/my-icon.png
website_url:
type: string
description: Application / publisher website URL
example: https://my-app.com
description:
type: string
description: Description of the application.
example: Online banking application.
hosted_authentication:
type: object
properties:
background_image_url:
type: string
description: URL of the background image
example: https://my-app.com/bg.jpg
alignment:
type: string
description: Alignment of background image
enum:
- left
- center
- right
color_primary:
type: string
description: Primary color
example: '#dc0000'
color_secondary:
type: string
description: Secondary color
example: '#000056'
title:
type: string
description: Title
subtitle:
type: string
description: Subtitle
background_color:
type: string
description: Background color
example: '#003400'
spacing:
type: integer
description: CSS spacing attribute in px
example: 5
callback_uris:
description: A list of your application's callback URIs.
type: array
items:
oneOf:
- $ref: '#/components/schemas/webDesktopCallbackNoSettings'
- $ref: '#/components/schemas/JsCallbackwSettings'
- $ref: '#/components/schemas/iosCallbackwSettings'
- $ref: '#/components/schemas/AndroidCallbackwSettings'
discriminator:
propertyName: platform
mapping:
web: '#/components/schemas/webDesktopCallbackNoSettings'
desktop: '#/components/schemas/webDesktopCallbackNoSettings'
js: '#/components/schemas/JsCallbackwSettings'
ios: '#/components/schemas/iosCallbackwSettings'
android: '#/components/schemas/AndroidCallbackwSettings'
RedirectURIObject:
oneOf:
- $ref: '#/components/schemas/webDesktopCallbackNoSettings'
- $ref: '#/components/schemas/JsCallbackwSettings'
- $ref: '#/components/schemas/iosCallbackwSettings'
- $ref: '#/components/schemas/AndroidCallbackwSettings'
discriminator:
propertyName: platform
mapping:
web: '#/components/schemas/webDesktopCallbackNoSettings'
desktop: '#/components/schemas/webDesktopCallbackNoSettings'
js: '#/components/schemas/JsCallbackwSettings'
ios: '#/components/schemas/iosCallbackwSettings'
android: '#/components/schemas/AndroidCallbackwSettings'
ConnectorObject:
type: object
additionalProperties: false
required:
- provider
- name
properties:
name:
type: string
description: The name of the connector.
example: Google Connector
provider:
type: string
description: Provider type
enum:
- google
- microsoft
- imap
- icloud
- yahoo
- virtual-calendar
- ews
- zoom
- nylas
example: google
settings:
description: Optional settings from provider
example:
topic_name: abc123
type: object
scope:
type: array
items:
type: string
description: (Not used for Zoom connectors.) Optional default scopes for the connector. For Zoom, configure scopes directly on your Zoom OAuth app. See [Zoom granular scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-granular/).
example:
- https://www.googleapis.com/auth/userinfo.email
- https://www.googleapis.com/auth/userinfo.profile
active_credential_id:
type: string
description: The ID of the "default" credential record of this Connector. This credential will be used as a default for communication with the provider.
example: c123f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
AutodetectObject:
type: object
additionalProperties: false
required:
- email_address
- detected
properties:
provider:
type: string
description: Provider detected.
example: google
type:
type: string
description: Provider type. Returned only when IMAP detected displays the IMAP provider.
example: icloud
email_address:
type: string
description: Email provided for autodetection.
example: test@example.com
detected:
type: boolean
description: Whether Nylas detected a provider for the given email address.
example: true
GrantObject:
type: object
required:
- created_at
- id
- provider
- scope
properties:
account_id:
type: string
description: |-
The v2 Nylas account ID. This field appears only if the grant was created by migrating a v2
connected account.
example: df0yq6c9okc6t9j4ejd5nyrt7
blocked:
type: boolean
description: When `true`, indicates that the grant is blocked from accessing the Nylas APIs.
example: false
created_at:
type: integer
description: When the grant was created, in seconds using the Unix timestamp format.
example: 1617817109
email:
type: string
description: |-
The email address associated with the grant. If the provider supports `id_token` and exposes the
user's email address, Nylas automatically extracts this value.
example: nyla@example.com
grant_status:
type: string
description: Specifies whether the grant is valid or the user needs to re-authenticate.
enum:
- invalid
- valid
example: valid
id:
type: string
description: A unique identifier for the grant.
example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
ip:
type: string
description: |-
The user's client IP address. Mostly useful for
[Hosted OAuth](/docs/v3/auth/hosted-oauth-apikey/).
example: 1.1.1.1
name:
type: string
description: The user's display name.
example: Nyla
provider:
type: string
description: The provider that the user authenticated with.
enum:
- ews
- google
- icloud
- imap
- microsoft
- virtual-calendar
- yahoo
- zoom
- nylas
x-enum-descriptions:
virtual-calendar: Nylas' [virtual calendars](/docs/v3/calendar/virtual-calendars/).
nylas: Nylas [Agent Accounts](/docs/v3/agent-accounts/).
example: microsoft
provider_user_id:
type: string
description: The user's provider ID. This field might be changed at any time by the provider.
example: b16f171c-6640-4edd-a598-e507b546d841
scope:
type: array
items:
type: string
description: |-
An array of [granular scopes](/docs/dev-guide/scopes/) associated with the grant. If none are
specified, Nylas uses the default scopes from the
[connector](/docs/reference/api/connectors-integrations/).
example:
- Mail.Read
- User.Read
- offline_access
settings:
type: object
description: |-
A list of settings associated with the grant. The contents of this object might differ between
grants or depending on the provider.
email_aliases:
type: array
items:
type: string
description: |-
An array of found email aliases for this grant. Only returned if special query parameter `expose_aliases` for
[Get Grant](/docs/reference/api/manage-grants/get_grant_by_id/) is used and set to `true`.
Applicable only for Google and Microsoft grants.
For Microsoft, aliases require a Microsoft 365 / Exchange Online mailbox. Free Outlook.com
(consumer) accounts have no aliases to expose, so this field is omitted from the response
even when `expose_aliases=true`.
example:
- email_alias1@example.com
- email_alias2@example.com
state:
type: string
description: |-
The initial state that was set as part of the authentication process. Nylas passes this value
back to your project without modifying it. You can use this field for verification, or to track
information about the user.
example: my-state
updated_at:
type: integer
description: |-
When the user last authenticated their grant, in seconds using the Unix timestamp format.
Initially, this value is the same as `created_at`.
example: 1617817109
user_agent:
type: string
description: |-
The user's [client or browser information](https://www.useragents.me/). Mostly useful for
[Hosted OAuth](/docs/v3/auth/hosted-oauth-apikey/).
workspace_id:
type: string
description: |-
The ID of the Workspace the grant belongs to, if any. For grants from providers other than
Agent Accounts, Nylas may omit this field when the grant is in the application's default
workspace.
example: abf6ff99-05ad-4c0a-aaf8-400aacf2470a
credential_id:
type: string
description: The ID of the Credential the grant is associated with. Grant will use this Credential for provider communication.
example: c123f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
WorkspaceObject:
type: object
properties:
application_id:
type: string
description: The ID of the application the workspace is associated with.
example: ad410018-d306-43f9-8361-fa5d7b2172e0
auto_group:
type: boolean
description: |-
When `true`, specifies that newly created grants in the application are automatically assigned
to the workspace if their email address' domain matches the `domain`.
example: true
created_at:
type: integer
description: When the workspace was created, in seconds using the Unix timestamp format.
example: 1756379932
default:
type: boolean
description: |-
When `true`, the workspace is the application's default workspace, which Nylas creates and
manages. Nylas includes this field when you retrieve workspaces. For more information, see
the [Workspaces overview](/docs/reference/api/workspaces/).
example: false
domain:
type: string
description: The top-level domain associated with the workspace.
example: nylas.com
name:
type: string
description: The name of the workspace.
example: The Nylas Workspace
policy_id:
type: string
description: |-
The ID of the [policy](/docs/v3/agent-accounts/policies-rules-lists/) attached to the workspace.
The policy applies to Agent Accounts in the workspace.
example: 6dcc5d92-8a55-4ce8-85a8-2f4275f8f0a0
rule_ids:
type: array
items:
type: string
description: |-
The IDs of any [rules](/docs/v3/agent-accounts/policies-rules-lists/#rules) attached to the
workspace. The rules apply to Agent Accounts in the workspace.
example:
- 3f2504e0-4f89-41d3-9a0c-0305e82c3301
updated_at:
type: integer
description: |-
When the workspace was last updated, in seconds using the Unix timestamp format. Initially, this
value is the same as `created_at`.
example: 1756379932
workspace_id:
type: string
description: The workspace ID.
example: abf6ff99-05ad-4c0a-aaf8-400aacf2470a
common_response:
properties:
request_id:
type: string
description: The request ID.
data:
type: object
description: The response object.
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
trigger_types:
type: array
items:
type: string
enum:
- calendar.created
- calendar.updated
- calendar.deleted
- event.created
- event.updated
- event.deleted
- grant.created
- grant.updated
- grant.deleted
- grant.expired
- grant.imap_sync_completed
- message.send_success
- message.send_failed
- message.bounce_detected
- message.created
- message.created.cleaned
- message.opened
- message.opened.legacy
- message.updated
- message.link_clicked
- message.link_clicked.legacy
- thread.replied
- thread.replied.legacy
- contact.updated
- contact.deleted
- folder.created
- folder.updated
- folder.deleted
- booking.created
- booking.pending
- booking.rescheduled
- booking.cancelled
- booking.reminder
- message.deleted
- message.transactional.bounced
- message.transactional.complaint
- message.transactional.delivered
- message.transactional.rejected
- message.bounced
- message.complaint
- message.delivered
- message.rejected
- notetaker.created
- notetaker.updated
- notetaker.deleted
- notetaker.meeting_state
- notetaker.media
description: |-
The event that triggers the notification. See the
[notification schemas](/docs/reference/notifications/) for details about each trigger
type.
See the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/),
[Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references
for information on how to trigger each event type.
destination_input_payload:
title: Destination Payload
required:
- trigger_types
- webhook_url
type: object
properties:
description:
type: string
description: A human-readable description of the webhook destination.
example: Production webhook destination
trigger_types:
$ref: '#/components/schemas/trigger_types'
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
notification_email_addresses:
type: array
items:
type: string
description: |-
The email addresses that Nylas notifies when a webhook is down for a while. See
[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for details.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: 'If `true`, Nylas compresses notification payloads using gzip before delivering them. Nylas adds the `Content-Encoding: gzip` header to the request. Default is `false`.'
default: false
example: true
destination_update_payload:
title: Destination Update Payload
properties:
description:
type: string
description: A human-readable description of the webhook destination.
example: Production webhook destination
trigger_types:
$ref: '#/components/schemas/trigger_types'
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
status:
type: string
description: The new status of the destination.
enum:
- active
- pause
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies when a webhook is down for a while. See the [rate limit documentation](/docs/dev-guide/best-practices/rate-limits/) for details.
example:
- abc@example.com
- def@example.com
compressed_delivery:
type: boolean
description: 'If `true`, Nylas compresses notification payloads using gzip before delivering them. Nylas adds the `Content-Encoding: gzip` header to the request.'
example: true
get_mock_payload_input:
title: Input Payload
type: object
required:
- trigger_type
- webhook_url
properties:
trigger_type:
type: string
enum:
- calendar.created
- calendar.updated
- calendar.deleted
- event.created
- event.updated
- event.deleted
- grant.created
- grant.updated
- grant.deleted
- grant.expired
- message.send_success
- message.send_failed
- message.bounce_detected
- message.created
- message.created.truncated
- message.created.cleaned
- message.updated
- message.updated.truncated
- contact.updated
- contact.deleted
- folder.created
- folder.updated
- folder.deleted
- message.opened
- message.link_clicked
- thread.replied
description: |-
The event that will trigger the mock notification. See the
[notification schemas](/docs/reference/notifications/) for details about each
trigger type.
See the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/),
[Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references
for information on how to trigger each event type.
You can test `message.created.truncated` and `message.updated.truncated` notifications using this
endpoint. For more information, see
[Truncated webhooks](/docs/v3/notifications/#truncated-webhooks).
send_test_event_input:
title: Input Payload
type: object
required:
- trigger_type
- webhook_url
properties:
trigger_type:
type: string
enum:
- calendar.created
- calendar.updated
- calendar.deleted
- event.created
- event.updated
- event.deleted
- grant.created
- grant.updated
- grant.deleted
- grant.expired
- message.send_success
- message.send_failed
- message.bounce_detected
- message.created
- message.created.truncated
- message.created.cleaned
- message.updated
- message.updated.truncated
- contact.updated
- contact.deleted
- folder.created
- folder.updated
- folder.deleted
- message.opened
- message.link_clicked
- thread.replied
description: |-
Select the type of event that will trigger the webhook. See the
[notification schemas](/docs/reference/notifications/) for details about each
trigger type.
See the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/),
[Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references
for information on how to trigger each event type.
You can test `message.created.truncated` and `message.updated.truncated` notifications using this
endpoint. For more information, see
[Truncated webhooks](/docs/v3/notifications/#truncated-webhooks).
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
pubsub_input_payload:
title: Destination Payload
required:
- trigger_types
- webhook_url
type: object
properties:
description:
type: string
description: A human-readable description of the Pub/Sub channel.
example: Production Pub/Sub for Events notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: 'If `true`, Nylas compresses notification payloads using gzip before delivering them. Nylas adds a `content_encoding: gzip` message attribute to the Pub/Sub message. Default is `false`.'
default: false
example: true
amazon_sns_input_payload:
title: Amazon SNS Channel Payload
required:
- trigger_types
- topic
- role_arn
type: object
properties:
description:
type: string
description: A human-readable description of the Amazon SNS channel.
example: Production SNS channel for Events notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Amazon SNS topic ARN that Nylas sends notifications to. Must start with `arn:aws:sns:`.
example: arn:aws:sns:us-east-1:123456789012:my-topic
role_arn:
type: string
description: The ARN of the IAM role that Nylas assumes to publish messages to the SNS topic. Must match `arn:aws:iam::<account-id>:role/<role-name>`.
example: arn:aws:iam::123456789012:role/nylas-sns-role
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Amazon SNS channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: 'If `true`, Nylas gzip-compresses and then base64-encodes notification payloads before delivering them. Nylas adds a `content_encoding: gzip+base64` message attribute to the SNS message. To decode, base64-decode the message body, then gzip-decompress. Default is `false`.'
default: false
example: true
CredentialObject:
type: object
additionalProperties: false
required:
- id
- name
- created_at
- updated_at
properties:
id:
type: string
description: Credential ID
example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
name:
description: Unique name of this credential
type: string
example: My first Google credential
created_at:
type: integer
description: Date of creation of the credential
example: 1617817109
updated_at:
type: integer
description: Initially same as `created_at`. Can differ if the credential has been updated.
example: 1617817109
DomainObject:
title: Domain
type: object
properties:
id:
type: string
description: Globally unique identifier for the domain.
example: abc-123-domain-id
name:
type: string
description: A human-readable label for the domain.
example: My transactional domain
branded:
type: boolean
description: If `true`, this is a Nylas-branded `nylas.email` subdomain managed by Nylas. You can only have one free Nylas branded domain per organization and region. If `false`, this is a custom domain.
example: false
domain_address:
type: string
description: The domain address (for example, `mail.example.com`).
example: mail.example.com
organization_id:
type: string
description: The ID of the Nylas organization that owns the domain.
example: org-123
region:
type: string
description: The Nylas data center region where the domain is registered.
enum:
- us
- eu
example: us
verified_ownership:
type: boolean
description: If `true`, the domain's ownership TXT record has been verified.
example: true
verified_dkim:
type: boolean
description: If `true`, the domain's DKIM TXT record has been verified.
example: false
verified_spf:
type: boolean
description: If `true`, the domain's SPF record has been verified.
example: false
verified_mx:
type: boolean
description: If `true`, the domain's MX record has been verified.
example: false
verified_feedback:
type: boolean
description: If `true`, the domain's feedback MX record for bounce detection has been verified.
example: false
verified_dmarc:
type: boolean
description: Currently not verified by Nylas. However, it is highly recommended to set DMARC to your desired value to prevent emails going to spam.
example: false
verified_arc:
type: boolean
description: Currently not verified by Nylas.
example: false
created_at:
type: number
description: When the domain was created, in seconds using the Unix timestamp format.
example: 1742932766
updated_at:
type: number
description: When the domain was last updated, in seconds using the Unix timestamp format.
example: 1742932766
DomainVerificationResponse:
title: DomainVerificationResponse
type: object
properties:
domain_id:
type: string
description: The ID of the domain.
example: abc-123-domain-id
attempt:
type: object
description: Details about the verification attempt.
properties:
type:
type: string
description: The type of DNS verification.
enum:
- ownership
- mx
- spf
- dkim
- feedback
example: ownership
options:
type: object
description: The DNS record values to configure at your DNS provider.
properties:
host:
type: string
description: The DNS host value.
example: '@'
type:
type: string
description: The DNS record type.
example: TXT
value:
type: string
description: The DNS record value to set.
example: nylas-ownership-verify=gNIeZAtY1lPUEpWOhA2XBB...
status:
type: string
description: The status of the verification attempt.
enum:
- done
- failed
- pending
example: done
created_at:
type: number
description: When the verification attempt was created, in seconds using the Unix timestamp format.
example: 1742932766
expires_at:
type: number
description: When the verification attempt expires, in seconds using the Unix timestamp format.
example: 1743537566
message:
type: string
description: A human-readable message about the verification status.
example: Domain ownership verified successfully.
PolicyObject:
title: Policy
type: object
properties:
id:
type: string
description: Globally unique identifier for the policy (UUID).
example: b1c2d3e4-5678-4abc-9def-0123456789ab
name:
type: string
description: A human-readable name for the policy. Required on create.
example: Standard Agent Account Policy
application_id:
type: string
description: The ID of the application that owns the policy. Read-only; derived from the authenticated API key.
example: ad410018-d306-43f9-8361-fa5d7b2172e0
organization_id:
type: string
description: The ID of the Nylas organization that owns the policy. Read-only; derived from the authenticated API key.
example: org-abc123
limits:
type: object
description: |-
Operational limits enforced for inboxes that use this policy. All fields are optional. If omitted, each limit defaults
to the plan's maximum allowed value. If a requested value exceeds the plan limit, the API returns an error.
properties:
limit_attachment_size_limit:
type: integer
format: int64
description: Maximum size (in bytes) for a single attachment.
example: 26214400
limit_attachment_count_limit:
type: integer
description: Maximum number of attachments allowed on a single message.
example: 20
limit_attachment_allowed_types:
type: array
description: Allowed attachment MIME types. If empty or omitted, all types permitted by the plan are allowed.
items:
type: string
example:
- image/png
- image/jpeg
- application/pdf
limit_size_total_mime:
type: integer
format: int64
description: Maximum total MIME size (in bytes) for a single message, including all attachments.
example: 31457280
limit_storage_total:
type: integer
format: int64
description: Maximum total storage (in bytes) for each inbox that uses this policy.
example: 10737418240
limit_count_daily_message_received:
type: integer
format: int64
description: Maximum number of messages each grant can receive per day.
example: 1000
limit_count_daily_email_sent:
type: integer
format: int64
description: Maximum number of messages each grant can send per day.
example: 1000
limit_inbox_retention_period:
type: integer
description: |-
How long (in days) to retain messages in the inbox before they are deleted. Must be greater than
`limit_spam_retention_period` when both are set.
example: 365
limit_spam_retention_period:
type: integer
description: |-
How long (in days) to retain messages in the spam folder before they are deleted. Must be shorter than
`limit_inbox_retention_period` when both are set.
example: 30
rules:
type: array
description: |-
(Legacy) Rule IDs linked to this policy. Rule evaluation uses the `rule_ids` array on the
[workspace](/docs/reference/api/workspaces/), not the policy. Set rules on the workspace instead.
Whether rules are allowed depends on your plan.
items:
type: string
example:
- c1d2e3f4-5678-4abc-9def-0123456789ab
spam_detection:
type: object
description: Spam detection configuration for inboxes that use this policy.
properties:
use_list_dnsbl:
type: boolean
description: If `true`, enables DNS-based block list (DNSBL) checking on inbound messages.
example: true
use_header_anomaly_detection:
type: boolean
description: If `true`, enables header anomaly detection on inbound messages.
example: true
spam_sensitivity:
type: number
format: float
minimum: 0.1
maximum: 5
default: 1
description: Spam detection sensitivity. Must be between `0.1` and `5.0`. Higher values mark more messages as spam.
example: 1.5
created_at:
type: integer
description: When the policy was created, in seconds using the Unix timestamp format.
example: 1742932766
updated_at:
type: integer
description: When the policy was last updated, in seconds using the Unix timestamp format.
example: 1742932766
RuleObject:
title: Rule
type: object
properties:
id:
type: string
description: Globally unique identifier for the rule (UUID).
example: c1d2e3f4-5678-4abc-9def-0123456789ab
name:
type: string
description: A human-readable name for the rule. Required on create.
example: Block spam domains
description:
type: string
description: An optional description of what the rule does.
example: Rejects messages from known spam domains at the SMTP level.
priority:
type: integer
minimum: 0
maximum: 1000
default: 10
description: Execution order for the rule. Lower numbers run first. Must be between `0` and `1000`. Defaults to `10`.
example: 1
enabled:
type: boolean
default: true
description: Whether the rule is active. Defaults to `true`.
example: true
trigger:
type: string
enum:
- inbound
- outbound
default: inbound
description: |-
When the rule is evaluated. `inbound` rules run on incoming messages. `outbound` rules run on sends
before the message is submitted to the email provider — an `outbound` rule with a `block` action
rejects the send with HTTP 403 and no message is delivered. Non-blocking actions (`mark_as_spam`,
`archive`, `mark_as_read`, `mark_as_starred`, `assign_to_folder`, `trash`) on outbound rules apply
to the stored sent copy. Inbound and outbound rules are isolated: inbound rules never run during sends, and
outbound rules never run on receipt.
example: inbound
match:
type: object
description: Defines the conditions that must be met for the rule to apply.
properties:
operator:
type: string
enum:
- any
- all
description: |-
How conditions are combined. Use `any` to match when any condition is true (OR), or `all` to
require every condition to be true (AND). When omitted, the rule defaults to `all`.
example: any
conditions:
type: array
description: The list of conditions to evaluate. At least one condition is required.
items:
type: object
properties:
field:
type: string
enum:
- from.address
- from.domain
- from.tld
- recipient.address
- recipient.domain
- recipient.tld
- outbound.type
description: |-
The field to match against. `from.*` fields match the normalized sender and are valid on
both triggers: `from.address` is the full sender email, `from.domain` is the domain
portion, and `from.tld` is the top-level domain. `recipient.*` fields are valid only on
`outbound` rules and match against **any** recipient — including To, CC, BCC, and SMTP
envelope recipients. For `is_not`, the condition is true only when **no** recipient
matches. `outbound.type` is valid only on `outbound` rules and classifies the send as
`compose` (a fresh message) or `reply` (a reply to an existing thread). The type is
derived as `reply` when the send includes `reply_to_message_id` or the raw MIME
contains `In-Reply-To` or `References` headers; otherwise it's `compose`.
example: from.domain
operator:
type: string
enum:
- is
- is_not
- contains
- in_list
description: |-
How to compare the field value. Use `is` for an exact match, `is_not` for the inverse,
`contains` for substring matching, or `in_list` to check against one or more List
resources. String matching is case-insensitive. The `outbound.type` field accepts only
`is` and `is_not` — `contains` and `in_list` are rejected.
example: is
value:
description: |-
The value to compare the field against. For `is`, `is_not`, and `contains`, this is a
string. For `in_list`, this is an array of List IDs. For `outbound.type`, this is
`compose` or `reply` — values are normalized to lowercase on write.
oneOf:
- type: string
- type: array
items:
type: string
example: spam-domain.com
actions:
type: array
description: |-
The actions to perform when the rule matches. At least one action is required. The `block` action cannot be
combined with other actions — it is terminal.
items:
type: object
properties:
type:
type: string
enum:
- block
- mark_as_spam
- assign_to_folder
- mark_as_read
- mark_as_starred
- archive
- trash
description: |-
The action to take on the matching message or send. `block` rejects inbound mail at the SMTP
level or rejects an outbound send before provider submission. `mark_as_spam` routes the
message or stored sent copy to the spam folder, `assign_to_folder` files it in the folder
named in `value`, and the remaining actions modify the message state.
example: block
value:
type: string
description: |-
Required when `type` is `assign_to_folder` — the target folder by name. Use a custom folder's
name (or its full path for a nested folder, e.g. `Clients/Acme`), or a system folder name
(`Inbox`, `Sent`, `Drafts`, `Trash`, `Junk`, `Archive`). The name is resolved when the rule
runs, so a reference to a folder that doesn't exist is skipped. Optional for other action types.
example: Receipts
application_id:
type: string
description: The ID of the application that owns the rule. Read-only; derived from the authenticated API key.
example: ad410018-d306-43f9-8361-fa5d7b2172e0
organization_id:
type: string
description: The ID of the Nylas organization that owns the rule. Read-only; derived from the authenticated API key.
example: org-abc123
created_at:
type: integer
description: When the rule was created, in seconds using the Unix timestamp format.
example: 1742932766
updated_at:
type: integer
description: When the rule was last updated, in seconds using the Unix timestamp format.
example: 1742932766
GrantRuleEvaluationObject:
title: GrantRuleEvaluation
type: object
description: |-
An audit record of a single rule-engine evaluation against an inbound message, SMTP envelope, or
outbound send for a grant. Rule evaluations are created automatically during inbound processing and
outbound send handling and can be listed to trace which rules matched, what input was considered,
and which actions were applied.
properties:
id:
type: string
description: Globally unique identifier for this evaluation record (UUID).
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
grant_id:
type: string
description: The grant this evaluation belongs to (UUID).
example: 41009df5-bf11-4c97-aa18-b285b5f2e386
message_id:
type:
- string
- 'null'
description: |-
The inbound message or stored sent copy associated with this evaluation (UUID). `null` when the
evaluation happened before a message record existed, such as `smtp_rcpt`, or when an outbound
evaluation did not persist a sent copy.
example: e8b5a51d-3c2f-4a1e-9d7b-6f8c2e1a4b3d
evaluated_at:
type: integer
description: When the evaluation occurred, in seconds using the Unix timestamp format.
example: 1713000000
evaluation_stage:
type: string
enum:
- smtp_rcpt
- inbox_processing
- outbound_send
description: |-
Where in the processing pipeline the evaluation happened. `smtp_rcpt` means the evaluation ran
during SMTP RCPT TO processing (before the message was accepted) — `message_id` is `null` in
this case. `inbox_processing` means the evaluation ran after the message was accepted and
during inbox processing — `message_id` is populated. `outbound_send` means the evaluation ran
for an outbound send; `message_id` is populated when a sent copy was stored, and `null` when
the send was blocked before storage or no sent copy was persisted.
example: inbox_processing
evaluation_input:
type: object
description: The normalized sender, recipient, and send-type data that rules were matched against.
properties:
from_address:
type: string
description: The normalized sender email address.
example: sender@example.com
from_domain:
type: string
description: The normalized domain portion of the sender address.
example: example.com
from_tld:
type: string
description: The normalized top-level domain of the sender address.
example: com
recipient_addresses:
type: array
description: Outbound recipient email addresses considered during rule evaluation.
items:
type: string
example:
- recipient@example.com
- bcc@example.net
recipient_domains:
type: array
description: Outbound recipient domains considered during rule evaluation.
items:
type: string
example:
- example.com
- example.net
recipient_tlds:
type: array
description: Outbound recipient top-level domains considered during rule evaluation.
items:
type: string
example:
- com
- net
outbound_type:
type: string
enum:
- compose
- reply
description: Outbound send classification used during rule evaluation.
example: reply
applied_actions:
type: object
description: |-
The actions that were applied as a result of matching rules. Only populated fields are returned —
fields are **omitted** (not set to `false`) when the corresponding action was not applied.
properties:
blocked:
type: boolean
description: The inbound message or outbound send was blocked and not delivered. Terminal action.
example: true
marked_as_spam:
type: boolean
description: The message or stored sent copy was moved to the junk/spam folder.
marked_as_read:
type: boolean
description: The message or stored sent copy was automatically marked as read.
marked_starred:
type: boolean
description: The message or stored sent copy was automatically starred.
archived:
type: boolean
description: The message or stored sent copy was archived.
trashed:
type: boolean
description: The message or stored sent copy was moved to trash.
folder_ids:
type: array
description: IDs of the custom folders the message or stored sent copy was assigned to.
items:
type: string
example:
- 4f2e1a0d-c3b2-4a5e-8d9c-6f8b2e1a4b3d
matched_rule_ids:
type: array
description: |-
IDs of the rules that matched during this evaluation. Empty when no rules matched (for example,
when rule execution ran but nothing applied).
items:
type: string
example:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
application_id:
type: string
description: The application this evaluation belongs to (UUID). Read-only; derived from the authenticated API key.
example: 5f37fe8d-c4ba-4898-bc18-aad5bb34735e
organization_id:
type: string
description: The Nylas organization this evaluation belongs to (UUID). Read-only; derived from the authenticated API key.
example: 9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210
created_at:
type: integer
description: When the evaluation record was created, in seconds using the Unix timestamp format.
example: 1713000000
updated_at:
type: integer
description: When the evaluation record was last updated, in seconds using the Unix timestamp format.
example: 1713000000
ListObject:
title: List
type: object
properties:
id:
type: string
description: Globally unique identifier for the list (UUID).
example: d1e2f3a4-5678-4abc-9def-0123456789ab
name:
type: string
description: A human-readable name for the list. 1–256 characters. Required on create.
example: Blocked domains
description:
type: string
description: An optional description of the list's purpose.
example: Domains we've identified as sending unwanted mail.
type:
type: string
enum:
- domain
- tld
- address
description: |-
The kind of values the list holds and which rule condition fields it can be used with. Required on create and
immutable after creation. `domain` holds domain names (matched against `from.domain` or `recipient.domain`),
`tld` holds top-level domains (matched against `from.tld` or `recipient.tld`), and `address` holds full email
addresses (matched against `from.address` or `recipient.address`).
example: domain
items_count:
type: integer
description: The number of items currently in the list. Read-only; maintained by the system.
example: 42
application_id:
type: string
description: The ID of the application that owns the list. Read-only; derived from the authenticated API key.
example: ad410018-d306-43f9-8361-fa5d7b2172e0
organization_id:
type: string
description: The ID of the Nylas organization that owns the list. Read-only; derived from the authenticated API key.
example: org-abc123
created_at:
type: integer
description: When the list was created, in seconds using the Unix timestamp format.
example: 1742932766
updated_at:
type: integer
description: When the list was last updated, in seconds using the Unix timestamp format.
example: 1742932766
ListItemObject:
title: ListItem
type: object
properties:
id:
type: string
description: Globally unique identifier for the list item (UUID).
example: e1f2a3b4-5678-4abc-9def-0123456789ab
list_id:
type: string
description: The ID of the list that contains the item.
example: d1e2f3a4-5678-4abc-9def-0123456789ab
value:
type: string
description: |-
The item's value, normalized (lowercased and trimmed) on write. The format depends on the parent list's `type`:
a domain, a top-level domain, or an email address.
example: spam-domain.com
created_at:
type: integer
description: When the item was added to the list, in seconds using the Unix timestamp format.
example: 1742932766
common_response_with_cursor:
properties:
request_id:
type: string
description: The request ID.
data:
type: object
description: The response object.
next_cursor:
type:
- string
- 'null'
description: A cursor pointing to the next page of results for the request.
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
grant_id:
title: Grant ID
type: string
description: The ID of grant for the connected user.
example: 41009df5-bf11-4c97-aa18-b285b5f2e386
readOnly: true
attachment:
description: A file attached to an email message.
type: object
required:
- id
properties:
id:
type: string
description: The ID of the attachment.
readOnly: true
example: 4kj2jrcoj9ve5j9yxqz5cuv98
content_type:
type: string
minLength: 1
description: |-
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the attachment, used by the email client to determine how to display the attachment. If you don't provide a type, Nylas infers it from the file name.
The value of this field is exactly the same as the email attachment's `Content-Type` header.
The provider might set additional parameters, such as `name` and `charset`.
Nylas returns an empty `content_type` field if an attachment file name contains non-ASCII characters (for example, accented characters like `ü`). This is because Google can't detect its content type.
example: image/png; name="pic.png"
filename:
type: string
minLength: 1
description: The file name of the attachment.
example: pic.png
grant_id:
$ref: '#/components/schemas/grant_id'
content_id:
type: string
description: |-
(Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the message's HTML. For
example, you might see something like `<img src=\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\">` in
the message body.
Sometimes, the `content_id` value is contained in angle brackets (for example,
`<ce9b9547-9eeb-43b2-ac4e-58768bdf04e4>`).
example: 1234567890
content_disposition:
type: string
description: (Not supported for Microsoft and EWS) The content disposition of the attachment. Usually, this is `inline` or `attachment` followed by the file name (for example, `inline; filename="some-image.jpeg"`).
example: inline
is_inline:
type: boolean
description: If `true`, indicates that the attachment is an inline file.
example: true
size:
type: integer
description: The size of the attachment, in bytes.
example: 13068
message-participant:
title: Message participant
type: object
description: A name/email address pair.
properties:
name:
type: string
example: Jon Snow
email:
type: string
format: email
example: jon.snow@example.com
required:
- email
message-participant-response:
title: Message participant response
type: object
description: A name/email address pair.
properties:
name:
type: string
example: Jon Snow
email:
type: string
format: email
example: jon.snow@example.com
message-header:
title: Message header
type: object
description: A message header key-value pair.
properties:
name:
type: string
example: Date
value:
type: string
example: Thu, 15 Aug 2024 00:59:58 +0000 (UTC)
required:
- name
- value
id:
title: ID
type: string
minLength: 1
description: A globally unique object identifier for Microsoft accounts. An email address for Google accounts.
example: 5d3qmne77v32r8l4phyuksl2x, nyla@example.com
metadata:
title: Metadata
type: object
description: |-
The metadata associated with the object. For more information, see
[Metadata](/docs/reference/api/#metadata).
additionalProperties:
type: string
description: A key-value pair.
maxLength: 500
maxProperties: 50
message:
title: Message
type: object
properties:
attachments:
type: array
description: |-
An array of Attachment objects. For Google, linked Google Drive files are not included. For
Microsoft, linked OneDrive files are not included.
items:
$ref: '#/components/schemas/attachment'
uniqueItems: true
minItems: 0
example:
- content_disposition: attachment
content_type: text/calendar
filename: null
content_id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_disposition: attachment
content_type: application/ics
filename: invite.ics
content_id: 70jcsv367jaiavt4njeu4xswg
size: 1708
bcc:
type: array
description: |-
An array of name/email address pairs that the message was BCC'd to. For received messages, this
is nearly always empty.
items:
$ref: '#/components/schemas/message-participant'
body:
type: string
description: |-
The body of the message as either plain-text or HTML content. If the message has both plain-text
and HTML, Nylas returns the HTML version.
example: Hello, I just sent a message using Nylas!
cc:
type: array
description: An array of name/email address pairs that the message was CC'd to.
items:
$ref: '#/components/schemas/message-participant'
date:
type: integer
description: |-
Unix timestamp in seconds that represents when _the mail server_ received the message. This might be
different from the unified `Date` header in a raw Message object.
example: 1635355739
folders:
type: array
description: |-
The IDs of the folders that the message appears in. Microsoft messages can be in a single folder
only. Google allows a single message to appear in multiple folders.
items:
type: string
uniqueItems: true
example:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
type: array
description: |-
A list of name/email address pairs that the message was sent from. This is usually one pair only,
but can be many.
items:
$ref: '#/components/schemas/message-participant-response'
uniqueItems: true
grant_id:
$ref: '#/components/schemas/grant_id'
headers:
type: array
description: |-
An array of key-value pairs that contain the message headers. Nylas returns this field when you
set the `fields` query parameter to either `include_headers` or `include_basic_headers`.
- `fields=include_headers`: Returns the full set of headers on the message.
- `fields=include_basic_headers`: Returns only the three RFC threading headers (`Message-ID`,
`In-Reply-To`, `References`). Use this option when you only need to track message identity and
thread relationships — payload size is significantly smaller than `include_headers`.
A single message can sometimes have multiple headers with the same key name. Nylas adds all of
the headers to the `headers` array without merging or de-duplicating the data. When the headers
contain encoded data, Nylas adds it to the `headers` array without decoding it. If you need the
decoded data, you need to build decoding logic into your project.
Some headers might contain raw MIME information (for example,
`=?Windows-1252?Q?Re:_Candidature_de_Mme_Leyah_Miller?=`).
items:
$ref: '#/components/schemas/message-header'
id:
$ref: '#/components/schemas/id'
in_reply_to:
type: string
description: |-
(EWS only) The ID of the message that this message replies to. This ID is the same as the
`In-Reply-To` header.
example: <b0582d2c-816d-42a4-9ff8-46073170d827@me.com>
metadata:
$ref: '#/components/schemas/metadata'
object:
type: string
description: The object type of the response (in this case, `message`).
example: message
raw_mime:
type: string
description: |-
A Base64url-encoded string containing the message data (including the body content).
To get the raw MIME content for a message, set the `fields` query parameter to `raw_mime` in
your request. When you request raw MIME data, Nylas returns the `grant_id`, `object`, `id`,
and `raw_mime` fields only.
reply_to:
type: array
items:
$ref: '#/components/schemas/message-participant'
uniqueItems: true
description: An array of name/email address pairs that should receive replies to the message.
snippet:
type: string
minLength: 1
description: |-
A short snippet (the first 100 characters, with HTML tags removed) of the message body. This is
useful for displaying a preview of the message.
example: |-
You have been invited to the following event. Welcome! WhenThu Oct 28, 2021
7am - 8am Eastern Time - Toronto Joining info
starred:
type: boolean
description: |-
If `true`, shows that the message has been starred by the user. For EWS, this is only supported
on Microsoft Exchange 2010 or later.
example: false
subject:
type: string
description: The subject of the message.
example: Nylas Send v3 Email
thread_id:
type: string
minLength: 1
description: |-
A reference to the parent Thread object. Every message is associated with a thread, whether that
thread contains one message or many. If the message is new, Nylas assigns a `thread_id` to it.
example: 1t8tv3890q4vgmwq6pmdwm8qgsaer
to:
type: array
description: An array of name/email address pairs that the message was sent to.
items:
$ref: '#/components/schemas/message-participant'
uniqueItems: true
tracking_options:
type: object
description: Tracking options for the message.
properties:
opens:
type: boolean
description: When `true`, shows that message open tracking is enabled.
example: true
thread_replies:
type: boolean
description: When `true`, shows that thread replied tracking is enabled.
example: true
links:
type: boolean
description: When `true`, shows that link clicked tracking is enabled.
example: true
label:
type: string
description: A label describing the message tracking purpose.
maxLength: 2048
example: Tracking test
unread:
type: boolean
description: If `true`, shows that the message has not been read by the user.
example: true
tracking_domain_name:
type: string
minLength: 1
maxLength: 253
example: tracking.example.com
description: |-
The custom hostname to use for link click and message open tracking. The hostname must be
registered to the authenticated organization in the
[Nylas Dashboard](https://dashboard-v3.nylas.com/organization/domains?tab=hosted-auth) and have an
active certificate.
Custom tracking hostnames are available on select plans. Contact your Nylas account representative
or the [Nylas Sales team](https://www.nylas.com/contact-sales/) to enable this feature for your
organization.
Nylas trims surrounding whitespace, removes one trailing dot, and converts ASCII letters to
lowercase before looking up the hostname. Provide an ASCII fully qualified hostname without a URL
scheme, path, port, or wildcard.
You must enable `links`, `opens`, or both when you provide this field. A custom tracking hostname
does not support `thread_replies` by itself. If you omit this field, Nylas uses its regional
tracking hostname. Invalid, inactive, blocked, deleted, and unowned hostnames return the same
generic `400` response. If Nylas cannot complete the explicit ownership and certificate lookup, it
returns a `5xx` response without falling back to a Nylas hostname.
use_draft:
type: boolean
description: |-
(Google and Microsoft only) If `true` when scheduling a message, Nylas saves the message in the user's
Drafts folder until it's sent. For more information, see
[Schedule messages to send in the future](/docs/v3/email/scheduled-send/).
default: false
example: false
message_send_response:
title: Message
type: object
properties:
attachments:
type: array
description: An array of Attachment objects. For google, linked Google Drive files are not included. For Microsoft, linked One Drive files are not included.
items:
$ref: '#/components/schemas/attachment'
uniqueItems: true
minItems: 0
example:
- content_disposition: attachment
content_type: text/calendar
filename: null
content_id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_disposition: attachment
content_type: application/ics
filename: invite.ics
content_id: 70jcsv367jaiavt4njeu4xswg
size: 1708
bcc:
type: array
description: |-
An array of name/email address pairs that the message was BCC'd to. For received messages, this
is nearly always empty.
items:
$ref: '#/components/schemas/message-participant'
body:
type: string
description: The body of the message. This field is the same as the `body` field in your request.
example: Hello, I just sent a message using Nylas!
cc:
type: array
description: An array of name/email address pairs that the message was CC'd to.
items:
$ref: '#/components/schemas/message-participant'
date:
type: integer
description: |-
Unix timestamp in seconds that represents when _the mail server_ received the message. This might be
different from the unified `Date` header in a raw Message object.
example: 1635355739
folders:
type: array
description: |-
The ID(s) of the folder(s) that the message appears in.
Microsoft messages can be in a single folder only. Google allows a single message to appear in
multiple folders.
items:
type: string
uniqueItems: true
example:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
type: array
description: |-
A list of name/email address pairs that the message was sent from. This is usually one pair only,
but can be many.
items:
$ref: '#/components/schemas/message-participant-response'
uniqueItems: true
grant_id:
$ref: '#/components/schemas/grant_id'
headers:
type: array
description: |-
An array of key-value pairs that contain the message headers. Nylas returns this field when you
set the `fields` query parameter on the send request to either `include_headers` or
`include_basic_headers`. This is supported for **synchronous** send only — the parameter has no
effect when you set the `send_at` field on the request.
- `fields=include_headers`: Returns the full set of headers on the response.
- `fields=include_basic_headers`: Returns only the three RFC threading headers (`Message-ID`,
`In-Reply-To`, `References`). Use this option when you only need to track message identity and
thread relationships — payload size is significantly smaller than `include_headers`.
A single message can sometimes have multiple headers with the same key name. Nylas adds all of
the headers to the `headers` array without merging or de-duplicating the data. When the headers
contain encoded data, Nylas adds it to the `headers` array without decoding it. If you need the
decoded data, you need to build decoding logic into your project.
Some headers might contain raw MIME information (for example,
`=?Windows-1252?Q?Re:_Candidature_de_Mme_Leyah_Miller?=`).
items:
$ref: '#/components/schemas/message-header'
id:
$ref: '#/components/schemas/id'
object:
type: string
description: The object type of the response (in this case, `message`).
example: message
reply_to:
type: array
items:
$ref: '#/components/schemas/message-participant'
uniqueItems: true
description: An array of name/email address pairs that should receive replies to the message.
reply_to_message_id:
type: string
description: The unique identifier of the message to which you want to draft a reply.
example: 1t8tv3890q4vgmwq6pmdwm8qg
schedule_id:
type: string
description: The ID of the scheduled message. Nylas returns the `schedule_id` if `send_at` is set.
example: c712c7ec-0bbd-4038-a69a-d7c287b026f5
snippet:
type: string
minLength: 1
description: |-
A short snippet (the first 100 characters, with HTML tags removed) of the message body. This is
useful for displaying a preview of the message.
example: |-
You have been invited to the following event. Welcome! WhenThu Oct 28, 2021 7am - 8am Eastern
Time - Toronto Joining info
starred:
type: boolean
description: |-
When `true`, shows that the message has been starred by the user. For EWS, this is only supported
for Microsoft Exchange 2010 or later.
example: false
subject:
type: string
description: The subject of the message.
example: Nylas Send v3 Email
thread_id:
type: string
minLength: 1
description: |-
A reference to the parent Thread object. Every message is associated with a thread, whether that
thread contains only one message or many. If this is a new message, Nylas assigns a `thread_id`
to it.
example: 1t8tv3890q4vgmwq6pmdwm8qgsaer
tracking_options:
type: object
description: Tracking options for the message.
properties:
opens:
type: boolean
description: When `true`, shows that message open tracking is enabled.
example: true
thread_replies:
type: boolean
description: When `true`, shows that thread replied tracking is enabled.
example: true
links:
type: boolean
description: When `true`, shows that link clicked tracking is enabled.
example: true
label:
type: string
description: A label describing the message tracking purpose.
maxLength: 2048
example: Tracking test
to:
type: array
description: An array of name/email address pairs that the message was sent to.
items:
$ref: '#/components/schemas/message-participant'
uniqueItems: true
unread:
type: boolean
description: When `true`, shows that the message has not been read by the user.
example: true
use_draft:
$ref: '#/components/schemas/use_draft'
Schedules:
type: object
required:
- schedule_id
- status
properties:
schedule_id:
type: string
description: The ID of the scheduled message.
status:
type: object
description: The status of the specified scheduled message.
properties:
code:
type: string
description: The status code which describes the state of the specified scheduled message.
description:
type: string
description: A description of the status of the specified scheduled message.
close_time:
type: integer
description: The time that the message was sent, or failed to send, in seconds using the Unix timestamp format.
smart_compose_suggestion:
title: PromptSuggestion
required:
- suggestion
type: object
properties:
suggestion:
title: Suggestion
type: string
attachment_transactional_send:
description: A file attachment for a transactional email message.
type: object
properties:
content_type:
type: string
minLength: 1
description: |-
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the attachment, used by the email client to determine how to display the attachment. If you don't provide a type, Nylas infers it from the file name.
The value of this field is exactly the same as the email attachment's `Content-Type` header.
The provider might set additional parameters, such as `name` and `charset`.
Nylas returns an empty `content_type` field if an attachment file name contains non-ASCII characters (for example, accented characters like `ü`). This is because Google can't detect its content type.
example: image/png; name="pic.png"
filename:
type: string
minLength: 1
description: The file name of the attachment.
example: pic.png
content_id:
type: string
description: |-
(Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the message's HTML. For
example, you might see something like `<img src=\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\">` in
the message body.
Sometimes, the `content_id` value is contained in angle brackets (for example,
`<ce9b9547-9eeb-43b2-ac4e-58768bdf04e4>`).
example: 1234567890
content_disposition:
type: string
description: (Not supported for Microsoft and EWS) The content disposition of the attachment. Usually, this is `inline` or `attachment` followed by the file name (for example, `inline; filename="some-image.jpeg"`).
example: inline
is_inline:
type: boolean
description: If `true`, indicates that the attachment is an inline file.
example: true
size:
type: integer
description: The size of the attachment, in bytes.
example: 13068
transactional_send_message:
type: object
properties:
id:
type: string
description: The message ID.
example: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
attachments:
type: array
description: An array of Attachment objects. For google, linked Google Drive files are not included. For Microsoft, linked One Drive files are not included.
items:
$ref: '#/components/schemas/attachment_transactional_send'
uniqueItems: true
minItems: 0
example:
- content_disposition: attachment
content_type: text/calendar
filename: null
content_id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_disposition: attachment
content_type: application/ics
filename: invite.ics
content_id: 70jcsv367jaiavt4njeu4xswg
size: 1708
bcc:
type: array
description: |-
An array of name/email address pairs that the message was BCC'd to. For received messages, this
is nearly always empty.
items:
$ref: '#/components/schemas/message-participant'
body:
type: string
description: The body of the message. This field is the same as the `body` field in your request.
example: Hello, I just sent a message using Nylas!
cc:
type: array
description: An array of name/email address pairs that the message was CC'd to.
items:
$ref: '#/components/schemas/message-participant'
from:
type: array
description: A list of name/email address pairs that the message was sent from. For transactional send, this will always be one pair.
items:
$ref: '#/components/schemas/message-participant-response'
uniqueItems: true
object:
type: string
description: The object type of the response (in this case, `message`).
example: message
reply_to:
type: array
items:
$ref: '#/components/schemas/message-participant'
uniqueItems: true
description: An array of name/email address pairs that should receive replies to the message.
snippet:
type: string
minLength: 1
description: |-
A short snippet (the first 100 characters, with HTML tags removed) of the message body. This is
useful for displaying a preview of the message.
example: |-
You have been invited to the following event. Welcome! WhenThu Oct 28, 2021 7am - 8am Eastern
Time - Toronto Joining info
subject:
type: string
description: The subject of the message.
example: Nylas Send v3 Email
tracking_options:
type: object
description: Tracking options for the message.
properties:
opens:
type: boolean
description: When `true`, shows that message open tracking is enabled.
example: true
links:
type: boolean
description: When `true`, shows that link clicked tracking is enabled.
example: true
label:
type: string
description: A label describing the message tracking purpose.
maxLength: 2048
example: Tracking test
to:
type: array
description: An array of name/email address pairs that the message was sent to.
items:
$ref: '#/components/schemas/message-participant'
uniqueItems: true
signature:
title: Signature
type: object
properties:
id:
type: string
description: Globally unique identifier for the signature.
readOnly: true
example: sig_abc123
grant_id:
$ref: '#/components/schemas/grant_id'
name:
type: string
description: A label for the signature (for example, "Work", "Personal", or "Mobile").
example: Work Signature
body:
type: string
description: The HTML content of the signature. Images must use externally hosted URLs.
example: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p></div>
object:
type: string
description: The type of object.
example: signature
readOnly: true
created_at:
type: integer
description: Unix timestamp when the signature was created.
readOnly: true
example: 1706367600
updated_at:
type: integer
description: Unix timestamp when the signature was last modified.
readOnly: true
example: 1706367600
draft:
title: Drafts
type: object
description: A draft of a message. You can edit a draft until you send it as a message.
properties:
bcc:
type: array
description: The name/email address pairs of the recipients to be BCC'd.
items:
$ref: '#/components/schemas/message-participant'
body:
type: string
description: |-
The body of the draft as either plain-text or HTML content. If the draft has both plain-text and
HTML, Nylas returns the HTML version.
example: Hi, Welcome to Nylas!
cc:
type: array
description: The name/email address pairs of the recipients to be CC'd.
items:
$ref: '#/components/schemas/message-participant'
attachments:
type: array
description: An array of Attachment objects. For Google, linked Google Drive files are not included. For Microsoft, linked One Drive files are not included.
items:
$ref: '#/components/schemas/attachment'
example:
- content_disposition: attachment
content_type: text/calendar
filename: null
id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_disposition: attachment
content_type: application/ics
filename: invite.ics
id: 70jcsv367jaiavt4njeu4xswg
size: 1708
folders:
type: array
description: A list of folder IDs. For Microsoft, only a single folder is supported. For Google, multiple folders may exist.
items:
type: string
uniqueItems: true
example:
- display_name: IMPORTANT
id: 8l6c4d11y1p4dm4fxj52whyr9
name: important
- display_name: INBOX
id: d9zkcr2tljpu3m4qpj7l2hbr0
name: inbox
from:
type: array
description: An array containing a single name/email address pair, to set as the `From` header.
items:
$ref: '#/components/schemas/message-participant-response'
uniqueItems: true
example:
- email: healthcare.demo@example.com
name: ''
grant_id:
$ref: '#/components/schemas/grant_id'
id:
$ref: '#/components/schemas/id'
metadata:
$ref: '#/components/schemas/metadata'
object:
type: string
description: The object type of the response. In this case, `draft`.
example: draft
reply_to:
type: array
description: An array of name/email address pairs that should receive replies to the message.
items:
$ref: '#/components/schemas/message-participant'
uniqueItems: true
example:
- email: healthcare.demo@example.com
name: ''
snippet:
type: string
minLength: 1
description: |-
A short snippet of the message body (the first 100 characters, with any HTML tags removed). This
is useful for displaying a preview of a draft message.
example: |-
You have been invited to the following event. Welcome! WhenThu Oct 28, 2021 7am - 8am Eastern
Time - Toronto Joining info
starred:
type: boolean
description: |-
When `true`, shows that the Draft has been starred by the user. For EWS, this is only supported
for Microsoft Exchange 2010 or later.
example: false
subject:
type: string
description: The subject line of the draft.
example: 'Invitation: Welcome! @ Thu Oct 28, 2021 7am - 8am (EDT) - Toronto'
thread_id:
type: string
description: A reference to the parent Thread object. If this is a new draft, the thread is empty.
example: 1t8tv3890q4vgmwq6pmdwm8qg
to:
type: array
description: The name/email address pairs of the recipients.
minItems: 1
items:
$ref: '#/components/schemas/message-participant'
uniqueItems: true
example:
- email: demo@example.com
name: ''
- email: realestate.demo@example.com
name: ''
thread:
title: Thread
type: object
properties:
grant_id:
$ref: '#/components/schemas/grant_id'
id:
$ref: '#/components/schemas/id'
object:
type: string
description: The type of object (in this case, `thread`).
latest_draft_or_message:
type: object
description: The latest message or draft in the thread.
$ref: '#/components/schemas/message'
has_attachments:
type: boolean
description: When `true`, indicates that the message has attachments.
example: false
has_drafts:
type: boolean
description: When `true`, indicates that the message is a draft.
example: false
earliest_message_date:
type: integer
description: |-
The date when the earliest or first message in the thread was sent or received, in seconds using the Unix timestamp
format.
latest_message_received_date:
type: integer
description: |-
The date when the most recent incoming message in the thread was received, in seconds using the Unix timestamp
format.
latest_message_sent_date:
type: integer
description: The date when the most recent outgoing message in the thread was sent, in seconds using the Unix timestamp format.
participants:
type: array
description: A sub-object that contains the names and email addresses of all participants in the thread.
items:
type: object
properties:
email:
type: string
name:
type: string
snippet:
type: string
minLength: 1
description: |-
A short snippet (the first 100 characters, with HTML tags removed) of the body of the last
received message. This is useful for displaying a preview of a message.
example: jnlnnn --Sent with Nylas
starred:
type: boolean
description: |-
When `true`, indicates that the thread is starred. For EWS, this is only supported for Microsoft
Exchange 2010 or later.
example: false
subject:
type: string
description: The subject line of the thread.
example: Nylas Send v3 Thread
unread:
type: boolean
description: When `false`, indicates that all messages in the thread have been read.
message_ids:
type: array
description: An array of IDs for all messages in the thread.
items:
type: string
draft_ids:
type: array
description: An array of IDs for all drafts in the thread.
items:
type: string
folders:
type: array
description: |-
An array of folder IDs for all folders that the messages in the thread appear in.
Microsoft messages can only be in one folder at a time. Google messages can be in multiple
folders.
items:
type: string
uniqueItems: true
example:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
object:
type: string
description: The type of object.
folder:
title: Folder
type: object
description: An email folder or label.
properties:
background_color:
type: string
description: |-
(Google only) The background color of the folder, in hexadecimal format (for example, `#0099EE`).
See the
[list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)
for more information.
child_count:
type: integer
description: (Microsoft and EWS only) The number of immediate child folders nested under the specified folder.
readOnly: true
grant_id:
$ref: '#/components/schemas/grant_id'
id:
$ref: '#/components/schemas/id'
name:
type: string
description: The name of the folder.
example: Invoices
object:
$ref: '#/components/schemas/object'
parent_id:
type: string
description: (Microsoft and EWS only) The ID of the parent folder.
single_level:
type: boolean
description: (Microsoft only) If `true`, retrieves folders from a single-level hierarchy only. If `false`, retrieves folders across a multi-level hierarchy.
system_folder:
type: boolean
description: |-
(Google only) If `true`, the folder is a standard folder created by Google. If `false`, the folder
was created by the user.
readOnly: true
text_color:
type: string
description: |-
(Google only) The text color of the folder, in hexadecimal format (for example, `#0099EE`). See
the
[list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)
for more information.
total_count:
type: integer
description: The number of items inside the folder.
readOnly: true
unread_count:
type: integer
description: The number of unread items inside the folder.
readOnly: true
attributes:
type: array
description: |-
An array of attribute descriptors shared by system folders across providers. For example, folders
that contain sent messages ("Sent Items" on Microsoft, or "SENT" on other providers) have the
`["\\Sent"]` attribute. For more information, see
[Common folder attributes](/docs/v3/email/folders/#common-folder-attributes). If a folder does not have one of the standard system folders, Nylas returns the `attributes` array empty.
You can't query for folders using attributes, but you _can_ manually filter through folders to
find any that match the attributes you're looking for.
items:
type: string
minItems: 0
create_folder:
title: create_folder
type: object
required:
- name
properties:
name:
type: string
maxLength: 1024
minLength: 1
description: Creates a folder with the specified display name.
parent_id:
type: string
description: (Microsoft and EWS only) The ID of the parent folder.
text_color:
type: string
description: (Google only) The text color of the folder, in hexadecimal format (for example, `#0099EE`). See the [list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color) for more information.
background_color:
type: string
description: (Google only) The background color of the folder, in hexadecimal format (for example, `#0099EE`). See the [list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color) for more information.
update_folder:
title: update_folder
type: object
properties:
name:
type: string
description: The name of the folder to be updated.
parent_id:
type: string
description: (Microsoft and EWS only) The ID of the parent folder.
text_color:
type: string
description: |-
(Google only) The text color of the folder, in hexadecimal format (for example, `#0099EE`). See
[Google's reference documentation](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)
for a list of accepted values.
background_color:
type: string
description: |-
(Google only) The background color of the folder, in hexadecimal format (for example, `#0099EE`).
See
[Google's reference documentation](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)
for a list of accepted values.
attachment_metadata:
description: Metadata for a file attached to an email message.
type: object
properties:
id:
$ref: '#/components/schemas/id'
content_type:
type: string
minLength: 1
description: |-
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the attachment, used by the email client to determine how to display the attachment. If you don't provide a type, Nylas infers it from the file name.
The value of this field is exactly the same as the email attachment's `Content-Type` header.
The provider might set additional parameters, such as `name` and `charset`.
Nylas returns an empty `content_type` field if an attachment file name contains non-ASCII characters (for example, accented characters like `ü`). This is because Google can't detect its content type.
example: image/png; name="pic.png"
filename:
type: string
minLength: 1
description: The file name of the attachment.
example: pic.png
grant_id:
$ref: '#/components/schemas/grant_id'
content_id:
type: string
description: |-
(Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the message's HTML. For
example, you might see something like `<img src=\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\">` in
the message body.
example: 1234567890
content_disposition:
type: string
description: (Not supported for Microsoft and EWS) The content disposition of the attachment. Usually, this is `inline` or `attachment` followed by the file name (for example, `inline; filename="some-image.jpeg"`).
example: inline; filename="pic.png"
is_inline:
type: boolean
description: Whether the attachment is inline (embedded in the message body, such as an image).
example: true
size:
type: integer
description: The size of the attachment, in bytes.
example: 13068
calendar_description:
title: Calendar description
type: string
description: (Not supported for iCloud or EWS) A brief description of the calendar.
example: Junior sports league carpool drivers
calendar_hex_color:
title: Background color hex code
type: string
description: |-
(Not supported for iCloud or EWS) The background color of the calendar, in hexadecimal format (for
example, `#0099EE`). When empty, Nylas uses the default background color.
You can set or modify this value using a `PUT` request only.
example: '#039BE5'
calendar_hex_foreground_color:
title: Foreground color hex code
type: string
description: |-
(Google only) The foreground color of the calendar, in hexadecimal format (for example, `#0099EE`).
When empty, Nylas uses the default foreground color.
You can modify this value using a `PUT` request only.
example: '#039BE5'
is_owned_by_user:
title: Is Owned By User
type: boolean
description: If `true`, indicates that the user owns the calendar. This field can't be modified once set.
calendar_location:
type: string
description: (Not supported for iCloud or EWS) The geographic location of the calendar, as free-form text.
example: London, England
calendar_name:
type: string
description: The name of the calendar.
example: My New Calendar
calendar_owner_email:
title: Owner email
type: string
description: |-
(Microsoft only) The email address of the account that owns the calendar. Use it to tell the grant's own
calendars apart from calendars shared with the grant.
This field is read-only.
example: nyla@example.com
calendar_read_only:
title: Read-only setting
type: boolean
description: |-
Set by the provider. If `true`, indicates that the calendar is read-only.
If the calendar is read-only, all of its events have `read_only` set to `true`. This field _cannot_
be modified.
calendar_timezone:
title: Calendar timezone
type: string
description: |-
(Google and virtual calendars only) An [IANA timezone database](https://en.wikipedia.org/wiki/Tz_database)
formatted string (for example, `America/New_York`).
example: America/Los_Angeles
calendar_common:
title: Calendar
type: object
description: A Calendar object.
properties:
description:
$ref: '#/components/schemas/calendar_description'
grant_id:
$ref: '#/components/schemas/grant_id'
hex_color:
$ref: '#/components/schemas/calendar_hex_color'
hex_foreground_color:
$ref: '#/components/schemas/calendar_hex_foreground_color'
id:
$ref: '#/components/schemas/id'
is_owned_by_user:
$ref: '#/components/schemas/is_owned_by_user'
is_primary:
type:
- boolean
description: If `true`, indicates that the calendar is the primary for the grant.
location:
$ref: '#/components/schemas/calendar_location'
metadata:
$ref: '#/components/schemas/metadata'
name:
$ref: '#/components/schemas/calendar_name'
object:
$ref: '#/components/schemas/object'
example: calendar
owner_email:
$ref: '#/components/schemas/calendar_owner_email'
read_only:
$ref: '#/components/schemas/calendar_read_only'
timezone:
$ref: '#/components/schemas/calendar_timezone'
meeting_settings_common:
type: object
description: A collection of settings for the Notetaker bot.
properties:
action_items:
type: boolean
description: |-
When `true`, Notetaker generates a list of action items from the meeting. If `action_items` is
`true`, `video_recording`, `audio_recording`, and `transcription` must also be `true`.
default: true
example: true
action_items_settings:
type: object
properties:
custom_instructions:
type: string
description: |-
A custom prompt to pass to Nylas' AI model and specify settings for the list of action items
it generates. `action_items` must be `true` to use this field.
example: Only return the 5 most important action items.
audio_recording:
type: boolean
description: When `true`, Notetaker records the meeting's audio.
default: true
example: true
leave_after_silence_seconds:
type: integer
description: |-
The number of seconds of silence after which the Notetaker bot automatically leaves
the meeting. This helps end recordings when meetings have concluded but participants
haven't disconnected the call. Must be between 10 and 3600 seconds (1 hour).
minimum: 10
maximum: 3600
default: 300
example: 360
summary:
type: boolean
description: |-
When `true`, Notetaker generates a summary of the meeting. If `summary` is `true`,
`video_recording`, `audio_recording`, and `transcription` must also be `true`.
default: true
example: true
summary_settings:
type: object
properties:
custom_instructions:
type: string
description: |-
A custom prompt to pass to Nylas' AI model and specify settings for the summary it generates.
`summary` must be `true` to use this field.
example: Return this summary in the MEDPIC sales methodology.
transcription:
type: boolean
description: |-
When `true`, Notetaker transcribes the meeting's audio. If `transcription` is `true`,
`video_recording` and `audio_recording` must also be `true`.
default: true
example: true
video_recording:
type: boolean
description: When `true`, Notetaker records the meeting's video.
default: true
example: true
meeting_settings:
allOf:
- $ref: '#/components/schemas/meeting_settings_common'
- type: object
properties:
transcription_settings:
type:
- object
- 'null'
description: |-
Optional settings that tune how Notetaker transcribes audio. `transcription` must be
`true` for these settings to take effect. Provide any combination of the fields below.
The fields fall into two independent groups:
- **Language hints** (`expected_languages`, `fallback_language`) constrain automatic
language detection. This declares the languages you expect; it does not translate
transcripts or force the recording into a specific language.
- **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward
domain-specific terms such as names, acronyms, and product names.
Set on individual Notetakers, on calendar sync, or on event sync. When set on a calendar,
events inherit the value unless the event's own request overrides it. Send `null` or `{}`
to clear inherited settings and return to default transcription behavior.
See [Set transcription languages](/docs/v3/notetaker/#set-transcription-languages) for
supported language codes and validation rules.
properties:
expected_languages:
type: array
description: |-
Language codes the audio is expected to contain. Optional. When provided, it must
contain at least one supported code and cannot be `null` or empty. When omitted,
transcription considers all supported languages.
minItems: 1
items:
type: string
example:
- en
- es
fallback_language:
type: string
description: |-
Language to use if Notetaker does not detect one of the `expected_languages`. Optional.
When `expected_languages` is set, the fallback must be one of those codes. When
`expected_languages` is omitted, transcription considers all supported languages and
the fallback may be any supported code. When `fallback_language` is omitted, the
transcriber auto-detects the language. The field is not stored, so responses do not
return it.
example: en
keywords:
type: array
description: |-
Domain-specific terms that bias transcription toward recognizing them correctly, such
as names, acronyms, and product names. Optional. Up to 200 terms; each term must be
1 to 200 characters and cannot contain control characters. Cannot be `null`.
maxItems: 200
items:
type: string
maxLength: 200
example:
- Nylas
- AssemblyAI
use_speaker_names_as_keywords:
type: boolean
description: |-
When `true`, Notetaker adds known speaker names to the keyword set so they are
transcribed accurately. Optional. Cannot be `null`.
example: true
calendar_sync:
type: object
properties:
meeting_settings:
$ref: '#/components/schemas/meeting_settings'
name:
type: string
description: The display name for the Notetaker bot.
default: Nylas Notetaker
example: Nylas Notetaker
rules:
type: object
description: Rules for when the Notetaker bot should join a meeting.
properties:
event_selection:
type: array
items:
type: string
enum:
- all
- external
- internal
- own_events
- participant_only
x-enum-descriptions:
all: Join all events with meeting links.
external: Join all events where the host's domain differs from any participant's domain.
internal: Join all events where the host's domain matches all participants' domains.
own_events: Join all events where the user is the host.
participant_only: Join all events where the user is a participant, but not the host.
description: |-
Specify the types of events Notetaker should join.
- "all": Join all events with meeting links.
- "external": Join all events where the host's domain differs from any participant's domain.
- "internal": Join all events where the host's domain matches all participants' domains.
- "own_events": Join all events where the user is the host.
- "participant_only": Join all events where the user is a participant, but not the host.
example:
- internal
participant_filter:
type: object
description: |-
Specify filters to determine which events Notetaker should join, based on the number of
participants. If you don't specify any settings, a Notetaker joins meetings regardless of
participants.
properties:
participants_gte:
type: integer
description: |-
Join all events where the number of participants is greater than or equal to the specified
value.
example: 5
participants_lte:
type: integer
description: |-
Join all events where the number of participants is less than or equal to the specified
value.
example: 5
calendar:
allOf:
- $ref: '#/components/schemas/calendar_common'
- properties:
notetaker:
$ref: '#/components/schemas/calendar_sync'
availability_buffer:
title: buffer
type: object
properties:
before:
type: integer
description: |-
The amount of buffer time to add before meetings, in increments of five minutes. For example,
if an account has a meeting scheduled from 10:00–11:00a.m., and you set a `before` buffer of
30 minutes, Nylas treats 9:30–11:00a.m. as busy.
This value must be between 0 and 120, and must be divisible by 5.
default: 0
minimum: 0
maximum: 120
after:
type: integer
description: |-
The amount of buffer time to add after meetings, in increments of five minutes. For example, if
an account has a meeting scheduled from 10:00–11:00a.m., and you set an `after` buffer of 15
minutes, Nylas treats 10:00–11:15a.m. as busy.
This value must be between 0 and 120, and must be divisible by 5.
default: 0
minimum: 0
maximum: 120
availability_open_hours:
description: A time block when a participant is available for meetings.
type: object
title: Open Hours
examples: []
properties:
days:
type: array
description: |-
The days of the week that the open hours settings are applied to. Sunday corresponds to `0`, and
Saturday corresponds to `6`.
items:
type: integer
enum:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
example:
- 0
- 1
- 2
timezone:
type: string
minLength: 1
description: The calendar's time zone as an [IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string.
example: America/Chicago
start:
type: string
minLength: 1
description: |-
The start time for the open hours settings, in 24-hour time format. Nylas omits leading zeroes.
The minimum start time is `0:00`, and the maximum is `23:49`.
example: '10:00'
end:
type: string
minLength: 1
description: The end time for the open hours settings, in 24-hour time format. Nylas omits leading zeroes.
example: '14:00'
exdates:
type: array
description: A list of dates that Nylas excludes from the account's open hours, in `YYYY-MM-DD` format.
items:
type: string
example:
- '2006-01-18'
availability_rules:
title: ''
type: object
properties:
availability_method:
type: string
default: max-availability
enum:
- collective
- max-fairness
- max-availability
buffer:
type: object
description: |-
The amount of buffer time Nylas adds around existing meetings, in minutes. For example, if an
account has a meeting scheduled from 10:00–11:00a.m., and you set a buffer of 30 minutes, Nylas
treats 9:30–11:30a.m. as busy.
$ref: '#/components/schemas/availability_buffer'
default_open_hours:
type: array
description: |-
A default set of open hours to apply to all participants. You can overwrite these open hours for
individual participants by specifying `open_hours` on the Participant object.
items:
$ref: '#/components/schemas/availability_open_hours'
round_robin_group_id:
type: string
description: |-
The ID on events that Nylas considers when calculating the order of round-robin participants.
This is used for both max-fairness and max-availability calculations.
To calculate participant order correctly, set the metadata key `key5` to the same value on any
events you want to consider for the current set of round-robin participants. You can set this
key to any value that helps you identify events used to calculate availability in this group
(for example, `new_subscriber_onboarding`).
tentative_as_busy:
type: boolean
default: true
description: (Microsoft and EWS only) When `true`, Nylas treats tentative events as busy.
availability_specific_time_availability:
description: A specific date and time range when the participant is available.
type: object
required:
- date
- start
- end
- timezone
properties:
date:
type: string
description: The date in `YYYY-MM-DD` format.
example: '2026-03-18'
end:
type: string
description: The end time in `HH:MM` format (24-hour).
example: '17:00'
start:
type: string
description: The start time in `HH:MM` format (24-hour).
example: '09:00'
timezone:
type: string
description: The participant's IANA timezone for this availability window.
example: America/Toronto
availability_time_slot:
title: TimeSlot
type: object
properties:
emails:
type:
- array
- 'null'
description: A list of participant email addresses for this time slot. This field may be `null`. Treat `null` the same as an empty array.
items:
type: string
start_time:
type: integer
description: The start of a time slot, in seconds using the Unix timestamp format.
end_time:
type: integer
description: The end of a time slot, in seconds using the Unix timestamp format.
event_id:
type: string
description: (Group Events Only). The event ID of the group event
master_id:
type: string
description: (Group Events Only). The master ID of the recurring group event
calendar_id:
type: string
description: (Group Events Only). The calendar ID of the group event
availability_response:
description: The response to a successful request to get availability for a participant.
type: object
properties:
order:
type: array
items:
type: string
description: (Round-robin events only) The order of participants in line to attend the proposed meeting.
time_slots:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/availability_time_slot'
description: |-
An array of the available time slots when you can create a meeting using the requested settings.
This field may be `null` if no time slots are available. Treat `null` the same as an empty array.
freebusy_request:
title: free-busy
type: object
required:
- start_time
- end_time
- emails
properties:
start_time:
type: integer
description: |-
The start of a time block, in seconds using the Unix timestamp format. Nylas uses `start_time` and `end_time` to assess
the specified account's free/busy schedule.
example: 1690862400
end_time:
type: integer
description: |-
The end of a time block, in seconds using the Unix timestamp format. Nylas uses `start_time` and `end_time` to
assess the specified account's free/busy schedule.
For Google and EWS accounts, Nylas can query a timespan of up to 3 months from the `start_time`.
For Microsoft Graph accounts, Nylas can query a timespan of up to 62 days from the `start_time`.
example: 1691208000
emails:
type: array
description: A list of email addresses to check the free/busy schedules for.
items:
type: string
tentative_as_busy:
type: boolean
default: true
description: When `true`, Nylas treats tentative events as busy.
event_calendar_id:
title: Event's Calendar ID
type:
- string
- 'null'
description: |-
The calendar ID associated with the event. If you used the `calendar_id=primary` query parameter in
your request, Nylas returns the real calendar ID instead of `primary`.
For Microsoft calendars, there are some cases where the event Nylas returns isn't associated with
a calendar ID. This happens most often when the event is created in a shared calendar.
This field may be `null` for certain event types (for example, virtual calendar events).
example: 7d93zl2palhxqdy6e5qinsakt
event_conferencing_response:
title: Event with conferencing
type: object
description: |-
An object that contains event conferencing details. Nylas appends the conference information to the
Event `description`.
properties:
provider:
type: string
enum:
- Google Meet
- GoToMeeting
- Microsoft Teams
- Skype for Business
- Skype for Consumer
- WebEx
- Zoom Meeting
- unknown
oneOf:
- title: Auto-conferencing
type: object
description: Conference Nylas autocreated for the event.
properties:
autocreate:
type: object
description: |-
The autocreate settings Nylas used to generate the conference for the event.
After the conferencing provider creates the meeting, Nylas returns the concrete meeting
information — such as the URL and meeting code — in the `details` object and appends it to
the event `description`. For an autocreated conference, expect the response `conferencing`
object to contain a `provider` and a `details` object once the meeting exists.
- title: Google Meet
type: object
description: Manually-attached Google Meet conferencing details.
properties:
details:
type: object
description: An object that contains Google Meet conferencing details.
properties:
url:
type: string
description: The URL for the Google Meet conference.
phone:
type: array
items:
type: string
description: The phone number associated with the Google Meet conference.
pin:
type: string
description: The PIN associated with the Google Meet conference, if applicable.
- title: Zoom Meeting
type: object
description: Manually-attached Zoom Meeting conferencing details.
properties:
details:
type: object
description: An object that contains Zoom conferencing details.
properties:
url:
type: string
description: The URL for the Zoom conference.
meeting_code:
type: string
description: A unique ID associated with the Zoom conference.
password:
type: string
description: The password for the Zoom conference, if applicable.
- title: Microsoft Teams
type: object
description: Manually-attached Microsoft Teams conferencing details.
properties:
details:
type: object
description: An object that contains Microsoft Teams conferencing details.
properties:
url:
type: string
description: The URL for the Microsoft Teams conference.
- title: WebEx
type: object
description: Manually-attached WebEx conferencing details.
properties:
details:
type: object
description: An object that contains WebEx conferencing details.
properties:
url:
type: string
description: The URL for the WebEx conference.
password:
type: string
description: The password for the WebEx conference, if applicable.
pin:
type: string
description: The PIN for the WebEx conference, if applicable.
phone:
type: array
items:
type: string
description: The phone number associated with the WebEx conference.
- title: GoToMeeting
type: object
description: Manually-attached GoToMeeting conferencing details.
properties:
details:
type: object
description: An object that contains GoToMeeting conferencing details.
properties:
url:
type: string
description: The URL for the GoToMeeting conference.
meeting_code:
type: string
description: A unique ID associated with the GoToMeeting conference.
password:
type: string
description: The password for the GoToMeeting conference, if applicable.
phone:
type: array
items:
type: string
description: The phone number associated with the GoToMeeting conference.
event_created_at:
type:
- integer
- 'null'
description: When the event was created, in seconds using the Unix timestamp format.
example: 1661874192
event_html_link:
type: string
description: (Not supported for EWS events) A link to the event on the provider.
example: https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Ef3feD2VuM29fMjAyMjA2MjdUMjIwMDAwWiBoYWxsYUBueWxhcy5jb20
event_ical_uid:
title: iCal format ID
type:
- string
- 'null'
description: |-
A unique ID that you can use to identify events across calendaring systems, in
[iCalendar format](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.4.7).
Recurring events might share the same ID.
Can be `null` for events synced before the year 2020.
event_id:
title: Event ID
type: string
minLength: 1
description: The ID of the event. Event IDs are usually unique to each user, except for Google which maintains the same event ID for an event regardless of the user querying it.
example: 5d3qmne77v32r8l4phyuksl2x
organizer:
type: object
description: An object that contains information about an event's organizer.
properties:
name:
type: string
description: The organizer's full name.
example: Leyah Miller
email:
type: string
description: |-
The organizer's email address.
For an event in a Google calendar, Nylas returns the `email` based on the calender type.
- For a primary calendar, `email` is the same as the `calendar_id`.
- For a non-primary calendar, `email` is set to the actual ID of the calendar.
example: leyah@example.com
event_participants:
title: Event participants list
type: array
description: |-
An array of participants invited to the event. The organizer doesn't need to be explicitly
included in this list.
uniqueItems: true
minItems: 1
items:
type: object
properties:
comment:
type: string
description: A note or comment about the participant (for example, their nickname).
example: Will be 5 minutes late.
email:
type: string
description: The participant's email address. For Microsoft Graph, this field can be missing.
example: kaveh@example.com
name:
type: string
description: The participant's name.
example: Kaveh
phone_number:
type: string
description: The participant's phone number.
example: 555-555-5555
status:
type: string
description: The participant's RSVP status.
enum:
- 'yes'
- 'no'
- maybe
- noreply
default: noreply
example: 'yes'
event_resources:
title: Resource information
description: Resources are physical locations or equipment that can be reserved for events, and which are tracked using an email address with an associated calendar.
type: object
properties:
email:
type: string
description: The resource's email address.
example: conference-room@resource.google.com
name:
type: string
description: The resource's full name.
example: Conference room
required:
- email
event_read_only:
title: Event read-only setting
type: boolean
description: |-
If `true`, indicates that the event is read-only. The provider sets the `read_only` value based on
the connected calendar, and you can't modify it.
In cases where you _can_ update this field on a cloned event (for example, an event imported to your
calendar from an email invitation), `read_only` is `true`.
If the calendar is read-only, all events on the calendar have `read_only` set to `true`.
event_reminders:
title: Event reminders list
type: object
description: |-
A list of reminders to generate for the event. If not defined, Nylas uses the provider's default
settings.
properties:
use_default:
type:
- boolean
- 'null'
description: |-
When `true`, the event uses the calendar's default reminder settings.
This field may be `null` if reminders are not explicitly configured.
- **Google**: Generates a `popup`-style reminder 10 minutes before the event begins.
- **Microsoft**: Generates a reminder 15 minutes before the event begins.
- **iCloud**: Does not generate a reminder.
- **EWS**: Generates a `display`-style reminder 15 minutes before the event begins.
overrides:
type:
- array
- 'null'
description: |-
A list of reminders for the event to use when `use_default` is `false`. If this field is empty
or omitted, and `use_default` is `false`, the event does not send reminders. If `true`, Nylas
generates both the default event reminder and any reminders in the `overrides` list.
You cannot set reminder overrides if `use_default` is `true`.
For Microsoft Graph, EWS, and iCloud, you can set only one reminder per event.
This field may be `null` if no reminder overrides have been set. Treat `null` the same as an
empty array.
items:
type: object
properties:
reminder_minutes:
type: integer
example: 20
description: The number of minutes before the event to display a reminder.
reminder_method:
type: string
description: |-
(Google and iCloud only) The method used to notify the user about the event, with separate
options and default settings for each provider.
- **Google**:
- Default: `popup`
- Options: `popup`, `email`
- **iCloud**:
- Default: `display`
- Options: `display`, `sound`
enum:
- popup
- email
- display
- sound
example: popup
event_recurrence:
title: Event recurrence settings
type: array
items:
type: string
example:
- RRULE:FREQ=WEEKLY;BYDAY=MO
- EXDATE:20210405T000000Z
description: |-
An array of `RRULE` and `EXDATE` strings. Nylas includes this field only if the event is the main
(master) event. See [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5) for more details.
You can use [this tool](https://jkbrzt.github.io/rrule/) to learn more about the `RRULE` spec.
Events inherit their timezone from the `when` object. Nylas recommends that you use the `when`
object to specify the event's start and end time.
Provider specifics:
- On some providers, `EXDATE` might not include exception or cancelled event timestamps. When this
happens, Nylas represents those event instances as separate objects in its responses.
- Virtual calendars don't support `DTSTART` or `TZID`.
- iCloud accounts do _not_ support changing an event from recurring to non-recurring. You can create,
update, or delete information on recurring events.
- Microsoft Graph adds one day to the `UNTIL` date.
event_status:
title: Event status
type: string
description: |-
(Not supported for iCloud) The status of the event. You can't set this field when creating or updating
an event. If you're the organizer of the event and you want to reply "maybe" or "no" to the
invitation, use the
[Send RSVP endpoint](/docs/reference/api/events/send-rsvp/)
instead.
For Google events, a `cancelled` status indicates that the event was an occurrence of a recurring
event, and that the occurrence has been cancelled by the event organizer.
For Microsoft and EWS events, a `cancelled` status indicates that the event was organized by someone
else, and the organizer cancelled or deleted the event.
example: confirmed
enum:
- confirmed
- cancelled
- maybe
event_updated_at:
type:
- integer
- 'null'
description: When the event was last updated, in seconds using the Unix timestamp format.
example: 1661874192
event_visibility:
title: Event visibility on calendars
type:
- string
- 'null'
enum:
- default
- private
- public
examples: []
description: |-
(Not supported for iCloud events) Specifies whether the event is `public` or `private`. If not
defined, Nylas uses the account's default provider settings. For Google and Microsoft, event visibility is `public` by default.
The `default` enum value is only valid for Google events, where it defers to the calendar's own sharing settings. Microsoft and EWS events only support `public` and `private`; sending `default` for these providers returns a 400 error.
For virtual calendar events, you can explicitly set `visibility` to `private` or `public` on create and update requests. If not set, virtual calendar events default to `public` behavior.
event_timespan:
title: Timespan
type: object
description: A period of time with a specified beginning and end (for example, an hour-long lunch meeting).
properties:
start_time:
type: integer
description: The event's start time, in seconds using the Unix timestamp format.
example: 1409594400
end_time:
type: integer
example: 1409598000
description: The event's end time, in seconds using the Unix timestamp format.
start_timezone:
type:
- string
- 'null'
minLength: 1
example: America/New_York
description: |-
The timezone of the event's `start_time` as an
[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.
If you define `start_timezone` in your request, you must also define `end_timezone`.
end_timezone:
type:
- string
- 'null'
minLength: 1
example: America/New_York
description: |-
The timezone of the event's `end_time` as an
[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.
If you define `end_timezone` in your request, you must also define `start_timezone`.
event_date:
title: Date
type: object
description: |-
The date on which the event occurs, without a clock-based start
or end time (for example, a birthday or holiday).
properties:
date:
type: string
example: '2021-05-09'
description: The date of the event, in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates).
event_datespan:
title: Datespan
type: object
description: |-
A span of days, without specific clock-based start and end times
(for example, a business quarter or semester). For more information, see [All-day event handling](/docs/v3/calendar/using-the-events-api/#all-day-event-handling).
properties:
start_date:
type: string
minLength: 1
description: The event's start date, in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates).
example: '2024-12-01'
end_date:
type: string
description: The event's end date (inclusive), in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates).
example: '2024-12-02'
event_when_response:
title: When
type:
- object
- 'null'
description: |-
An object that represents the time and duration of an event. Nylas might format `when` as one of three
sub-objects: `timespan`, `date`, or `datespan`. These sub-objects allow Nylas to capture and represent
specific points in time.
`timespan` objects include optional timezone support.
This field may be `null` when event timing data is unavailable (for example, when using field selection
that excludes the underlying time fields).
anyOf:
- allOf:
- $ref: '#/components/schemas/event_timespan'
- type: object
- readOnly: true
- allOf:
- $ref: '#/components/schemas/event_date'
- type: object
- readOnly: true
- allOf:
- $ref: '#/components/schemas/event_datespan'
- type: object
- readOnly: true
event_sync:
type: object
properties:
id:
type: string
readOnly: true
description: The Notetaker bot ID. Read-only; returned in responses but not required in create or update requests.
example: 71c807752c744ad0902f64d43e6cc399
meeting_settings:
$ref: '#/components/schemas/meeting_settings'
name:
type: string
description: The display name for the Notetaker bot.
default: Nylas Notetaker
example: Nylas Notetaker
event_common:
title: Event
type: object
properties:
busy:
type: boolean
description: |-
If `true`, shows the event's time block as `busy` on shared or public calendars. This may be
called "transparency" in some systems.
calendar_id:
$ref: '#/components/schemas/event_calendar_id'
conferencing:
$ref: '#/components/schemas/event_conferencing_response'
created_at:
$ref: '#/components/schemas/event_created_at'
description:
type:
- string
- 'null'
description: |-
A brief description of the event (for example, its agenda). The description might be returned
as an HTML string, depending on how the provider formats it.
For Google accounts, this field accepts a maximum of 8,192 characters.
example: Time for us to sync weekly on any new project changes
minLength: 0
text_description:
type:
- string
- 'null'
description: |-
A brief text description of the event (for example, its agenda). If the description is HTML-formatted,
this field will contain the text version of the description.
example: Time for us to sync weekly on any new project changes
minLength: 0
hide_participants:
type: boolean
description: (Not supported for iCloud or EWS events) When `true`, hides the event's list of participants.
grant_id:
$ref: '#/components/schemas/grant_id'
html_link:
$ref: '#/components/schemas/event_html_link'
ical_uid:
$ref: '#/components/schemas/event_ical_uid'
id:
$ref: '#/components/schemas/event_id'
location:
type:
- string
- 'null'
description: The location of the event (for example, a physical address or the name of a meeting room).
master_event_id:
type:
- string
- 'null'
description: |-
If the event is an instance of a recurring event series, this field lists the ID of the parent
event. If the parent event belongs to a different calendar that you don't have access to, or it's
been deleted or cancelled, you can't retrieve it using this ID.
metadata:
$ref: '#/components/schemas/metadata'
object:
$ref: '#/components/schemas/object'
organizer:
$ref: '#/components/schemas/organizer'
participants:
$ref: '#/components/schemas/event_participants'
resources:
type: array
description: An array of room resource bookings added to the event.
items:
$ref: '#/components/schemas/event_resources'
read_only:
$ref: '#/components/schemas/event_read_only'
reminders:
$ref: '#/components/schemas/event_reminders'
recurrence:
$ref: '#/components/schemas/event_recurrence'
status:
$ref: '#/components/schemas/event_status'
title:
type: string
minLength: 1
description: The name of the event.
maxLength: 1024
example: 'Remote Event: Group Yoga Class'
updated_at:
$ref: '#/components/schemas/event_updated_at'
visibility:
$ref: '#/components/schemas/event_visibility'
when:
$ref: '#/components/schemas/event_when_response'
original_start_time:
type: integer
description: |-
(Not supported for virtual calendars) The original start time of the event, in seconds using the Unix timestamp
format. This field is present only if the event is an instance of a recurring event.
example: 1633698000
notetaker:
$ref: '#/components/schemas/event_sync'
event_busy:
title: Event busy settings
type:
- boolean
- 'null'
description: |-
When `true`, shows the event's time block as "busy" on shared or public calendars. This might be
called "transparency" in some systems. This field may be `null` if not explicitly set. Treat `null`
the same as `true` (the default behavior).
example: true
event_capacity:
title: Event capacity settings
type: integer
description: The maximum number of participants that can attend the event.
example: 5
event_conferencing_request:
title: Event with conferencing
type: object
description: |-
An object that lets you automatically create a conference, or enter conferencing details manually.
You can't use `autocreate` and `details` in the same request. If you do, Nylas returns an error.
Nylas stores conference information in the event description. To remove conference details, set
`conferencing` to `{}` and remove the corresponding conference information from the description in
the same request.
oneOf:
- title: Auto-conferencing
type: object
description: Let Nylas autocreate the conference link.
properties:
provider:
type: string
description: The conferencing provider that Nylas uses to create the conference.
enum:
- Google Meet
- Zoom Meeting
- Microsoft Teams
autocreate:
type: object
description: |-
When you include `autocreate` in your request, Nylas automatically creates the conference
for the event and appends the conferencing details to the event description.
If the `provider` is `Zoom Meeting`, your Zoom OAuth app must include the following
[granular scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-granular/)
for Nylas to manage meetings on behalf of the user:
- `meeting:write:meeting` — required to **create** Zoom meetings.
- `meeting:update:meeting` — required to **update** Zoom meetings (for example, when event time or title changes).
- `meeting:delete:meeting` — required to **delete** Zoom meetings (when events are removed).
If any of these scopes are missing, the Zoom API rejects the request. After adding scopes
to your Zoom app, affected users must re-authenticate their grant so their access tokens
include the new scopes.
properties:
conf_grant_id:
type: string
description: |-
The grant ID of the account that hosts the conference. The user that belongs to this
grant acts as the conference host: they join the conference at the scheduled time and
admit other participants during the meeting.
Include `conf_grant_id` when the conferencing `provider` isn't available on the user's
own account — for example, when the `provider` is `Google Meet` but the user
authenticated with a Microsoft account (cross-provider autocreation). When the
`provider` is `Zoom Meeting`, `conf_grant_id` is always required.
conf_settings:
type: object
additionalProperties: true
description: |-
Optional provider-specific settings that Nylas passes through when it creates the
conference. For `Zoom Meeting`, each key is sent as a top-level parameter to
[Zoom's Create a Meeting API](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/#operation/meetingCreate)
— for example, `agenda`, `password`, or Zoom's own `settings` object. Nylas does _not_
validate these values. They can make your Zoom integration more accessible but
potentially less secure, so review your organization's security requirements.
- title: Google Meet
type: object
description: Manually attach Google Meet details to the event.
properties:
provider:
type: string
enum:
- Google Meet
description: The conferencing provider for the event.
details:
type: object
description: An object that contains Google Meet conferencing details.
required:
- url
properties:
url:
type: string
description: The URL for the Google Meet conference.
phone:
type: array
items:
type: string
description: |-
The phone number associated with the Google Meet conference. This array accepts only
one phone number.
pin:
type: string
description: The PIN associated with the Google Meet conference, if applicable.
- title: Zoom Meeting
type: object
description: Manually attach Zoom Meeting details to the event.
properties:
provider:
type: string
enum:
- Zoom Meeting
description: The conferencing provider for the event.
details:
type: object
description: An object that contains Zoom conferencing details.
required:
- url
properties:
url:
type: string
description: The URL for the Zoom conference.
meeting_code:
type:
- string
- 'null'
description: A unique ID associated with the Zoom conference.
password:
type:
- string
- 'null'
description: The password for the Zoom conference, if applicable.
- title: Microsoft Teams
type: object
description: Manually attach Microsoft Teams details to the event.
properties:
provider:
type: string
enum:
- Microsoft Teams
description: The conferencing provider for the event.
details:
type: object
description: An object that contains Microsoft Teams conferencing details.
required:
- url
properties:
url:
type: string
description: The URL for the Microsoft Teams conference.
- title: Teams for Business
type: object
description: Manually attach Teams for Business details to the event.
properties:
provider:
type: string
enum:
- Teams for Business
description: The conferencing provider for the event.
details:
type: object
description: An object that contains Microsoft Teams for Enterprise conferencing details.
required:
- url
properties:
url:
type: string
description: The URL for the Microsoft Teams for Enterprise conference.
- title: Skype for Consumer
type: object
description: Manually attach Skype for Consumer details to the event.
properties:
provider:
type: string
enum:
- Skype for Consumer
description: The conferencing provider for the event.
details:
type: object
description: An object that contains Skype for Consumer conferencing details.
required:
- url
properties:
url:
type: string
description: The URL for the Skype for Consumer conference.
- title: Skype for Business
type: object
description: Manually attach Skype for Business details to the event.
properties:
provider:
type: string
enum:
- Skype for Business
description: The conferencing provider for the event.
details:
type: object
description: An object that contains Skype for Business conferencing details.
required:
- url
properties:
url:
type: string
description: The URL for the Skype for Business conference.
- title: WebEx
type: object
description: Manually attach WebEx details to the event.
properties:
provider:
type: string
enum:
- WebEx
description: The conferencing provider for the event.
details:
type: object
description: An object that contains WebEx conferencing details.
required:
- url
properties:
url:
type: string
description: The URL for the WebEx conference.
password:
type: string
description: The password for the WebEx conference, if applicable.
pin:
type: string
description: The PIN for the WebEx conference, if applicable.
phone:
type: array
items:
type: string
description: The phone number associated with the WebEx conference.
- title: GoToMeeting
type: object
description: Manually attach GoToMeeting details to the event.
properties:
provider:
type: string
enum:
- GoToMeeting
description: The conferencing provider for the event.
details:
type: object
description: An object that contains GoToMeeting conferencing details.
required:
- url
properties:
url:
type: string
description: The URL for the GoToMeeting conference.
meeting_code:
type: string
description: A unique ID associated with the GoToMeeting conference.
password:
type: string
description: The password for the GoToMeeting conference, if applicable.
phone:
type: array
items:
type: string
description: The phone number associated with the GoToMeeting conference.
event_description:
title: Event description
type: string
description: |-
A brief description of the event (for example, its agenda). Nylas might return the description as
an HTML string, depending on how the provider formats it.
For Google accounts, this field accepts a maximum of 8,192 characters.
example: Come ready to talk philosophy!
event_hide_participants:
title: Hide participants on event
type: boolean
description: When `true`, hides the event's list of participants.
example: false
event_location:
title: Event location
type: string
description: The location of the event (for example, a physical address or the name of a meeting room).
maxLength: 255
example: Room 130
event_participants_create_update:
title: Create event with these participants
type: object
properties:
comment:
type: string
description: A note or comment about the participant (for example, their nickname). If the participant's email address is missing, this field is also missing.
email:
type: string
description: |-
The participant's email address.
For Microsoft Graph, this field can be missing.
example: dorothy@example.com
name:
type: string
description: The participant's full name.
example: Dorothy Vaughan
phone_number:
type: string
description: The participant's phone number. If the participant's email address is missing, this field is also missing.
required:
- email
event_reminders_create:
title: Create reminders list
type: object
description: A list of reminders to send for the event. If left empty or omitted, the event uses the provider defaults.
properties:
use_default:
type: boolean
title: Use Default
description: |-
When `true`, the event uses the calendar's default reminder settings.
- **Google**: Generates a `popup`-style reminder 10 minutes before the event begins.
- **Microsoft**: Generates a reminder 15 minutes before the event begins.
- **iCloud**: Does not generate a reminder.
- **EWS**: Generates a `display`-style reminder 15 minutes before the event begins.
overrides:
type: array
title: Overrides
description: |-
A list of reminders for the event to use when `use_default` is `false`. If this field is empty
or omitted, and `use_default` is `false`, the event does not send reminders. If `true`, Nylas
generates both the default event reminder and any reminders in the `overrides` list.
You cannot set reminder overrides if `use_default` is `true`.
For Microsoft Graph, EWS, and iCloud, you can set only one reminder per event.
items:
type: object
properties:
reminder_minutes:
type: integer
example: 20
description: The number of minutes before the event start time when a user wants to receive a reminder for this event.
reminder_method:
type: string
description: |-
(Google and iCloud only) The method used to notify the user about the event, with separate
options and default settings for each provider.
- **Google**:
- Default: `popup`
- Options: `popup`, `email`
- **iCloud**:
- Default: `display`
- Options: `display`, `sound`
enum:
- popup
- email
- display
- sound
example: popup
event_title:
title: Event title
type: string
description: The name of the event.
maxLength: 1024
example: Annual Philosophy Club Meeting
event_time:
title: Time
type: object
description: A specific point in time (for example, the start time of an event).
properties:
time:
type: integer
description: The time that the meeting occurs, in seconds using the Unix timestamp format.
example: 1633698000
timezone:
type: string
description: |-
The timezone of the event as an
[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string. If
populated, Nylas reads the value of `time` with the provided timezone.
example: America/New_York
event_when:
title: When
type: object
description: |-
An object that represents the time and duration of an event.
You can format `when` as one of four sub-objects: `time`, `timespan`, `date`, or `datespan`. These
sub-objects allow you to capture and represent specific points in time.
`time` and `timespan` objects include optional timezone support.
oneOf:
- $ref: '#/components/schemas/event_time'
- $ref: '#/components/schemas/event_timespan'
- $ref: '#/components/schemas/event_date'
- $ref: '#/components/schemas/event_datespan'
event_create:
title: create_event
type: object
required:
- when
properties:
busy:
$ref: '#/components/schemas/event_busy'
capacity:
$ref: '#/components/schemas/event_capacity'
conferencing:
$ref: '#/components/schemas/event_conferencing_request'
description:
$ref: '#/components/schemas/event_description'
hide_participants:
$ref: '#/components/schemas/event_hide_participants'
location:
$ref: '#/components/schemas/event_location'
metadata:
$ref: '#/components/schemas/metadata'
notetaker:
$ref: '#/components/schemas/event_sync'
participants:
type: array
items:
$ref: '#/components/schemas/event_participants_create_update'
resources:
type: array
items:
$ref: '#/components/schemas/event_resources'
recurrence:
$ref: '#/components/schemas/event_recurrence'
reminders:
$ref: '#/components/schemas/event_reminders_create'
title:
$ref: '#/components/schemas/event_title'
visibility:
$ref: '#/components/schemas/event_visibility'
when:
$ref: '#/components/schemas/event_when'
event:
allOf:
- $ref: '#/components/schemas/event_common'
event_send_rsvp:
title: Participant RSVP status
type: object
properties:
status:
type: string
description: A participant's RSVP status for the event.
example: maybe
enum:
- 'yes'
- 'no'
- maybe
resource_building:
title: Resource Building
type: string
description: The name of the building where the room is located.
example: Building 1
resource_capacity:
title: Resource Capacity
type: integer
description: The number of people the room can seat.
example: 5
resource_email:
title: Resource Email
type: string
description: The email address associated with the room resource.
example: conference-room@resources.google.com
resource_floor_name:
title: Resource Floor Name
type: string
description: The name of the floor where the room is located.
example: 1st Floor
resource_floor_number:
title: Resource Floor Number
type: integer
description: The floor number where the room is located.
example: 1
resource_floor_section:
title: Resource Floor Section
type: string
description: The section of the floor where the room is located.
example: A
resource:
title: Room Resource
type: object
properties:
building:
$ref: '#/components/schemas/resource_building'
capacity:
$ref: '#/components/schemas/resource_capacity'
email:
$ref: '#/components/schemas/resource_email'
floor_name:
$ref: '#/components/schemas/resource_floor_name'
floor_number:
$ref: '#/components/schemas/resource_floor_number'
floor_section:
$ref: '#/components/schemas/resource_floor_section'
grant_id:
$ref: '#/components/schemas/grant_id'
object:
type: string
description: The object type (in this case, `room_resource`).
example: room_resource
contact_birthday:
title: Contact Birthday
type: string
description: The contact's birthday in [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates).
example: '1980-12-31'
contact_company_name:
title: Contact Company Name
type: string
description: The name of the company that the contact is affiliated with (for example, their workplace).
example: Nylas
contact_email:
title: Contact email
type: object
required:
- email
description: |-
An array of the contact's email addresses. Different providers may have different limits on the
number of email addresses.
- IMAP/iCloud/Yahoo: at most one email address per contact.
- Microsoft/EWS: at most three email addresses per contact.
properties:
email:
type: string
description: The contact's email address.
maxLength: 255
example: leyah@example.com
type:
type: string
description: (Google, IMAP, and iCloud only) The email address type.
enum:
- work
- home
- other
example: work
contact_given_name:
title: Contact Given Name
type: string
description: The contact's given name.
example: John
contact_group_id:
title: Contact Group ID
type: object
required:
- id
properties:
id:
$ref: '#/components/schemas/id'
example:
id: 5d3qmne77v32r8l4phyuksl2x
contact_im_address:
title: Contact IM address
type: object
required:
- im_address
description: |-
An array of the contact's instant messaging (IM) addresses. Different providers may have different
limits on the number of IM addresses.
- IMAP/iCloud/Yahoo: at most one IM address per contact.
- Microsoft/EWS: at most three IM addresses per contact.
properties:
im_address:
type: string
description: The contact's IM address.
maxLength: 255
example: myJabberAddress
type:
type: string
description: The protocol for the IM address.
example: jabber
contact_job_title:
title: Contact Job Title
type: string
description: The contact's occupation or job title.
example: Software Engineer
contact_manager_name:
title: Contact Manager Name
type: string
description: The name of the contact's manager.
example: Bill
contact_middle_name:
title: Contact Middle Name
type: string
description: The contact's middle name.
example: Jacob
contact_nickname:
title: Contact Nickname
type: string
description: A custom nickname for the contact.
example: JD
contact_notes:
title: Contact Notes
type: string
description: Notes about with the contact (for example, their favorite food).
example: Loves Ramen
contact_office_location:
title: Contact Office Location
type: string
description: The location of the office where the contact works.
example: 123 Main Street
contact_phone_number:
title: Contact phone number
type: object
required:
- number
description: |-
An array of phone numbers associated with the contact. Different providers may have different limits
on the number of phone numbers.
- IMAP/iCloud/Yahoo: at most one phone number per contact.
- Microsoft: at most two home phone numbers, two work phone numbers, and one mobile phone number.
- EWS: at most two home phone numbers, two work phone numbers, one mobile phone number, and one
other phone number.
properties:
number:
type: string
description: |-
The contact's phone number, including its
[country code](https://www.itu.int/oth/T0202.aspx?parent=T0202).
example: +1-555-555-5555
type:
type: string
description: |-
The phone number type. `mobile` is supported for Google and Microsoft Graph only. `other` is
supported for Google and EWS only.
enum:
- work
- home
- mobile
- other
example: work
contact_physical_address:
title: Contact physical address
type: object
required:
- type
description: |-
An array of physical addresses associated with the contact. Different providers may have different
limits on the number of physical addresses.
- IMAP/iCloud/Yahoo: at most one physical address per contact.
- Microsoft/EWS: at most one physical address per contact per type.
properties:
city:
type: string
description: The town or city in which the contact is located.
example: San Francisco
country:
type: string
description: The country in which the contact is located.
example: USA
postal_code:
type: string
description: The postal code of a location associated with the contact.
example: '94107'
state:
type: string
description: The state or province in which the contact is located.
example: CA
street_address:
type: string
description: The street address of a location associated with the contact (for example, their work).
example: 123 Main Street
type:
type: string
description: The physical address type.
enum:
- work
- home
- other
example: work
contact_picture_url:
title: Contact Picture URL
type: string
description: A URL that links to the contact's picture.
example: https://example.com/picture.jpg
contact_source:
title: Contact source
type: string
description: |-
The source of the contact. For iCloud and IMAP grants, the source is `inbox` if the contact is
parsed from a message. If the contact is created or updated using the Nylas API, its source is
`address_book`.
enum:
- address_book
- domain
- inbox
example: address_book
contact_suffix:
title: Contact Suffix
type: string
description: (Not supported for EWS) The suffix of a contact's name, if applicable.
example: Jr.
contact_surname:
title: Contact Surname
type: string
description: The contact's surname.
example: Doe
contact_web_page:
title: Contact web page
type: object
required:
- url
properties:
url:
type: string
description: A URL that links to the contact's website.
example: https://www.example.com/leyah-miller
type:
type: string
description: The website type.
enum:
- work
- home
- other
example: work
contact:
title: Contact
type: object
properties:
birthday:
$ref: '#/components/schemas/contact_birthday'
company_name:
$ref: '#/components/schemas/contact_company_name'
emails:
type:
- array
- 'null'
description: The contact's email addresses. May be `null` if the contact has no email addresses. Treat `null` the same as an empty array.
items:
$ref: '#/components/schemas/contact_email'
given_name:
$ref: '#/components/schemas/contact_given_name'
grant_id:
$ref: '#/components/schemas/grant_id'
groups:
type:
- array
- 'null'
description: The contact's group memberships. May be `null` if the contact has no group memberships. Treat `null` the same as an empty array.
items:
$ref: '#/components/schemas/contact_group_id'
id:
$ref: '#/components/schemas/id'
im_addresses:
type:
- array
- 'null'
description: The contact's IM addresses. May be `null` if the contact has no IM addresses. Treat `null` the same as an empty array.
items:
$ref: '#/components/schemas/contact_im_address'
job_title:
$ref: '#/components/schemas/contact_job_title'
manager_name:
$ref: '#/components/schemas/contact_manager_name'
middle_name:
$ref: '#/components/schemas/contact_middle_name'
nickname:
$ref: '#/components/schemas/contact_nickname'
notes:
$ref: '#/components/schemas/contact_notes'
object:
type: string
description: The response object type.
example: contact
office_location:
$ref: '#/components/schemas/contact_office_location'
phone_numbers:
type:
- array
- 'null'
description: The contact's phone numbers. May be `null` if the contact has no phone numbers. Treat `null` the same as an empty array.
items:
$ref: '#/components/schemas/contact_phone_number'
physical_addresses:
type:
- array
- 'null'
description: The contact's physical addresses. May be `null` if the contact has no physical addresses. Treat `null` the same as an empty array.
items:
$ref: '#/components/schemas/contact_physical_address'
picture_url:
$ref: '#/components/schemas/contact_picture_url'
source:
$ref: '#/components/schemas/contact_source'
suffix:
$ref: '#/components/schemas/contact_suffix'
surname:
$ref: '#/components/schemas/contact_surname'
web_pages:
type:
- array
- 'null'
description: The contact's web pages. May be `null` if the contact has no web pages. Treat `null` the same as an empty array.
items:
$ref: '#/components/schemas/contact_web_page'
contact_picture:
title: Contact Picture
type: string
description: The contact's picture, represented as a Base64-encoded string.
example: /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHR...
contact_with_picture:
title: Contact With Picture
type: object
allOf:
- $ref: '#/components/schemas/contact'
- properties:
picture:
$ref: '#/components/schemas/contact_picture'
contact_group:
title: Contact Group
type: object
properties:
grant_id:
$ref: '#/components/schemas/grant_id'
group_type:
type: string
description: The Contact Group type.
enum:
- system
- user
- other
example: system
id:
$ref: '#/components/schemas/id'
name:
type: string
description: The Contact Group display name.
example: starred
object:
type: string
description: The response object type.
example: contact_group
path:
type: string
description: The Contact Group's path.
example: parentId/starred
notetaker:
type: object
properties:
grant_id:
type: string
description: The ID of the grant associated with this Notetaker bot.
example: d4e78fca-2a90-4b6e-91c3-a7f2bcb0d498
id:
type: string
description: The Notetaker ID.
example: 71c807752c744ad0902f64d43e6cc399
join_time:
type: integer
description: When Notetaker joined the meeting, in seconds using the Unix timestamp format.
example: 1732657774
meeting_link:
type: string
description: The meeting link.
example: https://meet.google.com/xyz-abcd-ijk
meeting_provider:
type: string
description: The meeting provider.
enum:
- Google Meet
- Zoom Meeting
- Microsoft Teams
example: Google Meet
meeting_settings:
$ref: '#/components/schemas/meeting_settings'
name:
type: string
description: The display name for the Notetaker bot.
default: Nylas Notetaker
example: Nylas Notetaker
object:
type: string
description: The type of object.
example: notetaker
state:
type: string
description: The current state of the Notetaker bot.
enum:
- scheduled
- connecting
- waiting_for_entry
- attending
- disconnected
- worker_finished
- processing
- available
- media_error
- media_deleted
- failed_entry
example: scheduled
status:
type: string
description: The current status of the Notetaker bot.
example: scheduled
notetakers:
type: object
required:
- meeting_link
properties:
join_time:
type: integer
description: |-
When the Notetaker bot should join the meeting, in seconds using the Unix timestamp format. If
you don't specify a time, Notetaker joins the meeting immediately.
If you provide a time that's in the past, Nylas returns an error.
example: 1732657774
meeting_link:
type: string
description: A meeting invitation link that Notetaker uses to join the meeting.
example: https://meet.google.com/xyz-abcd-ijk
meeting_settings:
$ref: '#/components/schemas/meeting_settings'
name:
type: string
description: The display name for the Notetaker bot.
default: Nylas Notetaker
example: Nylas Notetaker
notetaker_history_event:
type: object
description: A history event that records a change to a Notetaker bot.
properties:
created_at:
type: integer
description: When this history event was recorded, in seconds using the Unix timestamp format.
example: 1700000000
event_type:
type: string
description: The type of history event.
enum:
- notetaker.created
- notetaker.updated
- notetaker.meeting_state
- notetaker.media
- notetaker.deleted
example: notetaker.media
data:
allOf:
- $ref: '#/components/schemas/notetaker'
- type: object
description: The Notetaker bot payload at the time of the event.
properties:
meeting_state:
type: string
description: |
Additional information about the Notetaker bot's meeting state for `notetaker.meeting_state`
events. The value depends on the current `state`:
When `state` is `connecting`: `waiting_for_entry`.
When `state` is `attending`: `recording_active`.
When `state` is `disconnected`: `meeting_ended`, `kicked`, `no_activity`, `no_participants`, `api_request`, `network_error`, `cancelled`, `unknown`.
When `state` is `failed_entry`: `error`, `internal_error`, `bad_meeting_code`, `bad_meeting_link`, `sign_in_required`, `entry_denied`, `no_response`, `cannot_join`, `meeting_capacity_reached`, `admission_timeout`, `network_error`, `cancelled`.
When `state` is `worker_finished`: `worker_finished`.
example: recording_active
media:
type: object
description: Media files generated by the Notetaker bot for `notetaker.media` events.
properties:
recording:
type: string
description: A URL to the meeting recording file.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/recording.mp4
recording_duration:
type: string
description: The duration of the recording, in seconds.
example: '3600'
transcript:
type: string
description: A URL to the meeting transcript file.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/transcript.json
thumbnail:
type: string
description: A URL to a thumbnail image from the recording.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/thumbnail.jpg
summary:
type: string
description: A URL to a summary file generated from the meeting.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/summary.txt
action_items:
type: string
description: A URL to an action items file generated from the meeting.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/action_items.json
event:
type: object
description: Information about the calendar event associated with this Notetaker bot, if applicable.
properties:
event_id:
type: string
description: The associated Nylas event ID.
example: 5d3qmne77v32r8l4phyuksl2x
ical_uid:
type: string
description: The iCalendar UID of the event.
example: 040000008200E00074C5B7101A82E00800000000A0A0A0A0A0A0A0A0A0A0000000000000000100000003F21F1BFC9E2ED4FB0EC0A6C4C86A8A9
master_event_id:
type: string
description: The master event ID for recurring events, if applicable.
example: 7d93zl2palhxqdy6e5qinsakt
standalone_notetaker:
type: object
properties:
id:
type: string
description: The Notetaker ID.
example: 71c807752c744ad0902f64d43e6cc399
join_time:
type: integer
description: When Notetaker joined the meeting, in seconds using the Unix timestamp format.
example: 1732657774
meeting_link:
type: string
description: The meeting link.
example: https://meet.google.com/xyz-abcd-ijk
meeting_provider:
type: string
description: The meeting provider.
enum:
- Google Meet
- Zoom Meeting
- Microsoft Teams
example: Google Meet
meeting_settings:
$ref: '#/components/schemas/meeting_settings'
name:
type: string
description: The display name for the Notetaker bot.
default: Nylas Notetaker
example: Nylas Notetaker
object:
type: string
description: The type of object.
example: notetaker
state:
type: string
description: The current state of the Notetaker bot.
enum:
- scheduled
- connecting
- waiting_for_entry
- attending
- disconnected
- worker_finished
- processing
- available
- media_error
- media_deleted
- failed_entry
example: scheduled
status:
type: string
description: The current status of the Notetaker bot.
example: scheduled
standalone_notetaker_history_event:
type: object
description: A history event that records a change to a Notetaker bot.
properties:
created_at:
type: integer
description: When this history event was recorded, in seconds using the Unix timestamp format.
example: 1700000000
event_type:
type: string
description: The type of history event.
enum:
- notetaker.created
- notetaker.updated
- notetaker.meeting_state
- notetaker.media
- notetaker.deleted
example: notetaker.media
data:
allOf:
- $ref: '#/components/schemas/standalone_notetaker'
- type: object
description: The Notetaker bot payload at the time of the event.
properties:
meeting_state:
type: string
description: |
Additional information about the Notetaker bot's meeting state for `notetaker.meeting_state`
events. The value depends on the current `state`:
When `state` is `connecting`: `waiting_for_entry`.
When `state` is `attending`: `recording_active`.
When `state` is `disconnected`: `meeting_ended`, `kicked`, `no_activity`, `no_participants`, `api_request`, `network_error`, `cancelled`, `unknown`.
When `state` is `failed_entry`: `error`, `internal_error`, `bad_meeting_code`, `bad_meeting_link`, `sign_in_required`, `entry_denied`, `no_response`, `cannot_join`, `meeting_capacity_reached`, `admission_timeout`, `network_error`, `cancelled`.
When `state` is `worker_finished`: `worker_finished`.
example: recording_active
media:
type: object
description: Media files generated by the Notetaker bot for `notetaker.media` events.
properties:
recording:
type: string
description: A URL to the meeting recording file.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/recording.mp4
recording_duration:
type: string
description: The duration of the recording, in seconds.
example: '3600'
transcript:
type: string
description: A URL to the meeting transcript file.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/transcript.json
thumbnail:
type: string
description: A URL to a thumbnail image from the recording.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/thumbnail.jpg
summary:
type: string
description: A URL to a summary file generated from the meeting.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/summary.txt
action_items:
type: string
description: A URL to an action items file generated from the meeting.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/action_items.json
event:
type: object
description: Information about the calendar event associated with this Notetaker bot, if applicable.
properties:
event_id:
type: string
description: The associated Nylas event ID.
example: 5d3qmne77v32r8l4phyuksl2x
ical_uid:
type: string
description: The iCalendar UID of the event.
example: 040000008200E00074C5B7101A82E00800000000A0A0A0A0A0A0A0A0A0A0000000000000000100000003F21F1BFC9E2ED4FB0EC0A6C4C86A8A9
master_event_id:
type: string
description: The master event ID for recurring events, if applicable.
example: 7d93zl2palhxqdy6e5qinsakt
template:
type: object
description: A custom message template.
required:
- body
- created_at
- engine
- id
- name
- object
- subject
- updated_at
properties:
app_id:
type:
- string
- 'null'
description: |-
The ID of the Nylas application associated with the template. Returned only if the template is
configured at the application level.
example: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
body:
type: string
description: The body content of the template, in HTML format.
example: <p>Hello {{user.name}}, your booking has been confirmed.</p>
created_at:
type: integer
description: When the template was created, in seconds using the Unix timestamp format.
example: 1640995200
engine:
type: string
enum:
- handlebars
- mustache
- nunjucks
- twig
description: The templating engine.
example: mustache
grant_id:
type:
- string
- 'null'
description: |-
The ID of the grant associated with the template. Returned only if the template is configured
at the grant level.
example: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
name:
type: string
description: The name of the template.
example: Booking confirmed message
object:
type: string
description: The object type identifier.
default: template
example: template
subject:
type: string
description: The subject line of the template.
example: '{{user.name}}, your booking is confirmed!'
updated_at:
type: integer
description: When the template was last updated, in seconds using the Unix timestamp format.
example: 1640995200
workflow:
type: object
description: A custom workflow that sends messages from a template when certain events are triggered.
required:
- date_created
- delay
- id
- is_enabled
- name
- template_id
- trigger_event
properties:
app_id:
type:
- string
- 'null'
description: |-
The ID of the Nylas application associated with the workflow. Returned only if the
workflow is configured at the application level.
example: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
date_created:
type: integer
description: When the workflow was created, in seconds using the Unix timestamp format.
example: 1756477389
delay:
type: integer
description: |-
The number of minutes between a `trigger_event` being met and the workflow sending
a message.
example: 5
grant_id:
type:
- string
- 'null'
description: |-
The ID of the grant associated with the workflow. Returned only if the workflow is
configured at the grant level.
example: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
id:
type: string
description: The ID of the workflow.
example: b79c82b2-a51b-4c54-8469-28006a43551a
is_enabled:
type: boolean
description: When `true`, indicates that the workflow is enabled.
example: true
name:
type: string
description: The name of the workflow.
example: New booking confirmation workflow
template_id:
type: string
description: The ID of the email template the workflow uses.
example: 14c00cc8-648c-4381-ad10-52641d9bac8e
trigger_event:
type: string
enum:
- booking.cancelled
- booking.created
- booking.pending
- booking.reminder
- booking.rescheduled
description: The event which triggers the workflow.
example: booking.created
from:
type:
- object
- 'null'
description: Details of the sender if the workflow uses transactional send.
properties:
email:
type: string
description: The email address of the sender.
example: support@example.com
name:
type: string
description: The name of the sender.
example: Support
configuration_appearance:
title: appearance
type: object
description: Appearance settings definitions for the Scheduling Page.
properties:
your-key:
type: string
description: A key-value pair. For pre-defined keys for hosted Scheduling Pages, see [Styling options for hosted Scheduling Pages](/docs/v3/scheduler/customize-scheduler/#styling-options-for-hosted-scheduling-pages).
maxLength: 550
configuration_availability_open_hours:
description: Open hours settings for a participant.
type: object
title: Open Hours
examples: []
properties:
days:
type: array
description: The days of the week that the open hour settings are applied to. Sunday corresponds to `0`, and Saturday corresponds to `6`.
items:
type: integer
example:
- 0
- 1
- 2
start:
type: string
minLength: 1
description: The start time in 24-hour time format. Single-digit hours doesn't have a leading zero. The earliest start time is `0:00`, and the latest start time is `23:49`.
example: '10:00'
end:
type: string
minLength: 1
description: The end time in a 24-hour time format. Single-digit hours doesn't have a leading zero.
example: '14:00'
timezone:
type: string
minLength: 1
description: |-
The timezone for this open-hours block, as an [IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string.
For participant `open_hours`, this value applies only to the open-hours block where you define it and overrides the participant's `timezone`. If you omit it, Scheduler uses the participant's `timezone`, then `event_booking.timezone`.
For `default_open_hours` in Scheduler configurations, set `event_booking.timezone` to control the timezone that Scheduler uses when evaluating default open hours.
example: America/Chicago
exdates:
type: array
description: A list of dates that are excluded from the open hours. Dates should be formatted as `YYYY-MM-DD`.
items:
type: string
example:
- '2006-01-18'
configuration_availability_rules:
description: Availability rules for the scheduling configuration. These rules define how Nylas calculates availability for all participants.
type: object
properties:
availability_method:
description: |-
The method that Nylas uses to calculate availability for all participants. For one-on-one
meetings, the `availability_method` is always `collective`.
The round-robin methods, `max-fairness` and `max-availability`, don't support
[Agent Account](/docs/v3/scheduler/agent-accounts/) participants. Use connected grants for
round-robin pools.
type: string
default: collective
enum:
- collective
- max-fairness
- max-availability
buffer:
type: object
description: The amount of buffer time to add around existing meetings, in minutes. For example, if an account has a meeting scheduled from 10–11a.m., and you set a buffer of 30 minutes, Nylas treats 9:30–11:30a.m. as busy.
$ref: '#/components/schemas/availability_buffer'
default_open_hours:
type: array
description: A default set of open hours to apply to participants that don't define participant-level `open_hours`. You can overwrite these open hours for individual participants by specifying `open_hours` on the participant object. In Scheduler configurations, set `event_booking.timezone` to control the timezone used when Scheduler evaluates default open hours.
items:
$ref: '#/components/schemas/configuration_availability_open_hours'
default_specific_time_availability:
type: array
description: |-
Default specific date and time availability that applies to ALL participants in this configuration.
These are merged with participant-specific entries, with participant entries taking precedence
for the same date. Use this to define organization-wide special hours (e.g., holidays, events).
items:
type: object
required:
- date
- start
- end
properties:
date:
type: string
description: The date in YYYY-MM-DD format.
example: '2025-12-25'
start:
type: string
description: |-
The start time in HH:MM format (24-hour clock).
Use "00:00" with end "00:00" to mark the date as closed/unavailable.
example: '09:00'
end:
type: string
description: The end time in HH:MM format (24-hour clock).
example: '13:00'
timezone:
type: string
description: |-
The timezone for this specific date entry (e.g., "America/New_York").
Required when using default_specific_time_availability to ensure proper timezone conversion
across participants. When specified, `event_booking.timezone` must also be set.
example: America/Toronto
only_specific_time_availability:
type: boolean
description: |-
When `true`, ALL participants will ONLY be available at times defined in `default_specific_time_availability`
and their individual `specific_time_availability` entries. Regular `open_hours` and `default_open_hours`
are completely ignored.
This is useful for:
- Temporary availability windows (e.g., hiring events, special booking periods)
- Disabling all availability by setting to `true` with no specific dates defined
**Note**: When set at the config level, individual participants cannot override this to `false`.
default: false
example: true
configuration_availability:
type: object
description: The rules that determine the available time slots for the event.
required:
- duration_minutes
properties:
duration_minutes:
type: integer
description: The total number of minutes the event should last.
interval_minutes:
type: integer
description: The interval between meetings. Nylas checks from the nearest interval of the passed `start_time`. For example, you schedule 30-minute meetings (`duration_minutes`) with 15 minutes between them (`interval_minutes`). If you have a meeting starting at 9:59, the API returns times starting at 10:00 (10:00-10:30, 10:15-10:45).
round_to:
type: integer
default: 15
description: Nylas rounds each time slot to the nearest `round_to` value. For example, if a time slot starts at 9:05a.m. and `round_to` is set to `15`, Nylas rounds it to 9:15a.m. Must be a multiple of 5 minutes.
availability_rules:
$ref: '#/components/schemas/configuration_availability_rules'
configuration_event_booking:
type: object
required:
- title
properties:
booking_type:
type: string
description: |-
The booking type. If set to `booking`, Scheduler follows the
[standard booking flow](/docs/v3/scheduler/customize-booking-flows/).
If set to `organizer-confirmation`, Scheduler creates an event marked "Pending" in the organizer's
calendar and sends a confirmation request email to the organizer. The confirmation request email
includes a link to a page where the organizer can confirm or cancel the booking.
enum:
- booking
- organizer-confirmation
default: booking
example: booking
conferencing:
$ref: '#/components/schemas/event_conferencing_request'
description:
type: string
description: The description of the event.
example: Come ready to talk philosophy!
disable_emails:
type:
- boolean
- 'null'
description: |-
When `true`, Nylas doesn't send email notifications when an event is booked, cancelled, or
rescheduled. When `null`, the default behavior applies (emails are sent).
default: false
example: false
hide_participants:
type:
- boolean
- 'null'
description: When `true`, Nylas creates the event with `hide_participants=true`, so the host can see who's on the event but the guests cannot. When `null`, the default behavior applies (participants are visible).
default: false
example: false
location:
type: string
description: The location of the event.
example: Central Library, room 203
notify_participants:
type:
- boolean
- 'null'
description: |-
When `true`, the calendar provider sends notifications to participants when the
event is created, updated, or deleted. Microsoft grants ignore this flag and
always notify participants. This field may be `null` if not explicitly set on
the configuration; treat `null` the same as `false` (the default behavior).
default: false
example: true
reminders:
type: array
required:
- minutes_before_event
- type
items:
type: object
properties:
email_subject:
type: string
description: (Email reminders only) The subject line of the email reminder.
example: 'Reminder: Annual Philosophy Club Meeting'
minutes_before_event:
type: integer
description: The number of minutes before the event to send the reminder.
minimum: 1
example: 30
recipient:
type: string
description: (Email reminders only) Who should receive the reminder.
enum:
- all
- host
- guest
default: all
example: host
type:
type: string
description: The reminder type.
enum:
- email
- webhook
example: email
timezone:
type: string
description: |-
The timezone Nylas uses to display times in confirmation messages and reminders. This must be
an [IANA-formatted string](https://en.wikipedia.org/wiki/Tz_database).
minLength: 1
example: America/Chicago
title:
type: string
description: The title of the event.
example: Annual Philosophy Club Meeting
configuration_participants_availability:
description: The availability data for the participant. If omitted, the participant is considered to be available at all times. At least one participant must have availability data.
type: object
required:
- calendar_ids
properties:
calendar_ids:
type: array
description: |-
A list of calendar IDs associated with the participant's email address. These calendars are
used to check the participant's availability.
For an [Agent Account](/docs/v3/scheduler/agent-accounts/) participant, set this to
`["primary"]`. Scheduler reads busy time from an Agent Account's primary calendar only.
items:
type: string
open_hours:
type: array
description: An array of objects for the participant's open hours. Nylas searches for free time slots within these open hours.
items:
$ref: '#/components/schemas/configuration_availability_open_hours'
configuration_participants_booking:
description: The booking data for the participant. If omitted, the participant is not included in the booked event. At least one participant must have booking data.
type: object
required:
- calendar_id
properties:
calendar_id:
type: string
description: |-
The calendar ID that the event is created in.
For an [Agent Account](/docs/v3/scheduler/agent-accounts/) participant, set this to
`primary`. Scheduler creates booking events on an Agent Account's primary calendar only.
configuration_participants_specific_time_availability:
description: |-
A specific date and time range when the participant is available.
Use "00:00" for both start and end to explicitly mark a date as unavailable.
type: array
items:
type: object
required:
- date
- start
- end
properties:
date:
type: string
description: The date in YYYY-MM-DD format.
example: '2025-08-21'
start:
type: string
description: |-
The start time in HH:MM format (24-hour clock).
Use "00:00" with end "00:00" to explicitly mark this date as unavailable.
example: '09:00'
end:
type: string
description: The end time in HH:MM format (24-hour clock).
example: '17:00'
timezone:
type: string
description: |-
The timezone for this specific date (e.g., "America/New_York").
Optional for participant-level entries. Uses the participant's timezone if not specified.
example: America/Toronto
configuration_participants:
type: object
description: List of participants for the scheduling Configuration.
required:
- availability
- booking
- email
properties:
availability:
$ref: '#/components/schemas/configuration_participants_availability'
booking:
$ref: '#/components/schemas/configuration_participants_booking'
email:
type: string
description: |-
The participant's email address.
If the participant provides an `availability` or `booking` block, this email address must be
associated with a valid Nylas grant, or the request fails. Participants supplied by email only
(no `availability` or `booking` block) don't require a grant. They're treated as notification-only
invitees: they still receive scheduling emails, but they don't affect availability or free-busy
calculation and can't be selected as a round-robin host.
example: nyla@example.com
grant_id:
type: string
description: The participant's grant ID.
is_organizer:
type: boolean
description: |-
When `true`, indicates that the participant is the organizer of the event.
For non-round-robin meetings, one of the participants must be specified as the organizer. For
round-robin meetings, remove the `is_organizer` key/value pair or set `is_organizer` to `false`
for all participants.
default: false
example: false
name:
type: string
description: The participant's name.
example: Nyla
specific_time_availability:
$ref: '#/components/schemas/configuration_participants_specific_time_availability'
only_specific_time_availability:
type: boolean
description: |-
When `true`, this participant will ONLY be available at times defined in their
`specific_time_availability` entries. Their regular `open_hours` are ignored.
If the config-level `availability_rules.only_specific_time_availability` is `true`,
this participant-level setting cannot override it to `false`.
Setting to `true` with an empty `specific_time_availability` array results in
zero availability for this participant (useful for temporarily disabling someone).
default: false
example: true
timezone:
type: string
description: |-
The timezone in which the participant is located, as an
[IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string. Nylas uses this when
calculating the participant's open hours, and in email notifications.
If a participant `open_hours` block includes its own `timezone`, the open-hours timezone
overrides this participant timezone for that block. If participant `open_hours` doesn't include
a `timezone`, Scheduler uses this participant timezone, then `event_booking.timezone`.
example: America/Toronto
configuration_scheduler_additional_fields:
description: The definitions for additional fields to be displayed in the Scheduler UI. Guest will see the additional fields on the Scheduling Page when they book an event.
type: object
required:
- label
- type
- required
properties:
label:
type: string
description: The text label to be displayed in the Scheduler UI.
type:
type: string
description: The field type. If set to `metadata`, the field does not appear on email notifications and booking forms.
enum:
- text
- multi_line_text
- email
- phone_number
- dropdown
- date
- checkbox
- radio_button
- metadata
required:
type: boolean
description: Whether the field is required to be filled out by the guest when booking an event.
default:
type: string
description: |-
The default value for the field.
- For the `metadata` type, this field stores the default metadata value.
- For other types, this field sets the default value in the form, which is pre-filled when a guest books an event.
pattern:
type: string
description: A regular expression pattern that the value of the field must match.
order:
type: integer
description: The order in which the field will be displayed in the Scheduler UI. Fields with lower order values will be displayed first.
options:
type: array
description: A list of options for the `dropdown` or `radio_button` types. This field is required for the `dropdown` and `radio_button` types.
items:
type: string
configuration_scheduler_email_template_booking_confirmed:
description: Configurable settings specifically for booking confirmed emails.
type: object
properties:
title:
type: string
description: The title to replace the default 'Booking Confirmed' title. This doesn't change the email subject line. Only visible in emails sent to guests.
body:
type: string
description: The additional body to be appended after the default body. Only visible in emails sent to guests.
configuration_scheduler_email_template:
type: object
description: Configurable settings for booking emails.
properties:
booking_confirmed:
$ref: '#/components/schemas/configuration_scheduler_email_template_booking_confirmed'
logo:
type: string
description: |-
The URL of a custom logo that is displayed at the top of the booking email. Replaces the default
Nylas logo. The URL needs to be publicly accessible.
show_nylas_branding:
type: boolean
default: true
description: When `true`, displays Nylas branding in the booking email.
configuration_scheduler:
type: object
properties:
additional_fields:
type: object
additionalProperties:
$ref: '#/components/schemas/configuration_scheduler_additional_fields'
available_days_in_future:
type: integer
description: The number of days in the future that Scheduler is available for scheduling events.
default: 30
min_booking_notice:
type:
- integer
- 'null'
description: The minimum number of minutes in the future that a user can make a new booking. This field may be `null` if not explicitly set on the configuration; treat `null` the same as `60` (the default behavior).
default: 60
min_cancellation_notice:
type: integer
description: The minimum number of minutes before a booking can be cancelled.
default: 0
cancellation_policy:
type: string
description: A message about the cancellation policy to display to users when booking an event.
rescheduling_url:
type: string
description: The URL used to reschedule bookings. This URL is included in confirmation messages.
cancellation_url:
type: string
description: The URL used to cancel bookings. This URL is included in confirmation messages.
organizer_confirmation_url:
type: string
description: |-
The URL used to confirm or cancel pending bookings. This URL is included in booking request
messages.
confirmation_redirect_url:
type: string
description: The URL that Nylas redirects the user to when the booking is confirmed.
hide_rescheduling_options:
type: boolean
description: If `true`, the option to reschedule an event is hidden in booking confirmations and email notifications.
default: false
hide_cancellation_options:
type: boolean
description: If `true`, the option to cancel an event is hidden in booking confirmations and email notifications.
default: false
hide_additional_guests:
type: boolean
description: Whether to hide the **Additional guests** field on the Scheduling Page. If `true`, guests cannot invite additional guests to the event.
default: false
notetaker_settings:
type: object
description: |-
Settings for automatically adding a Notetaker bot to bookings created with this configuration.
When enabled, Notetaker joins the meeting to record, transcribe, and optionally generate
summaries and action items. Requires `event_booking.conferencing` to be configured.
properties:
enabled:
type: boolean
description: |-
When `true`, automatically creates a Notetaker bot for bookings made with this configuration.
The bot joins the meeting at the scheduled time to record and transcribe.
default: false
example: true
show_ui_consent_message:
type: boolean
description: |-
When `true`, displays a consent message in the Scheduler UI informing guests that the
meeting will be recorded.
default: true
example: true
notetaker_name:
type: string
description: |-
The display name for the Notetaker bot that joins the meeting.
Maximum 255 characters.
default: Nylas Notetaker
example: Sales Recording Bot
meeting_settings:
$ref: '#/components/schemas/meeting_settings'
email_template:
$ref: '#/components/schemas/configuration_scheduler_email_template'
configuration:
type: object
required:
- participants
- availability
- event_booking
properties:
appearance:
description: |-
An object that defines the appearance settings for the Scheduling Page. This field
may be `null` if no appearance customization has been set.
anyOf:
- $ref: '#/components/schemas/configuration_appearance'
- type: 'null'
availability:
$ref: '#/components/schemas/configuration_availability'
event_booking:
$ref: '#/components/schemas/configuration_event_booking'
name:
type: string
description: The name of the Scheduling Page. If not defined, Nylas defaults to the organizer's name.
participants:
type: array
description: |-
A list of participants to be included in the scheduled event.
Participants that provide availability (through an `availability` or `booking` block) must be
associated with a valid Nylas grant, or the request fails. Participants supplied by email only
don't require a grant. They're notification-only invitees who receive scheduling emails but don't
affect availability calculation and can't be selected as a round-robin host.
This field isn't accepted for group or round-robin configurations, which are anchored to the
organizer's own grant and calendar instead.
items:
$ref: '#/components/schemas/configuration_participants'
requires_session_auth:
type:
- boolean
- 'null'
description: |-
When `true`, the scheduling [Availability](/docs/reference/api/availability/) and
[Bookings](/docs/reference/api/bookings/) endpoints require a valid session ID to
authenticate requests using the specified Configuration. This field may be `null`
if not explicitly set on the configuration; treat `null` the same as `false`
(the default behavior).
default: false
scheduler:
$ref: '#/components/schemas/configuration_scheduler'
slug:
type:
- string
- 'null'
description: |-
The slug for the Configuration object. This is an optional, unique identifier. You can use the
slug instead of the `configuration_id` when making requests to the Nylas Scheduling endpoints.
Slugs are unique to each Nylas application. This field may be `null` if no slug has been set.
group-configuration:
type: object
required:
- group_booking
- name
- type
properties:
appearance:
$ref: '#/components/schemas/configuration_appearance'
group_booking:
type: object
description: Settings for the group booking.
required:
- calendar_id
properties:
booking_type:
type: string
description: |-
The booking type. Group Configurations support `booking` only, and follow the
[standard booking flow](/docs/v3/scheduler/customize-booking-flows/).
default: booking
example: booking
calendar_id:
type: string
description: |-
The ID of the calendar on which the group event is created. Nylas doesn't support read-only
calendars.
example: primary
disable_emails:
type:
- boolean
- 'null'
description: |-
When `true`, Nylas doesn't send email notifications when an event is booked, cancelled, or
rescheduled. When `null`, the default behavior applies (emails are sent).
default: false
example: false
reminders:
type: array
description: A list of reminders for the event.
items:
type: object
required:
- minutes_before_event
- type
properties:
email_subject:
type: string
description: (Email reminders only) The subject line for the email reminder.
example: 'Reminder: Your physiotherapy appointment'
minutes_before_event:
type: integer
description: The number of minutes before the event to send the reminder.
minimum: 1
example: 30
recipient:
type: string
description: (Email reminders only) Who should receive the email reminder.
enum:
- host
- guest
example: host
type:
type: string
description: The reminder type.
enum:
- email
- webhook
example: email
name:
type: string
description: The name of the Scheduling Page.
example: InPath Physiotherapy
requires_session_auth:
type:
- boolean
- 'null'
description: |-
When `true`, the [Availability](/docs/reference/api/availability/) and
[Bookings](/docs/reference/api/bookings/) endpoints require a valid session ID to
authenticate requests using the specified Configuration. This field may be `null`
if not explicitly set on the configuration; treat `null` the same as `false`
(the default behavior).
default: false
example: false
scheduler:
$ref: '#/components/schemas/configuration_scheduler'
slug:
type:
- string
- 'null'
description: |-
The slug for the Configuration object. This is an optional, unique identifier. You can use the
slug instead of the `configuration_id` when making requests to the Nylas Scheduling endpoints.
Slugs are unique to each Nylas application. This field may be `null` if no slug has been set.
type:
type: string
description: |-
The type of event supported by the Configuration. When set to `group`, enables access to the
[Group Events endpoints](/docs/reference/api/group-events/) and functionality.
Defaults to empty (`""`) for all existing Configurations.
example: group
group_event_participants:
title: Group event participants
type: object
description: |-
An array of participants to include in the event booking. If you don't specify at least
one participant, Nylas uses the event organizer instead.
required:
- email
properties:
name:
type: string
description: The participant's name.
example: Leyah Miller
email:
type: string
description: The participant's email address.
example: leyah@example.com
is_organizer:
type: boolean
description: When `true`, indicates that the participant is the event organizer.
default: false
example: true
group_event_recurrence:
title: Group event recurrence settings
type: array
items:
type: string
description: |-
An array of `RRULE` and `EXDATE` strings. Nylas includes this field only if the event is the main
(master) event. See [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5) for more details.
You can use [this tool](https://jkbrzt.github.io/rrule/) to learn more about the `RRULE` spec.
Events inherit their timezone from the `when` object. Nylas recommends that you use the `when`
object to specify the event's start and end time.
Provider specifics:
- Virtual calendars don't support `DTSTART` or `TZID`.
- iCloud accounts do _not_ support recurring events for group events
- Microsoft Graph adds one day to the `UNTIL` date.
example:
- RRULE:FREQ=WEEKLY;BYDAY=MO
- EXDATE:20210405T000000Z
group_event:
type: object
required:
- availability
- event_booking
- participants
- when
properties:
capacity:
type: integer
description: (Not supported for EWS events) The maximum number of attendees allowed in the event.
minimum: 1
maximum: 500
default: 10
example: 50
conferencing:
$ref: '#/components/schemas/event_conferencing_request'
description:
type: string
description: |-
A brief description of the group event (for example, its agenda). Nylas might return the
description as an HTML string, depending on how the provider formats it.
For Google accounts, this field accepts a maximum of 8,192 characters.
example: Come ready to talk philosophy!
location:
type: string
description: |-
The location of the group event (for example, a physical address or the name of a meeting
room).
maxLength: 255
example: New York Public Library, Cave Room
participants:
type: array
items:
$ref: '#/components/schemas/group_event_participants'
recurrence:
$ref: '#/components/schemas/group_event_recurrence'
reminders:
type: array
required:
- type
- minutes_before_event
items:
type: object
properties:
type:
type: string
description: The reminder type.
enum:
- email
- webhook
example: email
minutes_before_event:
type: integer
description: The number of minutes before the event to send the reminder.
minimum: 1
example: 30
recipient:
type: string
description: (Email reminders only) Who should receive the reminder.
enum:
- host
- guest
example: host
email_subject:
type: string
description: (Email reminders only) The subject line of the email reminder.
example: 'Reminder: Annual Philosophy Club Meeting'
title:
type: string
description: The name of the event.
maxLength: 1024
example: Annual Philosophy Club Meeting
when:
type: object
description: The time and duration of the event.
oneOf:
- $ref: '#/components/schemas/event_timespan'
- title: Read-only object
type: object
description: Read-only placeholder. Returned only in responses.
readOnly: true
import-group-event-response:
type: object
properties:
imported_events:
type: array
description: A list of event IDs representing successfully imported group events.
items:
type: object
properties:
event_id:
type: string
description: The group event ID.
example: 5d3qmne77v32r8l4phyuksl2x
import_failed:
type: array
description: A list of event IDs representing group events that Nylas couldn't import.
items:
type: object
properties:
event_id:
type: string
description: The group event ID.
example: 5d3qmne77v32r8l4phyuksl2x
reason:
type: string
description: The reason the event wasn't imported.
booking_create:
type: object
required:
- start_time
- end_time
- guest
properties:
start_time:
type: integer
description: The event's start time, in seconds using the Unix timestamp format.
end_time:
type: integer
description: The event's end time, in seconds using the Unix timestamp format.
participants:
type: array
description: An array of objects that include a list of participant email addresses from the Configuration object to include in the booking. If not provided, Nylas includes all participants from the Configuration object.
items:
type: object
properties:
email:
type: string
description: The participant's email address.
guest:
type: object
description: Details about the guest that is creating the booking. The guest `name` and `email` are required.
properties:
email:
type: string
description: The guest's email address.
name:
type: string
description: The guest's name.
timezone:
type: string
description: |-
The guest's timezone, used in email notifications. If not provided, Nylas uses the timezone from
the [Configuration object](/docs/reference/api/configurations/).
email_language:
type: string
description: The language of the guest email notifications.
enum:
- en
- fr
- de
- es
- nl
- sv
- ja
- zh
default: en
additional_guests:
type: array
description: An array of objects that include a list of additional guest email addresses to include in the booking.
items:
type: object
properties:
email:
type: string
description: The additional guest's email address.
name:
type: string
description: The additional guest's name.
additional_fields:
type: object
description: A dictionary of additional field keys mapped to the values populated by the guest in the booking form.
additionalProperties:
type: string
example:
name: Dorothy Vaughan
email_address: dorothy@example.com
booking:
type: object
required:
- booking_id
- event_id
- title
- organizer
- status
properties:
booking_id:
type: string
description: The unique ID of the booking.
event_id:
type: string
description: The unique ID of the event object associated with the booking.
title:
type: string
description: The title of the event.
organizer:
type: object
description: The participant that is designated as the organizer of the event.
properties:
email:
type: string
description: The organizer's email address.
name:
type: string
description: The organizer's name.
status:
type: string
description: The current status of the booking.
enum:
- booked
- pending
- cancelled
description:
type: string
description: The description of the event.
booking_confirm:
type: object
required:
- salt
- status
properties:
salt:
type: string
description: The salt extracted from the booking reference embedded in the organizer confirmation link, encoded as a URL-safe base64 string (without padding).
status:
type: string
description: The action to take on the pending booking.
enum:
- confirmed
- cancelled
cancellation_reason:
type: string
description: The reason that the booking is being cancelled.
booking_update:
type: object
required:
- start_time
- end_time
properties:
start_time:
type: string
description: The event's start time, in seconds using the Unix timestamp format.
end_time:
type: string
description: The event's end time, in seconds using the Unix timestamp format.
booking_update_group:
type: object
required:
- calendar_id
- end_time
- event_id
- start_time
properties:
calendar_id:
type: string
description: The ID of the calendar to access.
example: 7d93zl2palhxqdy6e5qinsakt
end_time:
type: integer
description: The event's end time, in seconds using the Unix timestamp format.\
example: 1661877792
event_id:
type: string
description: The ID of the event to update.
example: 5d3qmne77v32r8l4phyuksl2x
master_event_id:
type: string
description: (Recurring events only) The ID of the master event.
example: 5d3qmne77v32r8l4phyuksl2x
start_time:
type: integer
description: The event's start time, in seconds using the Unix timestamp format.
example: 1661874192
MigrationJob:
type: object
additionalProperties: false
required:
- job_id
- type
- public_application_id
- status
- count_all
- count_success
- count_failed
- count_warning
- created_at
- updated_at
properties:
job_id:
type: string
description: An identifier for the migration job.
example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
type:
type: string
description: The type of job.
enum:
- snapshot
- migration
example: snapshot
public_application_id:
type: string
description: The ID of v3 application this job is running for.
example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
status:
type: string
description: |-
The state of the job.
- **Pending**: The job has been created, but not started. Batch clone runs only after the linked
snapshot job is completed.
- **Running**: The job is currently running.
- **Completed**: The job has successfully finished all migrations.
- **Failed**: _All_ migrations failed.
- **Partial**: The job successfully migrated _some_ accounts, but some could not be migrated or were created as "placeholder" grants.
enum:
- pending
- running
- completed
- failed
- partial
example: pending
count_all:
type: integer
description: A total number of accounts to be migrated. The total is a sum of the successful and failed migrations.
example: 20
count_success:
type: integer
description: The number of accounts that were successfully migrated.
example: 10
count_failed:
type: integer
description: The number of accounts that were unable to migrate.
example: 5
count_warning:
type: integer
description: The number of accounts that were migrated as invalid grants ("placeholder" grant ready for re-authentication).
example: 5
created_at:
type: integer
description: The time when the job was created, in seconds using the Unix timestamp format.
example: 1617817109
updated_at:
type: integer
description: The time the job was updated, in seconds using the Unix timestamp format.
example: 1617817109
linked_job_id:
type: string
description: The bulk migration tool creates two separate jobs that run one after the other. This ID links them together.
example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
translate_v2v3_id:
type: object
additionalProperties: false
required:
- v2_application_id
- v2_account_id
- resource_type
- ids
properties:
v2_application_id:
type: string
description: The ID of the v2 Nylas application the connected account belongs to.
example: defg12342l0mr39hmla2eabcd
v2_account_id:
type: string
description: The ID of v2 connected account you are requesting translations for.
example: 1kb392012l0mr39hmla2exnxu
resource_type:
type: string
description: |-
The names of the v2 resources you're requesting translations for.
To request Gmail's "labels", include `folders`. (Nylas v3 consolidates folders and labels into
one resource.)
example: message
enum:
- messages
- drafts
- threads
- contacts
- contactgroups
- events
- calendars
- folders
translations:
type: array
description: |-
A list of v2 Nylas IDs and their v3 Provider ID counterparts, according to the requested resource
type and v2 connected account.
items:
type: object
properties:
v2_resource_id:
type: string
description: The v2 Nylas ID.
example: 1kb392012l0mr39hmla2exnxu
v3_resource_id:
type: string
description: The v3 Provider ID.
example: 175ade7f22b0a2f4
next_page_number:
type: integer
description: A page number for next set of results, if more results are available. This field does not appear if there are no more results.
example: 2
requestBodies:
message_update:
content:
application/json:
schema:
title: Message Update payload
type: object
properties:
starred:
type: boolean
description: Set to `true` to mark as starred; `false` to mark as not starred.
example: true
unread:
type: boolean
description: Set to `true` to mark as unread; `false` to mark as read.
example: true
folders:
type: array
items:
type: string
description: The ID(s) of the folder(s) to apply, overwriting all folders previously associated with the message. Microsoft messages can be in a single folder only. Google allows a single message to appear in multiple folders.
example:
- folder-1
- folder-2
metadata:
$ref: '#/components/schemas/metadata'
messages-clean:
content:
application/json:
schema:
type: object
properties:
message_id:
type: array
items:
type: string
description: An array of IDs for the messages Nylas will clean.
example:
- 18df98cadcc8534a
maxItems: 20
ignore_links:
type: boolean
description: If `true`, removes link-related tags (`<a>`) from the message while keeping the text.
example: true
default: true
ignore_images:
type: boolean
description: If `true`, removes images from the message.
example: true
default: true
images_as_markdown:
type: boolean
description: |-
If `true`, converts images in the message to
[Markdown](https://en.wikipedia.org/wiki/Markdown). Can't be `false` when `html_as_markdown`
is `true`.
example: true
default: true
ignore_tables:
type: boolean
description: |-
If `true`, removes table-related tags (`<table>`, `<th>`, `<td>`, `<tr>`) from the message
while keeping rows.
example: true
default: true
remove_conclusion_phrases:
type: boolean
description: If `true`, removes phrases such as "Best" and "Regards" from the message signature.
example: true
default: true
html_as_markdown:
type: boolean
description: |-
**This property is in beta**. If `true`, converts the message to
[Markdown](https://en.wikipedia.org/wiki/Markdown). Can't be `true` when
`images_as_markdown` is `false`.
example: false
default: false
message_send:
content:
application/json:
schema:
type: object
required:
- to
properties:
attachments:
type: array
description: An array of files to be sent with the message.
items:
type: object
properties:
content:
type: string
description: |-
The Base64-encoded file content. See
[Working with email attachments](/docs/v3/email/attachments/#attachment-schemas-and-size-limits)
for more information.
example: YXR0YWNoDQoNCi0tLS0tLS0tLS0gRm9yd2FyZGVkIG1lc3NhZ2UgL=
content_disposition:
type: string
description: |-
(Not supported for Microsoft and EWS) The content disposition of the file. Usually,
this is `inline` or `attachment`, followed by the file name.
example: attachment; filename="nylas_logo.png"
content_id:
type: string
description: |-
(Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the HTML
message body. To avoid unexpected behavior in threads, make sure to use unique CIDs
across messages of a thread.
example: ce9b9547-9eeb-43b2-ac4e-58768bdf04e4
content_type:
type: string
description: |-
The
[MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)
of the file. This is used by the email client to determine how to display the
attachment.
minLength: 1
example: image/png
filename:
type: string
description: The file name.
minLength: 1
example: nylas_logo.png
bcc:
type: array
description: A list of people BCC'd on the message.
items:
type: object
properties:
name:
type: string
description: The name of the person BCC'd on the message.
example: Leyah Miller
email:
type: string
description: The email address of the person BCC'd on the message.
example: leyah@example.com
body:
type: string
description: The HTML body of the message.
example: Looking forward to seeing you!
cc:
type: array
description: A list of people CC'd on the message.
items:
type: object
properties:
name:
type: string
description: The name of the person CC'd on the message.
example: Kaveh
email:
type: string
description: The email address of the person CC'd on the message.
example: kaveh@example.com
custom_headers:
type: array
description: An array of custom headers to add to the message.
items:
type: object
properties:
name:
type: string
description: The header name.
example: Email-Campaign
value:
type: string
description: The header value.
example: meetings
from:
type: array
description: |-
The sender of the message. Accepts a single object in an array. If omitted, Nylas uses the
grant's email address and display name.
items:
type: object
required:
- email
properties:
name:
type: string
description: The name of the user sending the message.
example: Nyla
email:
type: string
description: The email address of the user sending the message.
example: nyla@example.com
is_plaintext:
type: boolean
description: When `true`, the message body is sent as plain text and the MIME data doesn't include the HTML version of the message. When `false`, the message body is sent as HTML.
default: false
metadata:
$ref: '#/components/schemas/metadata'
reply_to:
type: array
description: A list of people who should receive replies to the message by default.
items:
type: object
properties:
name:
type: string
description: The name of the person who should receive replies to the message.
example: Leyah Miller
email:
type: string
description: The email address of the person who should receive replies to the message.
example: leyah@example.com
reply_to_message_id:
type: string
description: |-
The ID of the message you're replying to. For Gmail and Microsoft Graph, this is the
message ID on the provider. For IMAP Send, this is the
[RFC822](https://datatracker.ietf.org/doc/html/rfc822#section-4.6.1) `Message-ID` header
of the message you're replying to.
send_at:
type: integer
description: |-
The time when Nylas should send the message, in seconds using the Unix timestamp format. This time must be
at least one minute in the future from the time you make your request. You can schedule
a message to be sent up to 30 days in the future. If the request includes
`tracking_options.domain_name`, Nylas validates the hostname when it creates the schedule
and revalidates it before delivery.
subject:
type: string
description: The subject of the message.
example: 'Reminder: Annual Philosophy Club Meeting'
template:
type: object
description: The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
properties:
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
to:
type: array
description: A list of people that the message will be sent to.
items:
type: object
properties:
name:
type: string
description: The name of the person the message will be sent to.
example: Kim Townsend
email:
type: string
description: The email address of the person the message will be sent to.
example: kim@example.com
tracking_options:
type: object
description: Tracking settings for the message. See [Track messages](/docs/v3/email/message-tracking/).
properties:
opens:
type: boolean
description: |-
When `true`, enables
[message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the
message. Nylas generates a
[`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications)
when a participant first opens the message.
default: false
thread_replies:
type: boolean
description: |-
When `true`, enables
[thread replied tracking](/docs/v3/email/message-tracking/#thread-replied-tracking)
on the message. Nylas generates a
[`thread.replied` webhook notification](/docs/reference/notifications/#thread-replied-notifications)
when a participant replies to the thread.
default: false
links:
type: boolean
description: |-
When `true`, enables
[link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the
message. Nylas generates a
[`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications)
when a participant clicks a link in the message.
default: false
label:
type: string
description: |-
A brief description of the message, why it's being tracked, or the tracking options
enabled.
maxLength: 2048
domain_name:
$ref: '#/components/schemas/tracking_domain_name'
use_draft:
type: boolean
description: |-
(Google and Microsoft only) When `true`, Nylas saves the message in the user's Drafts folder
until its `send_at` time. This field can't be `true` if `send_at` is undefined.
default: false
signature_id:
type: string
description: |-
The ID of a [signature](/docs/v3/email/signatures/) to append to the message body. Nylas
inserts the signature after a line break at the end of the body, including after any quoted
text in replies and forwards. Only one signature can be used per message.
example: sig_abc123
multipart/form-data:
schema:
type: object
properties:
attachment:
type: string
description: The content of the attachment (if available), in binary format.
format: binary
message:
type: object
required:
- to
properties:
bcc:
type: array
description: A list of people BCC'd on the message.
items:
type: object
properties:
name:
type: string
description: The name of the person BCC'd on the message.
example: Leyah Miller
email:
type: string
description: The email address of the person BCC'd on the message.
example: leyah@example.com
body:
type: string
description: The HTML body of the message.
example: Looking forward to seeing you!
cc:
type: array
description: A list of people CC'd on the message.
items:
type: object
properties:
name:
type: string
description: The name of the person CC'd on the message.
example: Kaveh
email:
type: string
description: The email address of the person CC'd on the message.
example: kaveh@example.com
custom_headers:
type: array
description: An array of custom headers to add to the message.
items:
type: object
properties:
name:
type: string
description: The header name.
example: Email-Campaign
value:
type: string
description: The header value.
example: meetings
from:
type: array
description: |-
The sender of the message. Accepts a single object in an array. If omitted, Nylas uses
the grant's email address and display name.
items:
type: object
required:
- email
properties:
name:
type: string
description: The name of the user sending the message.
example: Nyla
email:
type: string
description: The email address of the user sending the message.
example: nyla@example.com
is_plaintext:
type: boolean
description: When `true`, the message body is sent as plain text and the MIME data doesn't include the HTML version of the message. When `false`, the message body is sent as HTML.
default: false
reply_to:
type: array
description: A list of people who should receive replies to the message by default.
items:
type: object
properties:
name:
type: string
description: The name of the person who should receive replies to the message.
example: Leyah Miller
email:
type: string
description: The email address of the person who should receive replies to the message.
example: leyah@example.com
send_at:
type: integer
description: |-
The time when Nylas should send the message, in seconds using the Unix timestamp format.
Must be at least one minute in the future from the time you make your request. You can
schedule a message to be sent up to 30 days in the future. If the request includes
`tracking_options.domain_name`, Nylas validates the hostname when it creates the schedule
and revalidates it before delivery.
subject:
type: string
description: The subject of the message.
example: 'Reminder: Annual Philosophy Club Meeting'
template:
type: object
description: The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
properties:
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
to:
type: array
description: A list of people that the message will be sent to.
items:
type: object
properties:
name:
type: string
description: The name of the person the message will be sent to.
example: Kim Townsend
email:
type: string
description: The email address of the person the message will be sent to.
example: kim@example.com
tracking_options:
type: object
description: Tracking settings for the message. See [Track messages](/docs/v3/email/message-tracking/).
properties:
opens:
type: boolean
description: |-
When `true`, enables
[message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the
message. Nylas generates a
[`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications)
when a participant first opens the message.
default: false
thread_replies:
type: boolean
description: |-
When `true`, enables
[thread replied tracking](/docs/v3/email/message-tracking/#thread-replied-tracking)
on the message. Nylas generates a
[`thread.replied` webhook notification](/docs/reference/notifications/#thread-replied-notifications)
when a participant replies to the thread.
default: false
links:
type: boolean
description: |-
When `true`, enables
[link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the
message. Nylas generates a
[`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications)
when a participant clicks a link in the message.
default: false
label:
type: string
description: |-
A brief description of the message, why it's being tracked, or the tracking options
enabled.
maxLength: 2048
domain_name:
$ref: '#/components/schemas/tracking_domain_name'
use_draft:
type: boolean
description: |-
(Google and Microsoft only) When `true`, Nylas saves the message in the user's Drafts folder
until its `send_at` time. This field can't be `true` if `send_at` is undefined.
default: false
signature_id:
type: string
description: |-
The ID of a [signature](/docs/v3/email/signatures/) to append to the message body. Nylas
inserts the signature after a line break at the end of the body, including after any quoted
text in replies and forwards. Only one signature can be used per message.
example: sig_abc123
encoding:
attachment:
contentType: application/octet-stream
message:
contentType: application/json
smart_compose:
content:
application/json:
schema:
title: Smart Compose
type: object
description: A Smart Compose request.
properties:
prompt:
title: Prompt
description: The prompt that Smart Compose uses to generate a message suggestion.
maxLength: 1000
type: string
example: Reply to John Doe about the upcoming project.
signature_create:
content:
application/json:
schema:
type: object
required:
- name
- body
properties:
name:
type: string
description: A label for the signature (for example, "Work", "Personal", or "Mobile").
example: Work Signature
body:
type: string
description: |-
The HTML content of the signature. Maximum 100 KB. Images must use externally hosted URLs
(base64 inline images are not supported). Nylas sanitizes the HTML on input to prevent
malicious content.
example: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p><p><a href="mailto:nick@nylas.com">nick@nylas.com</a></p></div>
example:
name: Work Signature
body: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p><p><a href="mailto:nick@nylas.com">nick@nylas.com</a></p></div>
signature_update:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Updated label for the signature.
example: Updated Work Signature
body:
type: string
description: |-
Updated HTML content for the signature. Maximum 100 KB. Images must use externally hosted
URLs (base64 inline images are not supported). Nylas sanitizes the HTML on input to prevent
malicious content.
example: <div><p><strong>Nick Barraclough</strong></p><p>Senior Product Manager | Nylas</p></div>
example:
name: Updated Work Signature
body: <div><p><strong>Nick Barraclough</strong></p><p>Senior Product Manager | Nylas</p></div>
draft_create:
content:
application/json:
schema:
title: Drafts
type: object
description: A draft of a message. You can edit a draft until you send it as a message.
properties:
bcc:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients to be BCC'd.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: brandon.carson@example.com
name: ''
body:
type: string
description: The body of the draft, in HTML format.
example: Hi, Welcome to Nylas!
cc:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients to be CC'd.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: clivescounters@example.com
name: ''
tracking_options:
type: object
properties:
opens:
type: boolean
thread_replies:
type: boolean
links:
type: boolean
label:
type: string
maxLength: 2048
domain_name:
$ref: '#/components/schemas/tracking_domain_name'
attachments:
description: |-
An array of file attachments to include in the draft. You can use either the
`application/json` or `multipart/form-data` schema, depending on the size of the
attachment.
The `application/json` schema is limited to 3MB, including the message body. The `content`
must be Base64-encoded.
The `multipart/form-data` schema is limited by the provider to 25MB. See the
[Attachments references](/docs/reference/api/attachments/) for more information.
type: array
uniqueItems: true
items:
type: object
properties:
filename:
type: string
content:
description: |-
Must be Base64-encoded if using the `application/json` schema. Use binary format if
using `multipart/form-data`.
type: string
content_type:
type: string
description: |-
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)
of the attachment, used by the email client to determine how to display the
attachment. If you don't provide a type, Nylas infers it from the file name.
content_id:
type: string
description: |-
(Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the email's
HTML. For example, you might see something like
`<img src=\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\">` in the message body.
content_disposition:
type: string
description: |-
(Not supported for Microsoft and EWS) The content disposition of the attachment.
Usually, this is `inline` or `attachment` followed by the file name.
example: inline; filename="some-image.jpeg"
from:
type: array
description: |-
An array that contains a single name and email address pair that Nylas sets as the
`from` header. By default, Nylas uses the email address associated with the `grant_id`.
Nylas supports multiple `from` addresses for email aliases only.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: leyah@example.com
name: Leyah Miller
is_plaintext:
type: boolean
description: When `true`, the message body is sent as plain text and the MIME data doesn't include the HTML version of the message. When `false`, the message body is sent as HTML.
default: false
reply_to:
type: array
uniqueItems: true
description: |-
An array of name/email address pairs that should receive replies to the message. This is
used to set an alternative `Reply-To` header in the sent message. Not all providers support
setting this in a draft.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: healthcare.demo@example.com
name: ''
reply_to_message_id:
type: string
description: The unique identifier of the message to which you want to draft a reply.
example: 1t8tv3890q4vgmwq6pmdwm8qg
starred:
type: boolean
description: If `true`, the draft is starred.
example: false
subject:
type: string
description: The subject line of the draft.
example: 'Invitation: Welcome! @ Thu Oct 28, 2021 7am - 8am (EDT) - Toronto'
to:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: demo@example.com
name: ''
- email: realestate.demo@example.com
name: ''
custom_headers:
type: array
description: An array of custom headers to add to the message.
items:
type: object
properties:
name:
type: string
value:
type: string
metadata:
$ref: '#/components/schemas/metadata'
template:
type: object
description: The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
properties:
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
signature_id:
type: string
description: |-
The ID of a [signature](/docs/v3/email/signatures/) to append to the draft body. Nylas
inserts the signature after a line break at the end of the body. Only one signature can be
used per draft.
example: sig_abc123
multipart/form-data:
schema:
type: object
properties:
draft:
type: object
description: A draft of a message. You can edit a draft until you send it as a message.
properties:
bcc:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients to be BCC'd.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: brandon.carson@example.com
name: ''
body:
type: string
description: The body of the draft, in HTML format.
example: Hi, Welcome to Nylas!
cc:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients to be CC'd.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: clivescounters@example.com
name: ''
tracking_options:
type: object
properties:
opens:
type: boolean
thread_replies:
type: boolean
links:
type: boolean
label:
type: string
maxLength: 2048
domain_name:
$ref: '#/components/schemas/tracking_domain_name'
reply_to:
type: array
uniqueItems: true
description: |-
An array of name/email address pairs that should receive replies to the message. This
is used to set an alternative `Reply-To` header in the sent message. Not all providers
support setting this in a draft.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: healthcare.demo@example.com
name: ''
starred:
type: boolean
description: If `true`, the draft is starred.
example: false
subject:
type: string
description: The subject line of the draft.
example: 'Invitation: Welcome! @ Thu Oct 28, 2021 7am - 8am (EDT) - Toronto'
thread_id:
type: string
description: A reference to the parent Thread object. If you're creating a new draft, leave this empty.
example: 1t8tv3890q4vgmwq6pmdwm8qg
to:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients.
items:
$ref: '#/components/schemas/message-participant'
examples:
- email: demo@example.com
name: ''
- email: realestate.demo@example.com
name: ''
custom_headers:
type: array
description: An array of custom headers to add to the message.
items:
type: object
properties:
name:
type: string
value:
type: string
metadata:
$ref: '#/components/schemas/metadata'
template:
type: object
description: The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
properties:
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
signature_id:
type: string
description: |-
The ID of a [signature](/docs/v3/email/signatures/) to append to the draft body. Nylas
inserts the signature after a line break at the end of the body. Only one signature can
be used per draft.
example: sig_abc123
attachment:
type: string
description: The content of the attachment, in binary format.
format: binary
example: binary data
draft_update:
content:
application/json:
schema:
title: Drafts
type: object
description: A draft of a message. You can edit a draft until you send it as a message.
properties:
bcc:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients to be BCC'd.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: brandon.carson@example.com
name: ''
body:
type: string
description: The body of the draft, in HTML format.
example: Hi, Welcome to Nylas!
cc:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients to be CC'd.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: clivescounters@example.com
name: ''
tracking_options:
type: object
properties:
opens:
type: boolean
thread_replies:
type: boolean
links:
type: boolean
label:
type: string
maxLength: 2048
domain_name:
$ref: '#/components/schemas/tracking_domain_name'
attachments:
type: array
uniqueItems: true
description: An array of file attachments to include in the draft. You can use either the `application/json` or `multipart/form-data` schema, depending on attachment size. The `application/json` format is limited to 3MB including the message body, and the `content` must be Base64 encoded. The `multipart/form-data` format size is limited by the provider to 25MB. See [Attachments](/#tag--Attachments) for more information.
items:
type: object
properties:
filename:
type: string
content:
description: Must be Base64-encoded if using the `application/json` schema. Use binary format if using `multipart/form-data`.
type: string
content_type:
type: string
description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the attachment, used by the email client to determine how to display the attachment. If you don't provide a type, Nylas infers it from the file name.
content_id:
type: string
description: |-
(Inline attachments only) The alphanumeric `cid` from the `<img>` tag in the message's
HTML. For example, you might see something like
`<img src=\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\">` in the message body. Only
include a value for the `content_id` field if the attachment is inline.
content_disposition:
type: string
description: (Not supported for Microsoft and EWS) The content disposition of the attachment. Usually, this is `inline` or `attachment` followed by the file name (for example, `inline; filename="some-image.jpeg"`).
example: inline; filename="some-image.jpeg"
reply_to:
type: array
uniqueItems: true
description: |-
An array of name/email address pairs that should receive replies to the message. This is
used to set an alternative `Reply-To` header in the sent message. Not all providers support
setting this in a draft.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: healthcare.demo@example.com
name: ''
starred:
type: boolean
description: If `true`, the draft is starred.
example: false
subject:
type: string
description: The subject line of the draft.
example: 'Invitation: Welcome! @ Thu Oct 28, 2021 7am - 8am (EDT) - Toronto'
to:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: demo@example.com
name: ''
- email: realestate.demo@example.com
name: ''
metadata:
$ref: '#/components/schemas/metadata'
template:
type: object
description: The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
properties:
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
multipart/form-data:
schema:
type: object
properties:
draft:
type: object
description: A draft of a message. You can edit a draft until you send it as a message.
properties:
bcc:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients to be BCC'd.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: brandon.carson@example.com
name: ''
body:
type: string
description: The body of the draft, in HTML format.
example: Hi, Welcome to Nylas!
cc:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients to be CC'd.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: clivescounters@example.com
name: ''
tracking_options:
type: object
properties:
opens:
type: boolean
thread_replies:
type: boolean
links:
type: boolean
label:
type: string
maxLength: 2048
domain_name:
$ref: '#/components/schemas/tracking_domain_name'
reply_to:
type: array
uniqueItems: true
description: |-
An array of name/email address pairs that should receive replies to the message. This
is used to set an alternative `Reply-To` header in the sent message. Not all providers
support setting this in a draft.
items:
$ref: '#/components/schemas/message-participant'
example:
- email: healthcare.demo@example.com
name: ''
starred:
type: boolean
description: If `true`, the draft is starred.
example: false
subject:
type: string
description: The subject line of the draft.
example: 'Invitation: Welcome! @ Thu Oct 28, 2021 7am - 8am (EDT) - Toronto'
thread_id:
type: string
description: A reference to the parent Thread object.
example: 1t8tv3890q4vgmwq6pmdwm8qg
to:
type: array
uniqueItems: true
description: The name/email address pairs of the recipients.
items:
$ref: '#/components/schemas/message-participant'
examples:
- email: demo@example.com
name: ''
- email: realestate.demo@example.com
name: ''
metadata:
$ref: '#/components/schemas/metadata'
template:
type: object
description: The [template](/docs/reference/api/application-level-templates/) to use for the message. Can be overriden by the `body` and `subject` fields.
properties:
id:
type: string
description: The template ID.
example: b79c82b2-a51b-4c54-8469-28006a43551a
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
attachment:
type: string
description: The content of the attachment, in binary format.
format: binary
example: binary data
thread_update:
content:
application/json:
schema:
title: Update thread payload
type: object
properties:
starred:
type: boolean
description: When `true`, indicates that the thread is starred.
example: true
unread:
type: boolean
description: When `false`, indicates that all messages in the thread have been read.
example: true
folders:
type: array
items:
type: string
description: |-
The IDs of the folders to apply to the thread. This overwrites all previously assigned
folders for all messages in the thread.
example:
- folder-1
- folder-2
folder_create:
content:
application/json:
schema:
$ref: '#/components/schemas/create_folder'
examples:
Google Folder:
value:
name: Invoices
text_color: '#fff'
background_color: '#00FF00'
Microsoft Folder:
value:
name: Invoices
parent_id: AAMkADk0ZWVhMzJhLWY1ODktNDRhZi1hNDcyLWJkMDRlYmE0MTc3ZAAuAAAAAAC6eJwD9EoFS4TLH1YcoDjXAQDIFSkx-42TT5zffjtLuf8AAAAAAAEIAAA=
folder_update:
content:
application/json:
schema:
$ref: '#/components/schemas/update_folder'
examples:
Google Folder:
value:
name: Invoices
text_color: '#fff'
background_color: '#00FF00'
Microsoft Folder:
value:
name: Invoices
parent_id: AAMkADk0ZWVhMzJhLWY1ODktNDRhZi1hNDcyLWJkMDRlYmE0MTc3ZAAuAAAAAAC6eJwD9EoFS4TLH1YcoDjXAQDIFSkx-42TT5zffjtLuf8AAAAAAAEIAAA=
calendar_create:
content:
application/json:
schema:
type: object
required:
- name
properties:
description:
$ref: '#/components/schemas/calendar_description'
location:
$ref: '#/components/schemas/calendar_location'
metadata:
$ref: '#/components/schemas/metadata'
name:
$ref: '#/components/schemas/calendar_name'
notetaker:
$ref: '#/components/schemas/calendar_sync'
timezone:
$ref: '#/components/schemas/calendar_timezone'
example:
description: Calendar for work events.
location: Los Angeles
name: Work Calendar
notetaker:
name: Nyla's Notetaker
meeting_settings:
action_items: true
action_item_settings:
custom_instructions: Only return the 5 most important action items.
audio_recording: true
summary: true
summary_settings:
custom_instructions: Return this summary in the MEDPIC sales methodology.
transcription: true
transcription_settings:
expected_languages:
- en
- es
fallback_language: en
video_recording: true
rules:
event_selection:
- internal
participant_filter:
participants_gte: 5
participants_lte: 10
timezone: America/Los_Angeles
calendar_update:
content:
application/json:
schema:
type: object
properties:
description:
$ref: '#/components/schemas/calendar_description'
hex_color:
$ref: '#/components/schemas/calendar_hex_color'
hex_foreground_color:
$ref: '#/components/schemas/calendar_hex_foreground_color'
location:
$ref: '#/components/schemas/calendar_location'
metadata:
$ref: '#/components/schemas/metadata'
name:
type: string
description: |-
The name of the calendar.
Microsoft doesn't allow you to update the name of a user's primary calendar.
example: My Updated Calendar
timezone:
$ref: '#/components/schemas/calendar_timezone'
notetaker:
$ref: '#/components/schemas/calendar_sync'
example:
name: My New Calendar
description: Description of my new calendar
location: Location description
timezone: America/Los_Angeles
hex_color: '#039BE5'
notetaker:
name: Nylas Notetaker
meeting_settings:
video_recording: true
audio_recording: true
transcription: true
transcription_settings:
expected_languages:
- en
- es
fallback_language: en
rules:
event_selection:
- internal
freebusy:
content:
application/json:
schema:
$ref: '#/components/schemas/freebusy_request'
example:
start_time: 1633698000
end_time: 1633698000
emails:
- user1@example.com
- user2@example.com
event_send_rsvp:
content:
application/json:
schema:
$ref: '#/components/schemas/event_send_rsvp'
contact_create:
content:
application/json:
schema:
type: object
required:
- given_name
properties:
birthday:
$ref: '#/components/schemas/contact_birthday'
company_name:
$ref: '#/components/schemas/contact_company_name'
emails:
type: array
items:
$ref: '#/components/schemas/contact_email'
given_name:
$ref: '#/components/schemas/contact_given_name'
groups:
type: array
description: |-
A list of IDs for contact groups the contact is included in.
Microsoft, iCloud and IMAP support at most one contact group per contact.
items:
$ref: '#/components/schemas/contact_group_id'
im_addresses:
type: array
items:
$ref: '#/components/schemas/contact_im_address'
job_title:
$ref: '#/components/schemas/contact_job_title'
manager_name:
$ref: '#/components/schemas/contact_manager_name'
middle_name:
$ref: '#/components/schemas/contact_middle_name'
nickname:
$ref: '#/components/schemas/contact_nickname'
notes:
$ref: '#/components/schemas/contact_notes'
office_location:
$ref: '#/components/schemas/contact_office_location'
phone_numbers:
type: array
items:
$ref: '#/components/schemas/contact_phone_number'
physical_addresses:
type: array
items:
$ref: '#/components/schemas/contact_physical_address'
suffix:
$ref: '#/components/schemas/contact_suffix'
surname:
$ref: '#/components/schemas/contact_surname'
web_pages:
type: array
description: |-
An array of the contact's websites. Different providers may have different limits on the number of web pages.
- IMAP/iCloud/Yahoo: at most one web page per contact.
- Microsoft/EWS: at most one web page per contact. The type must be `work`.
items:
$ref: '#/components/schemas/contact_web_page'
example:
birthday: '1960-12-31'
company_name: Nylas
emails:
- email: john@example.com
type: work
- email: johnisacooldad@example.com
type: home
given_name: John
groups:
- id: starred
- id: all
im_addresses:
- type: jabber
im_address: myjabberaddress
- type: msn
im_address: mymsnaddress
job_title: Software Engineer
manager_name: Bill
middle_name: Jacob
nickname: JD
notes: Loves Ramen
office_location: 123 Main Street
phone_numbers:
- number: +1-555-555-5555
type: work
- number: +1-555-555-5556
type: home
physical_addresses:
- type: work
street_address: 123 Main Street
postal_code: '94107'
state: CA
country: USA
city: San Francisco
- type: home
street_address: 456 Main Street
postal_code: '94107'
state: CA
country: USA
city: San Francisco
source: address_book
suffix: Jr.
surname: Doe
web_pages:
- type: work
url: https://www.linkedin.com/in/johndoe
- type: home
url: https://www.johndoe.com
notetakers:
content:
application/json:
schema:
$ref: '#/components/schemas/notetakers'
patch-notetaker:
content:
application/json:
schema:
type: object
properties:
join_time:
type: integer
description: |-
When Notetaker should join the meeting, in seconds using the Unix timestamp format. If empty, Notetaker joins the
meeting immediately.
If you provide a time that's in the past, Nylas returns an error.
example: 1732657774
meeting_settings:
$ref: '#/components/schemas/meeting_settings'
name:
type: string
description: The display name for the Notetaker bot.
default: Nylas Notetaker
example: Nylas Notetaker
template_create:
description: Create template request
content:
application/json:
schema:
type: object
required:
- body
- name
- subject
properties:
body:
type: string
description: The body content of the template, in HTML format.
example: <p>Hello {{user.name}}, your booking has been confirmed.</p>
engine:
type: string
description: The templating engine to use.
enum:
- handlebars
- mustache
- nunjucks
- twig
default: mustache
example: mustache
name:
type: string
description: The name of the template.
example: Booking confirmed message
subject:
type: string
description: The subject line of the template.
example: '{{user.name}}, your booking is confirmed!'
template_update:
description: Update template request
content:
application/json:
schema:
type: object
properties:
body:
type: string
description: The body content of the template, in HTML format.
example: <p>Hello {{user.name}}, your booking has been confirmed.</p>
engine:
type: string
description: The templating engine to use.
enum:
- handlebars
- mustache
- nunjucks
- twig
example: mustache
name:
type: string
description: The name of the template.
example: Updated booking confirmed message
subject:
type: string
description: The subject line of the template.
example: '{{user.name}}, your booking is confirmed!'
template_render_html:
content:
application/json:
schema:
type: object
required:
- body
- engine
- variables
properties:
body:
type: string
description: The body content of the template, in HTML format.
example: <p>Hello {{user.name}}, this shows test was {{ foo }}.</p>
engine:
type: string
description: The templating engine to use.
enum:
- handlebars
- mustache
- nunjucks
- twig
example: mustache
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't defined
in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
foo: testing successful
template_render:
content:
application/json:
schema:
type: object
required:
- variables
properties:
strict:
type: boolean
description: |-
When `true`, Nylas returns an error if the template contains variables that aren't
defined in the `variables` object.
default: true
example: true
variables:
type: object
description: |-
A set of key/value pairs representing variables to substitute for values in the
template.
additionalProperties:
type: string
example:
user:
name: Leyah
surname: Miller
workflow_create:
description: Create workflow request
required: true
content:
application/json:
schema:
type: object
required:
- name
- template_id
- trigger_event
properties:
delay:
type: integer
description: |-
The number of minutes between a `trigger_event` being met and the workflow
sending a message.
default: 0
example: 5
is_enabled:
type: boolean
description: When `true`, indicates that the workflow is enabled.
default: true
example: true
name:
type: string
description: The name of the workflow.
example: New booking confirmation workflow
template_id:
type: string
description: The ID of the email template the workflow uses.
example: 14c00cc8-648c-4381-ad10-52641d9bac8e
trigger_event:
type: string
enum:
- booking.cancelled
- booking.created
- booking.pending
- booking.reminder
- booking.rescheduled
description: The event which triggers the workflow.
example: booking.created
from:
type:
- object
- 'null'
description: |-
Details of the sender if the workflow should use [transactional send](/docs/reference/api/transactional-send/).
If not provided, the sender will be the grant associated with the trigger event.
properties:
email:
type: string
description: The email address of the sender.
example: support@example.com
name:
type: string
description: The name of the sender.
example: Support
workflow_update:
description: Update workflow request
required: true
content:
application/json:
schema:
type: object
properties:
delay:
type: integer
description: |-
The number of minutes between a `trigger_event` being met and the workflow
sending a message.
example: 1
is_enabled:
type: boolean
description: When `true`, indicates that the workflow is enabled.
example: false
name:
type: string
description: The name of the workflow.
example: Updated booking confirmation workflow
template_id:
type: string
description: The ID of the email template the workflow uses.
example: 14c00cc8-648c-4381-ad10-52641d9bac8e
trigger_event:
type: string
enum:
- booking.cancelled
- booking.created
- booking.pending
- booking.reminder
- booking.rescheduled
description: The event which triggers the workflow.
example: booking.created
from:
type:
- object
- 'null'
description: |-
Details of the sender if the workflow should use [transactional send](/docs/reference/api/transactional-send/).
If not provided, the sender will be the grant associated with the trigger event.
properties:
email:
type: string
description: The email address of the sender.
example: support@example.com
name:
type: string
description: The name of the sender.
example: Support
group_event_create:
description: Create a group event
content:
application/json:
schema:
type: object
required:
- calendar_id
- capacity
- participants
- title
- when
properties:
calendar_id:
type: string
description: The ID of the calendar to access.
example: primary
capacity:
type: integer
description: The maximum number of attendees allowed in the event.
minimum: 1
maximum: 500
default: 10
example: 50
conferencing:
type: object
description: |-
An object that lets you automatically create a conference, or enter conferencing details
manually.
oneOf:
- $ref: '#/components/schemas/event_conferencing_request'
- title: Read-only object
type: object
description: Read-only placeholder. Returned only in responses.
readOnly: true
description:
type: string
description: |-
A brief description of the group event (for example, its agenda). Nylas might return the
description as an HTML string, depending on how the provider formats it.
example: Come ready to talk philosophy today!
location:
type: string
description: |-
The location of the group event (for example, a physical address or the name of a meeting
room).
maxLength: 255
example: New York Public Library, Cave Room
participants:
type: object
description: A list of participants to be included in the group event.
properties:
name:
type: string
description: The participant's name.
example: Leyah Miller
email:
type: string
description: The participant's email address.
example: leyah@example.com
is_organizer:
type: boolean
description: When `true`, indicates that the participant is the organizer for the event.
example: true
recurrence:
$ref: '#/components/schemas/group_event_recurrence'
title:
type: string
description: The name of the group event.
maxLength: 1024
example: Annual Philosophy Club Meeting
when:
type: object
description: An object representing the time and duration of the group event.
oneOf:
- $ref: '#/components/schemas/event_timespan'
- title: Read-only object
type: object
description: Read-only placeholder. Returned only in responses.
readOnly: true
group_event_update:
description: Update a group event
content:
application/json:
schema:
type: object
properties:
calendar_id:
type: string
description: The ID of the calendar to access.
example: primary
capacity:
type: integer
description: The maximum number of attendees allowed in the event.
minimum: 1
maximum: 500
default: 10
example: 50
conferencing:
type: object
description: |-
An object that lets you automatically create a conference, or enter conferencing details
manually.
oneOf:
- $ref: '#/components/schemas/event_conferencing_request'
- title: Read-only object
type: object
description: Read-only placeholder. Returned only in responses.
readOnly: true
description:
type: string
description: |-
A brief description of the group event (for example, its agenda). Nylas might return the
description as an HTML string, depending on how the provider formats it.
example: Come ready to talk philosophy today!
location:
type: string
description: |-
The location of the group event (for example, a physical address or the name of a meeting
room).
maxLength: 255
example: New York Public Library, Cave Room
participants:
type: object
description: A list of participants to be included in the group event.
properties:
name:
type: string
description: The participant's name.
example: Leyah Miller
email:
type: string
description: The participant's email address.
example: leyah@example.com
is_organizer:
type: boolean
description: When `true`, indicates that the participant is the organizer for the event.
example: true
recurrence:
$ref: '#/components/schemas/group_event_recurrence'
title:
type: string
description: The name of the event.
maxLength: 1024
example: Annual Philosophy Club Meeting
when:
type: object
description: An object representing the time and duration of the group event.
oneOf:
- $ref: '#/components/schemas/event_timespan'
- title: Read-only object
type: object
description: Read-only placeholder. Returned only in responses.
readOnly: true
import_group_event:
description: Import group event
content:
application/json:
schema:
type: array
items:
type: object
required:
- calendar_id
- event_id
properties:
calendar_id:
type: string
description: The ID of the calendar to access.
example: primary
capacity:
type: number
description: |-
The maximum number of attendees allowed in the event. If not specified, Nylas uses the
default capacity for your Configuration.
minimum: 1
maximum: 500
default: 10
example: 50
event_id:
type: string
description: ID of the event to import.
example: 5d3qmne77v32r8l4phyuksl2x
exceptions:
type: array
description: An array of events to create exceptions for.
items:
type: object
properties:
capacity:
type: number
description: |-
The maximum number of attendees allowed in the event. You must specify a `capacity`
for all events in `exceptions`.
example: 5
event_id:
type: string
description: ID of the to create an exception for.
example: 5d3qmne77v32r8l4phyuksl2x
participants:
type: array
description: |-
An array of participants to include in the event booking. If you don't specify at least
one participant, Nylas uses the event organizer instead.
items:
type: object
properties:
name:
type: string
description: The participant's full name.
example: Leyah Miller
email:
type: string
description: The participant's email address.
example: leyah@example.com
validate_timeslot:
description: Validate time slot
content:
application/json:
schema:
type: object
required:
- calendar_id
- start_time
- end_time
- event_id
properties:
calendar_id:
type: string
description: ID of the calendar to access.
example: primary
capacity:
type: number
description: |-
The maximum number of attendees for the event. If not specified, Nylas uses the default
capacity for your Configuration.
minimum: 1
maximum: 500
default: 10
example: 50
emails:
type: array
items:
type: string
description: A list of email addresses associated with the event's participants.
example:
- nyla@example.com
- leyah@example.com
event_id:
type: string
description: ID of the event to validate.
example: 5d3qmne77v32r8l4phyuksl2x
master_id:
type: string
description: The master event ID. Required when working with recurring events.
example: 5d3qmne77v32r8l4phyuksl2x
session_create:
description: Create a new scheduling session
content:
application/json:
schema:
type: object
properties:
configuration_id:
type: string
description: The ID of the Scheduler Configuration object for the session. If you're using `slug`, `configuration_id` is not required.
example: AAAA-BBBB-1111-2222
slug:
type: string
description: The slug of the Scheduler Configuration object for the session. You can use `slug` instead of `configuration_id`.
example: my-page-slug
time_to_live:
type: number
description: The time to live for the session in minutes. The maximum value is `30`.
default: 5
example: 10
booking_create:
content:
application/json:
schema:
$ref: '#/components/schemas/booking_create'
example:
start_time: '1708714800'
end_time: '1708722000'
participants:
- email: user@example.com
guest:
name: Guest
email: guest@example.com
booking_confirm:
content:
application/json:
schema:
$ref: '#/components/schemas/booking_confirm'
example:
salt: '-zgLLAuk_qtcsw'
status: cancelled
cancellation_reason: I am no longer available at this time.
securitySchemes:
ACCESS_TOKEN:
scheme: bearer
type: http
bearerFormat: NYLAS_ACCESS_TOKEN
description: |-
The Nylas **access token** for a specific grant. Issued as part of OAuth 2.1 flow token
exchange.
NYLAS_API_KEY:
scheme: bearer
type: http
bearerFormat: NYLAS_API_KEY
description: |-
The Nylas **API key** provides application-level access to APIs and all grants. You can
generate these from the Dashboard. Learn more about [authorizing requests](/docs/v3/auth/).
SCHEDULER_SESSION_TOKEN:
scheme: bearer
type: http
bearerFormat: Session ID
description: The Nylas Scheduler **session ID** that Scheduler UI Components use to authorize API requests.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
examples:
OK:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
'202':
description: Email Send Accepted
content:
application/json:
schema:
type: object
required:
- grant_id
- data
- request_id
- schedule_id
properties:
grant_id:
type: string
request_id:
type: string
data:
$ref: '#/components/schemas/message_send_response'
examples:
example1:
description: Save a scheduled message with an Attachment as a draft
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
schedule_id: 17d0281e-0c25-4ad1-a275-639c74f5f6a4
send_at: 1671234087
use_draft: true
grant_id: your grant_id
data:
subject: Sending Emails with Nylas
body: Nylas API v3 Test!
from:
- name: John Doe
email: johnn.doe@example.com
to:
- name: Jane Doe
email: jane.doe@example.com
cc:
- name: Nylas
email: nylas@example.com
bcc:
- name: Nylas
email: nylas@example.com
attachments:
- content_id: HASKDJhiuahsdjlkhKJAsd=
content_type: text/plain
content_disposition: inline
filename: myfile.txt
example2:
description: Send a scheduled message with many recipients
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
schedule_id: 17d0281e-0c25-4ad1-a275-639c74f5f6a4
send_at: 1671234087
use_draft: false
grant_id: your grant_id
data:
subject: Sending Emails with Nylas
body: Nylas API v3 Test!
from:
- name: John Doe
email: johnn.doe@example.com
to:
- name: Jane Doe
email: jane.doe@example.com
- name: Scott
email: scott@example.com
- name: Tom
email: tom@example.com
attachments:
- content_id: HASKDJhiuahsdjlkhKJAsd=
content_type: text/plain
filename: myfile.txt
content_disposition: attachment
'400':
description: Bad Request
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
provider_error:
type: object
description: The error from the provider.
examples:
Bad Request:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: invalid_request_error
message: error parsing request body
provider_error:
code: TargetIdShouldNotBeMeOrWhitespace
message: Id is malformed.
Invalid Idempotency-Key:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: api.invalid_idempotency_key
message: Idempotency-Key must be 256 characters or fewer.
'401':
description: Unauthorized
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
provider_error:
type: object
description: The error from the provider.
examples:
Unauthorized:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: unauthorized
message: Unauthorized
provider_error:
code: 401
message: Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
'403':
description: Unauthorized
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: ID of the request
error:
type: object
description: Response error object.
properties:
type:
type: string
description: Error Type
message:
type: string
description: Error Message
provider_error:
type: object
description: Provider Error
examples:
Insufficient Scopes:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: insufficient_scopes
message: missing provider scopes required to send email
'404':
description: Not Found
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
provider_error:
type: object
description: The raw error from the provider, if available
properties:
code:
type: string
message:
type: string
examples:
Not Found:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: not_found_error
message: requested object not found
provider_error:
code: MailboxNotEnabledForRESTAPI
message: The mailbox is either inactive, soft-deleted, or is hosted on-premise.
'409':
description: Conflict
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
example: conflict
message:
type: string
description: The error message.
example: This request isn't supported for the Notetaker's current state.
'429':
description: Rate Limit
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
examples:
Not Found:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: rate_limit_error
message: Too many requests, please try again shortly.
'504':
description: Provider Failure
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
examples:
Provider Failure:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: provider_error
message: Provider request timed out.
200-delete:
description: Delete Succeeded
content:
application/json:
schema:
type: object
required:
- request_id
properties:
request_id:
type: string
description: ID of the request.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
get-api-keys-200:
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: array
properties:
api_key:
type: object
description: The API key.
properties:
application_id:
type: string
description: The ID of the application the API key is associated with.
created_at:
type: number
description: When the API key was created, in seconds using the Unix timestamp format.
expires_at:
type: number
description: When the API key will expire, in seconds using the Unix timestamp format.
expires_in:
type: number
description: How long the API key is valid, in seconds.
id:
type: string
description: The API key ID.
name:
type: string
description: The name of the API key.
permissions:
type: array
description: An array of permissions associated with the API key.
items:
type: string
status:
type: string
description: The status of the API key.
updated_at:
type: number
description: When the API key was last updated, in seconds using the Unix timestamp format.
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
api_key:
application_id: ad410018-d306-43f9-8361-fa5d7b2172e0
created_at: 1617817109
expires_at: 1619385186
expires_in: 3600
name: Leyah's API key
permissions:
- all
status: active
updated_at: 1617817109
get-api-key-200:
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
application_id:
type: string
description: The ID of the application the API key is associated with.
created_at:
type: number
description: When the API key was created, in seconds using the Unix timestamp format.
expires_at:
type: number
description: When the API key will expire, in seconds using the Unix timestamp format.
expires_in:
type: number
description: How long the API key is valid, in seconds.
id:
type: string
description: The API key ID.
name:
type: string
description: The name of the API key.
permissions:
type: array
description: An array of permissions associated with the API key.
items:
type: string
status:
type: string
description: The status of the API key.
updated_at:
type: number
description: When the API key was last updated, in seconds using the Unix timestamp format.
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
application_id: ad410018-d306-43f9-8361-fa5d7b2172e0
created_at: 1617817109
expires_at: 1619385186
expires_in: 3600
name: Leyah's API key
permissions:
- all
status: active
updated_at: 1617817109
get_200:
description: Destinations Returned
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: A unique identifier for the webhook destination.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the webhook destination.
example: Production webhook destination
trigger_types:
$ref: '#/components/schemas/trigger_types'
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
status:
type: string
description: The status of the new destination.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: |-
The email addresses that Nylas notifies when a webhook is down for a while. See
[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for
details.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
request_id:
type: string
description: The ID for each request.
get_400:
description: Destination not returned
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70001'
message:
type: string
description: A human readable message with details about the error.
example: application_id.required
request_id:
type: string
description: The ID for each request.
create_200:
description: Webhook Destination Created
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the webhook destination.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the webhook destination.
example: Production webhook destination
trigger_types:
$ref: '#/components/schemas/trigger_types'
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
webhook_secret:
type: string
description: A secret value used to encode the `x-nylas-signature` header on webhook requests.
example: 41dD3-nXTUfebYuk81Gr
status:
type: string
description: The status of the new destination. This will always be "active" if Nylas successfully created the destination. If you need to pause the destination, use the [Update webhook destination](#put-/v3/webhooks/-id-) method to change the status to `pause`.
enum:
- active
notification_email_addresses:
type: array
items:
type: string
description: |-
The email addresses that Nylas notifies when a webhook is down for a while. See
[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for
details.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
request_id:
type: string
description: The request ID for each request.
create_400:
description: Destination not created
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70005'
message:
type: string
description: A human-readable message with details about the error.
example: 'unable.verify.webhook_url : status is not ok, got 404'
request_id:
type: string
description: The ID of the request.
get_by_id_200:
description: Destinations Returned
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the webhook destination.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the webhook destination.
example: Production webhook destination
trigger_types:
type: array
items:
type: string
enum:
- calendar.created
- calendar.updated
- calendar.deleted
- event.created
- event.updated
- event.deleted
- grant.created
- grant.updated
- grant.deleted
- grant.expired
- message.send_success
- message.send_failed
- message.bounce_detected
- message.created
- message.updated
- contact.updated
- contact.deleted
- folder.created
- folder.updated
- folder.deleted
- message.opened
- message.link_clicked
- thread.replied
description: |-
The event that triggers the webhook notification. See the
[notification schemas](/docs/reference/notifications/) for details about
each trigger type.
See the [Grants](/docs/reference/api/manage-grants/),
[Calendar](/docs/reference/api/calendar/), [Events](/docs/reference/api/events/), and
[Messages](/docs/reference/api/messages/) references for information on how to trigger
each event type.
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
status:
type: string
description: The status of the new destination.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: |-
The email addresses that Nylas notifies when a webhook is down for a while. See
[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for
details.
example:
- jane@example.com
- joe@example.com
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the webhook destination was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the webhook destination was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The ID for each request.
update_200:
description: Destination Updated
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the webhook destination.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the webhook destination.
example: Production webhook destination
trigger_types:
$ref: '#/components/schemas/trigger_types'
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
status:
type: string
description: The status of the new destination.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: |-
The email addresses that Nylas notifies when a webhook is down for a while. See
[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for
details.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the webhook destination was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the webhook destination was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The ID for each request.
update_400:
description: Unable to update Pub/Sub channel
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70000'
message:
type: string
description: A human readable message with details about the error.
example: 'destination.id.not.found : record not found'
request_id:
type: string
description: The unique ID of the request that generated this response.
delete_200:
description: Destination Deleted
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
status:
type: string
enum:
- success
request_id:
type: string
description: The ID for each request.
delete_400:
description: Notification channel not deleted
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70000'
message:
type: string
description: A human readable message with details about the error.
example: 'destination.id.not.found : record not found'
request_id:
type: string
description: The unique ID of the request that generated this response.
rotate_secret_200:
description: Webhook Secret Updated
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the webhook destination.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the webhook destination.
example: Production webhook destination
trigger_types:
$ref: '#/components/schemas/trigger_types'
webhook_url:
type: string
description: The URL to send webhooks to.
example: https://example.com/webhooks
webhook_secret:
type: string
description: A secret value used to encode the `x-nylas-signature` header on webhook requests.
example: 41dD3-nXTUfebYuk81Gr
status:
type: string
description: The status of the new destination.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: |-
The email addresses that Nylas notifies when a webhook is down for a while. See
[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for
details.
example:
- jane@example.com
- joe@example.com
request_id:
type: string
description: The request ID for each request.
get_mock_payload_200:
description: Webhook Payload Returned
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
data:
type: object
description: This object is an example payload that Nylas sends to your webhook destination
request_id:
type: string
description: The ID for each request.
send_test_event_200:
description: Test event sent
content:
application/json:
schema:
type: object
properties:
data:
type: string
description: Indicates if the test event succeeded or failed.
example: success
request_id:
type: string
description: The ID for each request.
get_pubsub_200:
description: Get Pub/Sub channel information
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: A unique identifier for the Pub/Sub notification channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Pub/Sub notification channel.
example: Production Pub/Sub channel for Email notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The status of the new destination.
enum:
- active
- paused
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
request_id:
type: string
description: The unique ID of the request that generated this response.
get_pubsub_400:
description: Unable to get Pub/Sub channel information
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70001'
message:
type: string
description: A human readable message with details about the error.
example: 'invalid.input.format : topic is required'
request_id:
type: string
description: The unique ID of the request that generated this response.
create_pubsub_200:
description: Pub/Sub channel created
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Pub/Sub notification channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Pub/Sub notification channel.
example: Production Pub/Sub channel for Grant notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The status of the Pub/Sub channel. When you first create a new channel, Nylas sets it to "active".
enum:
- active
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
request_id:
type: string
description: The unique ID of the request that generated this response.
create_pubsub_400:
description: Unable to create Pub/Sub channel
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70005'
message:
type: string
description: A human-readable message with details about the error.
example: 'invalid.input.format : topic is required'
request_id:
type: string
description: The unique ID of the request that generated this response.
get_pubsub_by_id_200:
description: Get specific Pub/Sub channel information
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Pub/Sub channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Pub/Sub channel.
example: Production Pub/Sub for Event updates
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The deliverability status of the Pub/Sub channel.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the Pub/Sub channel was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the Pub/Sub channel was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The unique ID of the request that generated this response.
update_pubsub_200:
description: Pub/Sub channel updated
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Pub/Sub channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Pub/Sub channel.
example: Production Pub/Sub channel
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Google Pub/Sub topic that Nylas sends notifications to.
example: projects/your-project-id/topics/your-topic-id
status:
type: string
description: The deliverability status of the Pub/Sub channel.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Pub/Sub channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas compresses notification payloads using gzip before delivering them.
example: false
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the Pub/Sub channel was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the Pub/Sub channel was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The unique ID of the request that generated this response.
update_pubsub_400:
description: Pub/Sub channel not updated
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70000'
message:
type: string
description: A human readable message with details about the error.
example: 'invalid.input.format : topic is required"'
request_id:
type: string
description: The unique ID of the request that generated this response.
get_sns_200:
description: Get Amazon SNS channel information
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: A unique identifier for the Amazon SNS notification channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Amazon SNS notification channel.
example: Production SNS channel for Email notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Amazon SNS topic ARN that Nylas sends notifications to.
example: arn:aws:sns:us-east-1:123456789012:my-topic
role_arn:
type: string
description: The ARN of the IAM role that Nylas assumes to publish messages to the SNS topic.
example: arn:aws:iam::123456789012:role/nylas-sns-role
status:
type: string
description: The status of the Amazon SNS channel.
enum:
- active
- paused
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Amazon SNS channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas gzip-compresses and then base64-encodes notification payloads before delivering them.
example: false
request_id:
type: string
description: The unique ID of the request that generated this response.
get_sns_400:
description: Unable to get Amazon SNS channel information
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70001'
message:
type: string
description: A human readable message with details about the error.
example: 'invalid.input.format : topic is required'
request_id:
type: string
description: The unique ID of the request that generated this response.
create_sns_200:
description: Amazon SNS channel created
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Amazon SNS notification channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Amazon SNS notification channel.
example: Production SNS channel for Grant notifications
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Amazon SNS topic ARN that Nylas sends notifications to.
example: arn:aws:sns:us-east-1:123456789012:my-topic
role_arn:
type: string
description: The ARN of the IAM role that Nylas assumes to publish messages to the SNS topic.
example: arn:aws:iam::123456789012:role/nylas-sns-role
status:
type: string
description: The status of the Amazon SNS channel. When you first create a new channel, Nylas sets it to "active".
enum:
- active
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Amazon SNS channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas gzip-compresses and then base64-encodes notification payloads before delivering them.
example: false
request_id:
type: string
description: The unique ID of the request that generated this response.
create_sns_400:
description: Unable to create Amazon SNS channel
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70005'
message:
type: string
description: A human-readable message with details about the error.
example: 'invalid.input.format : topic is required'
request_id:
type: string
description: The unique ID of the request that generated this response.
get_sns_by_id_200:
description: Get specific Amazon SNS channel information
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Amazon SNS channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Amazon SNS channel.
example: Production SNS channel for Event updates
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Amazon SNS topic ARN that Nylas sends notifications to.
example: arn:aws:sns:us-east-1:123456789012:my-topic
role_arn:
type: string
description: The ARN of the IAM role that Nylas assumes to publish messages to the SNS topic.
example: arn:aws:iam::123456789012:role/nylas-sns-role
status:
type: string
description: The deliverability status of the Amazon SNS channel.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Amazon SNS channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas gzip-compresses and then base64-encodes notification payloads before delivering them.
example: false
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the Amazon SNS channel was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the Amazon SNS channel was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The unique ID of the request that generated this response.
update_sns_200:
description: Amazon SNS channel updated
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: A unique identifier for the Amazon SNS channel.
example: UMWjAjMeWQ4D8gYF2moonK4486
description:
type: string
description: A human-readable description of the Amazon SNS channel.
example: Production SNS channel
trigger_types:
$ref: '#/components/schemas/trigger_types'
topic:
type: string
description: The Amazon SNS topic ARN that Nylas sends notifications to.
example: arn:aws:sns:us-east-1:123456789012:my-topic
role_arn:
type: string
description: The ARN of the IAM role that Nylas assumes to publish messages to the SNS topic.
example: arn:aws:iam::123456789012:role/nylas-sns-role
status:
type: string
description: The deliverability status of the Amazon SNS channel.
enum:
- active
- pause
- failing
- failed
notification_email_addresses:
type: array
items:
type: string
description: The email addresses that Nylas notifies if delivery to the Amazon SNS channel fails.
example:
- jane@example.com
- joe@example.com
compressed_delivery:
type: boolean
description: If `true`, Nylas gzip-compresses and then base64-encodes notification payloads before delivering them.
example: false
status_updated_at:
type: integer
description: The time the `status` field was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
created_at:
type: integer
description: The time the Amazon SNS channel was created, represented as a Unix timestamp in seconds.
example: 1234567890
updated_at:
type: integer
description: The time the Amazon SNS channel was last updated, represented as a Unix timestamp in seconds.
example: 1234567890
request_id:
type: string
description: The unique ID of the request that generated this response.
update_sns_400:
description: Amazon SNS channel not updated
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: An alphanumeric code that represents the error type.
example: '70000'
message:
type: string
description: A human readable message with details about the error.
example: 'invalid.input.format : topic is required'
request_id:
type: string
description: The unique ID of the request that generated this response.
messages:
description: Messages response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/message'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- body: Hello, I just sent a message using Nylas!
cc:
- name: Arya Stark
email: arya.stark@example.com
date: 1635355739
attachments:
- content_type: text/calendar
id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_type: application/ics
filename: invite.ics
id: 70jcsv367jaiavt4njeu4xswg
size: 1708
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
- name: Daenerys Targaryen
email: daenerys.t@example.com
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
id: 5d3qmne77v32r8l4phyuksl2x
object: message
reply_to:
- name: Daenerys Targaryen
email: daenerys.t@example.com
snippet: Hello, I just sent a message using Nylas!
starred: true
subject: Hello from Nylas!
thread_id: 1t8tv3890q4vgmwq6pmdwm8qgsaer
to:
- name: Jon Snow
email: j.snow@example.com
unread: true
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
message:
description: Message response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/message'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
body: Hello, I just sent a message using Nylas!
cc:
- name: Arya Stark
email: arya.stark@example.com
date: 1635355739
attachments:
- content_type: text/calendar
id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_type: application/ics
filename: invite.ics
id: 70jcsv367jaiavt4njeu4xswg
size: 1708
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
- name: Daenerys Targaryen
email: daenerys.t@example.com
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
id: 5d3qmne77v32r8l4phyuksl2x
object: message
reply_to:
- name: Daenerys Targaryen
email: daenerys.t@example.com
snippet: Hello, I just sent a message using Nylas!
starred: true
subject: Hello from Nylas!
thread_id: 1t8tv3890q4vgmwq6pmdwm8qgsaer
to:
- name: Jon Snow
email: j.snow@example.com
unread: true
messages-clean:
description: Clean message response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/message'
- properties:
conversation:
type: string
description: |-
The cleaned message body. If `html_as_markdown` is `true`, the text is
Markdown-formatted. Otherwise, Nylas returns plain text.
example: Hello, I just sent a message using Nylas!
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- body: "<div dir=\"ltr\"><div>Hello, I just sent a message using Nylas!\_<br></div><img src=\"cid:ii_ltppe5ph0\" alt=\"Nylas-Logo-Stacked-Blue_.png\" width=\"540\" height=\"464\"><br><div dir=\"ltr\" class=\"gmail_signature\" data-smartmail=\"gmail_signature\"><div dir=\"ltr\"></div></div></div>\r\n"
cc:
- name: Arya Stark
email: arya.stark@example.com
date: 1635355739
attachments:
- is_inline: true
id: v0:TnlsYXMtTG9nby1TdGFja2VkLUJsdWVfLnBuZw==:aW1hZ2UvcG5nOyBuYW1lPSJOeWxhcy1Mb2dvLVN0YWNrZWQtQmx1ZV8ucG5nIg==:26044
grant_id: nylas_test_9
filename: Nylas-Logo-Stacked-Blue_.png
content_type: image/png; name="Nylas-Logo-Stacked-Blue_.png"
content_disposition: inline; filename="Nylas-Logo-Stacked-Blue_.png"
content_id: ii_ltppe5ph0
size: 26044
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
- name: Daenerys Targaryen
email: daenerys.t@example.com
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
id: 5d3qmne77v32r8l4phyuksl2x
object: message
reply_to:
- name: Daenerys Targaryen
email: daenerys.t@example.com
snippet: Hello, I just sent a message using Nylas!
starred: true
subject: Hello from Nylas!
thread_id: 1t8tv3890q4vgmwq6pmdwm8qgsaer
to:
- name: Jon Snow
email: j.snow@example.com
unread: true
conversation: Hello, I just sent a message using Nylas!
200_messages_send:
description: 200 OK
content:
application/json:
schema:
type: object
required:
- grant_id
- data
- request_id
properties:
grant_id:
type: string
request_id:
type: string
data:
$ref: '#/components/schemas/message_send_response'
examples:
Send with an attachment:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
grant_id: your grant_id
data:
subject: Sending Emails with Nylas
body: Nylas API v3 Test!
from:
- name: John Doe
email: john.doe@example.com
to:
- name: Jane Doe
email: jane.doe@example.com
cc:
- name: Nylas
email: nylas@example.com
bcc:
- name: Nylas
email: nylas@example.com
attachments:
- id: 4kj2jrcoj9ve5j9yxqz5cuv98
content_id: HASKDJhiuahsdjlkhKJAsd=
content_type: text/plain
filename: myfile.txt
schedule_id: ''
Simple Send to Two Recipients:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
grant_id: your grant_id
data:
subject: Sending Emails with Nylas
body: Nylas API v3 Test!
from:
- name: John Doe
email: john.doe@example.com
to:
- name: Jane Doe
email: jane.doe@example.com
- name: Scott
email: scott@example.com
- name: Tom
email: tom@example.com
attachments:
- content_id: HASKDJhiuahsdjlkhKJAsd=
content_type: text/plain
filename: myfile.txt
reply_to_message_id: ''
schedule_id: ''
Schedule a Send to Two Recipients:
value:
request_id: 9fb8efab-e4c0-4e68-bbd9-948d6be65402
grant_id: your grant_id
data:
subject: Sending Emails with Nylas
body: Nylas API v3 Test!
from:
- name: John Doe
email: john.doe@example.com
to:
- name: Jane Doe
email: jane.doe@example.com
- name: Scott
email: scott@example.com
- name: Tom
email: tom@example.com
reply_to_message_id: ''
send_at: 123456789
use_draft: false
schedule_id: ''
Send with a reply-to address:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
grant_id: your grant_id
data:
subject: Sending Emails with Nylas
body: Nylas API v3 Test!
from:
- name: John Doe
email: john.doe@example.com
to:
- name: Jane Doe
email: jane.doe@example.com
- name: Scott
email: scott@example.com
- name: Tom
email: tom@example.com
attachments:
- id: 4kj2jrcoj9ve5j9yxqz5cuv98
content_id: HASKDJhiuahsdjlkhKJAsd=
content_type: text/plain
filename: myfile.txt
schedule_id: ''
reply_to_message_id: <the message ID you replied to>
409_idempotent:
description: Conflict. Returned when an `Idempotency-Key` conflicts with an existing entry.
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
examples:
Different payload, same key:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: api.invalid_idempotent_request
message: The Idempotency-Key was reused with a different request payload. Use a different key, or match the original payload.
Concurrent request in flight:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: api.concurrent_idempotent_request
message: A request with the same Idempotency-Key is currently in progress. Wait a moment and retry with the same key.
200_schedules:
description: Schedule(s) Successfully Retrieved
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Schedules'
examples:
Retrieved two schedules:
value:
- schedule_id: 8cd56334-6d95-432c-86d1-c5dab0ce98be
status:
code: pending
description: schedule send awaiting send at time
- schedule_id: rb856334-6d95-432c-86d1-c5dab0ce98be
status:
code: success
description: schedule send succeeded
close_time: 1690579819
200_schedule_id:
description: Schedule(s) Retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Schedules'
examples:
Retrieved two schedules:
value:
schedule_id: 8cd56334-6d95-432c-86d1-c5dab0ce98be
status:
code: pending
description: schedule send awaiting send at time
202_schedules_delete:
description: Schedule Deleted
content:
application/json:
schema:
type: object
required:
- data
- request_id
properties:
request_id:
type: string
example: 9c2ce8cd-d6e0-4206-a1d0-703f16880061
data:
type: object
properties:
message:
type: string
example: requested cancelation for workflow
examples:
Succesfully Request Schedule Deletion:
value:
request_id: 9c2ce8cd-d6e0-4206-a1d0-703f16880061
data:
message: requested cancelation for workflow
smart_compose_200:
description: Returns a suggestion for a message
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/smart_compose_suggestion'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
suggestion: |-
Dear John,
I hope this email finds you well. I wanted to reach out and inform you about an exciting upcoming project that we will be working on together. This project has the potential to be a game-changer for our company, and I believe your expertise and skills will be invaluable to its success. I look forward to discussing the project with you further and hearing your input and ideas. Let's make this project a resounding success!
Best regards,
[Your Name]
text/event-stream:
schema:
type: object
format: event-stream
properties:
suggestion:
type: string
smart_compose_400:
description: Bad Request
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: ID of the request
error:
type: object
description: Response error object.
properties:
type:
type: string
description: Error Type
message:
type: string
description: Error Message
examples:
Invalid Request:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: invalid_request_error
message: invalid request
Prompt Required:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: prompt_required_error
message: prompt is required
Prompt Not Allowed:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: prompt_not_allowed_error
message: prompt is not allowed
Message ID Required:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: message_id_required_error
message: message ID is required
Grant ID Required:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: grant_id_required_error
message: grant ID is required
Unknown Message Sender Error:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: unknown_message_sender_error
message: could not determine message sender
smart_compose_422:
description: Validation Error
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: ID of the request
error:
type: object
description: Response error object.
properties:
type:
type: string
description: Error Type
message:
type: string
description: Error Message
details:
type: array
items:
type: object
properties:
loc:
title: Location
type: array
items:
anyOf:
- type: string
- type: integer
msg:
title: Message
type: string
type:
title: Error Type
type: string
examples:
Validation Error:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: validation_error
message: validation error
details:
- loc:
- path
- item_id
msg: value is not a valid integer
type: type_error.integer
smart_compose_500:
description: Unexpected Error
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: ID of the request
error:
type: object
description: Response error object.
properties:
type:
type: string
description: Error Type
message:
type: string
description: Error Message
examples:
Unexpected Error:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: unexpected_error
message: an unexepcted error has occurred
signatures:
description: Signatures
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/signature'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- id: sig_abc123
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
name: Work Signature
body: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p></div>
object: signature
created_at: 1706367600
updated_at: 1706367600
- id: sig_def456
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
name: Personal Signature
body: <div><p>Nick B.</p><p>Sent from my phone</p></div>
object: signature
created_at: 1706367700
updated_at: 1706367700
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
signature:
description: Signature
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/signature'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
id: sig_abc123
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
name: Work Signature
body: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p><p><a href="mailto:nick@nylas.com">nick@nylas.com</a></p></div>
object: signature
created_at: 1706367600
updated_at: 1706367600
drafts:
description: Drafts
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/draft'
example:
Draft response example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- body: Hello, I just sent a message using Nylas!
cc:
- email: arya.stark@example.com
attachments:
- content_type: text/calendar
id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_type: application/ics
filename: invite.ics
id: 70jcsv367jaiavt4njeu4xswg
size: 1708
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
- name: Daenerys Targaryen
email: daenerys.t@example.com
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
id: 5d3qmne77v32r8l4phyuksl2x
object: message
reply_to:
- name: Daenerys Targaryen
email: daenerys.t@example.com
snippet: Hello, I just sent a message using Nylas!
starred: true
subject: Hello from Nylas!
thread_id: 1t8tv3890q4vgmwq6pmdwm8qgsaer
to:
- name: Jon Snow
email: j.snow@example.com
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
draft:
description: Draft
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/draft'
example:
Draft response example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
body: Hello, I just sent a message using Nylas!
cc:
- email: arya.stark@example.com
attachments:
- content_type: text/calendar
id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_type: application/ics
filename: invite.ics
id: 70jcsv367jaiavt4njeu4xswg
size: 1708
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
- name: Daenerys Targaryen
email: daenerys.t@example.com
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
id: 5d3qmne77v32r8l4phyuksl2x
object: draft
reply_to:
- name: Daenerys Targaryen
email: daenerys.t@example.com
snippet: Hello, I just sent a message using Nylas!
starred: true
subject: Hello from Nylas!
thread_id: 1t8tv3890q4vgmwq6pmdwm8qgsaer
to:
- name: Jon Snow
email: j.snow@example.com
threads:
description: Threads response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: object
properties:
threads:
type: array
items:
$ref: '#/components/schemas/thread'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
threads:
- grant_id: ca8f1733-6063-40cc-a2e3-ec7274abef11
id: 7ml84jdmfnw20sq59f30hirhe
object: thread
has_attachments: false
has_drafts: false
earliest_message_date: 1634149514
latest_message_received_date: 1634832749
latest_message_sent_date: 1635174399
participants:
- email: daenerys.t@example.com
name: Daenerys Targaryen
- email: dr.crumpler@example.com
name: Rebecca Lee Crumpler
snippet: jnlnnn --Sent with Nylas
starred: false
subject: Dinner Wednesday?
unread: false
message_ids:
- njeb79kFFzli09
- 998abue3mGH4sk
draft_ids:
- a809kmmoW90Dx
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
latest_draft_or_message:
body: Hello, I just sent a message using Nylas!
cc:
- name: Arya Stark
email: arya.stark@example.com
date: 1635355739
attachments:
- content_id: YXR0YWNoDQoNCi0tLS0tLS0tLS0gRm9yd2FyZGVkIG1lc3NhZ2UgL=
content_type: text/calendar
id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_type: application/ics
filename: invite.ics
id: 70jcsv367jaiavt4njeu4xswg
size: 1708
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
- name: Daenerys Targaryen
email: daenerys.t@example.com
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
id: njeb79kFFzli09
object: message
reply_to:
- name: Daenerys Targaryen
email: daenerys.t@example.com
snippet: Hello, I just sent a message using Nylas!
starred: true
subject: Hello from Nylas!
thread_id: 1t8tv3890q4vgmwq6pmdwm8qgsaer
to:
- name: Jon Snow
email: j.snow@example.com
unread: true
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
thread:
description: Thread response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/thread'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
grant_id: ca8f1733-6063-40cc-a2e3-ec7274abef11
id: 7ml84jdmfnw20sq59f30hirhe
object: thread
has_attachments: false
has_drafts: false
earliest_message_date: 1634149514
latest_message_received_date: 1634832749
latest_message_sent_date: 1635174399
participants:
- email: daenerys.t@example.com
name: Daenerys Targaryen
- email: dr.crumpler@example.com
name: Rebecca Lee Crumpler
snippet: jnlnnn --Sent with Nylas
starred: false
subject: Dinner Wednesday?
unread: false
message_ids:
- njeb79kFFzli09
- 998abue3mGH4sk
draft_ids:
- a809kmmoW90Dx
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
latest_draft_or_message:
body: Hello, I just sent a message using Nylas!
cc:
- name: Arya Stark
email: arya.stark@example.com
date: 1635355739
attachments:
- filename: YXR0YWNoDQoNCi0tLS0tLS0tLS0gRm9yd2FyZGVkIG1lc3NhZ2UgL=
content_type: text/calendar
content_id: 4kj2jrcoj9ve5j9yxqz5cuv98
size: 1708
- content_type: application/ics
filename: invite.ics
content_id: 70jcsv367jaiavt4njeu4xswg
size: 1708
folders:
- 8l6c4d11y1p4dm4fxj52whyr9
- d9zkcr2tljpu3m4qpj7l2hbr0
from:
- name: Daenerys Targaryen
email: daenerys.t@example.com
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
id: njeb79kFFzli09
object: message
reply_to:
- name: Daenerys Targaryen
email: daenerys.t@example.com
snippet: Hello, I just sent a message using Nylas!
starred: true
subject: Hello from Nylas!
thread_id: 1t8tv3890q4vgmwq6pmdwm8qgsaer
to:
- name: Jon Snow
email: j.snow@example.com
unread: true
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
folders:
description: Returned all folders
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/folder'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- id: SENT
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
name: SENT
system_folder: true
- id: INBOX
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
name: INBOX
system_folder: true
- id: Label_2
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
name: New Label with Color
system_folder: false
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
folder:
description: Folder
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/folder'
example:
Folder response example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
id: SENT
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
name: SENT
system_folder: true
attributes:
- \Sent
attachment:
description: Attachment metadata
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/attachment_metadata'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
content_type: image/png; name="pic.png"
content_disposition: inline; filename="pic.png"
filename: pic.png
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
id: 185e56cb50e12e82
is_inline: true
size: 13068
content_id: <ce9b9547-9eeb-43b2-ac4e-58768bdf04e4>
attachment_file:
description: |-
The attached file as a binary stream (`application/octet-stream`). Use the
[Return Attachment Metadata endpoint](/docs/reference/api/attachments/get-attachments-id/)
to get the MIME type of the file.
content:
application/octet-stream:
schema:
type: string
format: binary
example: some binary data
calendars:
description: Calendars Response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/calendar_common'
example:
Calendars response example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- description: Description of my new calendar
hex_color: '#039BE5'
hex_foreground_color: '#039BE5'
id: 5d3qmne77v32r8l4phyuksl2x
is_owned_by_user: true
is_primary: true
location: Los Angeles, CA
metadata:
your-key: value
name: My New Calendar
object: calendar
owner_email: nyla@example.com
read_only: false
timezone: America/Los_Angeles
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
calendar:
description: Calendar Response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/calendar'
example:
Calendar response example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
description: Description of my new calendar
hex_color: '#039BE5'
hex_foreground_color: '#039BE5'
id: 5d3qmne77v32r8l4phyuksl2x
is_owned_by_user: true
is_primary: true
location: Los Angeles, CA
metadata:
your-key: value
name: My New Calendar
object: calendar
owner_email: nyla@example.com
read_only: false
timezone: America/Los_Angeles
notetaker:
id: 5fa64c92-e840-4357-86b9-2aa364d35b87
name: Nylas Notetaker
meeting_settings:
video_recording: true
audio_recording: true
transcription: true
transcription_settings:
expected_languages:
- en
- es
fallback_language: en
rules:
event_selection:
- internal
participant_filter:
participants_gte: 5
participants_lte: 10
availability:
description: Return availability
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/availability_response'
examples:
Return round-robin scheduling:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
order:
- nyla@example.com
- leyah@example.com
time_slots:
- emails:
- leyah@example.com
- nyla@example.com
start_time: 1659367800
end_time: 1659369600
- emails:
- nyla@example.com
start_time: 1659376800
end_time: 1659378600
Return group Configuration availability:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
time_slots:
- emails:
- leyah@example.com
- nyla@example.com
start_time: 1659367800
end_time: 1659369600
capacity: 100
event_id": AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AeRryRUlhMECYNfAbiKd_mQABCjy6hAAA_20250409T193000Z
calendar_id: primary
master_id: AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AeRryRUlhMECYNfAbiKd_mQABCjy6hAAA
- emails:
- nyla@example.com
start_time: 1659376800
end_time: 1659378600
capacity: 100
event_id": AAkALgAAAAAAHYQDEapmEc2byACqAC-EtegrfdsczUlhMECYNfAbiKd_mQABCjy6hAAA_20250409T193000Z
calendar_id: primary
master_id: AAkALgAAAAAAHYQDEapmEc2byACqAC-EfsrgdfeasECYNfAbiKd_mQABCjy6hAAA
freebusy:
description: Free/Busy Response
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The request ID.
data:
type: array
description: |-
An array of free/busy schedules. Nylas returns one free/busy schedule for each email address
specified in the request.
items:
type: object
properties:
email:
type: string
description: The participant's email address.
time_slots:
type:
- array
- 'null'
description: |-
An array of busy time slots. This field may be `null` when a free/busy lookup returns
an error for a specific email address.
items:
type: object
properties:
start_time:
type: integer
description: The beginning of a time slot, in seconds using the Unix timestamp format.
end_time:
type: integer
description: The end of a time slot, in seconds using the Unix timestamp format.
status:
type: string
description: The status of the time slot.
object:
type: string
description: The object type (in this case, always `time_slot`).
error:
type: string
description: |-
If Nylas encounters an error fetching data for a participant, this field contains
a description of the error.
object:
type: string
description: |-
The object type. If the request succeeds, the value is `free_busy`. If the request
fails, the value is `error`.
enum:
- free_busy
- error
examples:
free_busy_response:
value:
request_id: dd3ec9a2-8f15-403d-b269-32b1f1beb9f5
data:
- email: user1@example.com
time_slots:
- start_time: 1690898400
end_time: 1690902000
status: busy
object: time_slot
- start_time: 1691064000
end_time: 1691067600
status: busy
object: time_slot
object: free_busy
- email: user2@example.com
error: Unable to resolve e-mail address user2@example.com to an Active Directory object.
object: error
events:
description: Events Response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/event_common'
example:
Events response example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- busy: true
calendar_id: 7d93zl2palhxqdy6e5qinsakt
conferencing:
provider: Zoom Meeting
details:
meeting_code: code-123456
password: password-123456
url: https://zoom.us/j/1234567890?pwd=1234567890
created_at: 1661874192
description: Description of my new calendar
hide_participants: false
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
html_link: https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Ef3feD2VuM29fMjAyMjA2MjdUMjIwMDAwWiBoYWxsYUBueWxhcy5jb20
id: 5d3qmne77v32r8l4phyuksl2x
location: Roller Rink
metadata:
your_key: your_value
object: event
organizer:
email: organizer@example.com
name: ''
participants:
- comment: Aristotle
email: aristotle@example.com
name: Aristotle
phone_number: +1 23456778
status: maybe
read_only: false
reminders:
use_default: false
overrides:
- reminder_minutes: 10
reminder_method: email
status: confirmed
title: Birthday Party
updated_at: 1661874192
visibility: private
when:
start_time: 1661874192
end_time: 1661877792
start_timezone: America/New_York
end_timezone: America/New_York
notetaker:
id: notetaker-123456
name: Nylas Notetaker
meeting_settings:
video_recording: true
audio_recording: true
transcription: true
transcription_settings:
expected_languages:
- en
- es
fallback_language: en
summary: true
action_items: true
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
event:
description: Event Response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/event'
example:
Event response example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
busy: true
calendar_id: 7d93zl2palhxqdy6e5qinsakt
conferencing:
provider: Zoom Meeting
details:
meeting_code: code-123456
password: password-123456
url: https://zoom.us/j/1234567890?pwd=1234567890
created_at: 1661874192
description: Description of my new calendar
hide_participants: false
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
html_link: https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Ef3feD2VuM29fMjAyMjA2MjdUMjIwMDAwWiBoYWxsYUBueWxhcy5jb20
id: 5d3qmne77v32r8l4phyuksl2x
location: Roller Rink
metadata:
your_key: your_value
object: event
organizer:
email: organizer@example.com
name: ''
participants:
- comment: Aristotle
email: aristotle@example.com
name: Aristotle
phone_number: +1 23456778
status: maybe
read_only: false
reminders:
use_default: false
overrides:
- reminder_minutes: 10
reminder_method: email
recurrence:
- RRULE:FREQ=WEEKLY;BYDAY=MO
- EXDATE:20211011T000000Z
status: confirmed
title: Birthday Party
updated_at: 1661874192
visibility: private
when:
start_time: 1661874192
end_time: 1661877792
start_timezone: America/New_York
end_timezone: America/New_York
notetaker:
id: notetaker-123456
name: Nylas Notetaker
meeting_settings:
video_recording: true
audio_recording: true
transcription: true
transcription_settings:
expected_languages:
- en
- es
fallback_language: en
summary: true
action_items: true
events-send_rsvp:
description: Send-RSVP Response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
send_ics_error:
type: object
description: |-
If an error occurs while sending an updated ICS file to the organizer of an event,
Nylas returns an error message in this field. The event is still updated, but the
ICS file is _not_ sent to the organizer.
properties:
type:
type: string
description: The type of error that occurred.
message:
type: string
description: A human-readable message with details about the error.
example:
Event response example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
send_ics_error:
type: provider_error
message: Request had insufficient authentication scopes.
resources:
description: Room resource bookings
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/resource'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- building: West Building
capacity: '8'
email: training-room-1A@example.com
floor_name: '7'
floor_section: '7'
floor_number: '7'
name: Training Room 1A
object": room_resource
next_cursor: OQ==
contacts:
description: Contacts
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/contact'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- birthday: '1960-12-31'
company_name: Nylas
emails:
- type: work
email: john-work@example.com
- type: home
email: john-home@example.com
given_name: John
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
groups:
- id: starred
- id: friends
id: 5d3qmne77v32r8l4phyuksl2x
im_addresses:
- type: jabber
im_address: myjabberaddress
- type: msn
im_address: mymsnaddress
job_title: Software Engineer
manager_name: Bill
middle_name: Jacob
nickname: JD
notes: Loves ramen
object: contact
office_location: 123 Main Street
phone_numbers:
- type: work
number: +1-555-555-5555
- type: home
number: +1-555-555-5556
physical_addresses:
- type: work
street_address: 123 Main Street
postal_code: '94107'
state: CA
country: US
city: San Francisco
- type: home
street_address: 123 Main Street
postal_code: '94107'
state: CA
country: US
city: San Francisco
picture_url: https://example.com/picture.jpg
source: address_book
suffix: Jr.
surname: Doe
web_pages:
- type: work
url: https://www.linkedin.com/in/johndoe
- type: home
url: https://www.johndoe.com
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
contact:
description: Contact
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/contact'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
birthday: '1960-12-31'
company_name: Nylas
emails:
- type: work
email: john@example.com
- type: home
email: johnisacooldad@example.com
given_name: John
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
groups:
- id: starred
- id: friends
id: 5d3qmne77v32r8l4phyuksl2x
im_addresses:
- type: jabber
im_address: myjabberaddress
- type: msn
im_address: mymsnaddress
job_title: Software Engineer
manager_name: Bill
middle_name: Jacob
nickname: JD
notes: Loves ramen
object: contact
office_location: 123 Main Street
phone_numbers:
- type: work
number: +1-555-555-5555
- type: home
number: +1-555-555-5556
physical_addresses:
- type: work
street_address: 123 Main Street
postal_code: '94107'
state: CA
country: US
city: San Francisco
- type: home
street_address: 321 Pleasant Drive
postal_code: '94107'
state: CA
country: US
city: San Francisco
picture_url: https://example.com/picture.jpg
source: address_book
suffix: Jr.
surname: Doe
web_pages:
- type: work
url: https://www.linkedin.com/in/johndoe
- type: home
url: https://www.johndoe.com
contact_with_picture:
description: Contact
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/contact_with_picture'
examples:
Without Picture Blob:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
birthday: '1960-12-31'
company_name: Nylas
emails:
- type: work
email: john-work@example.com
- type: home
email: john-home@example.com
given_name: John
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
groups:
- id: starred
- id: friends
id: 5d3qmne77v32r8l4phyuksl2x
im_addresses:
- type: jabber
im_address: myjabberaddress
- type: msn
im_address: mymsnaddress
job_title: Software Engineer
manager_name: Bill
middle_name: Jacob
nickname: JD
notes: Loves ramen
object: contact
office_location: 123 Main Street
phone_numbers:
- type: work
number: +1-555-555-5555
- type: home
number: +1-555-555-5556
physical_addresses:
- type: work
street_address: 123 Main Street
postal_code: '94107'
state: CA
country: US
city: San Francisco
- type: home
street_address: 123 Main Street
postal_code: '94107'
state: CA
country: US
city: San Francisco
picture_url: https://example.com/picture.jpg
source: address_book
suffix: Jr.
surname: Doe
web_pages:
- type: work
url: https://www.linkedin.com/in/johndoe
- type: home
url: https://www.johndoe.com
With Picture Blob:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
birthday: '1960-12-31'
company_name: Nylas
emails:
- type: work
email: john-work@example.com
- type: home
email: john-home@example.com
given_name: John
grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
groups:
- id: starred
- id: friends
id: 5d3qmne77v32r8l4phyuksl2x
im_addresses:
- type: jabber
im_address: myjabberaddress
- type: msn
im_address: mymsnaddress
job_title: Software Engineer
manager_name: Bill
middle_name: Jacob
nickname: JD
notes: Loves ramen
object: contact
office_location: 123 Main Street
phone_numbers:
- type: work
number: +1-555-555-5555
- type: home
number: +1-555-555-5556
physical_addresses:
- type: work
street_address: 123 Main Street
postal_code: '94107'
state: CA
country: US
city: San Francisco
- type: home
street_address: 123 Main Street
postal_code: '94107'
state: CA
country: US
city: San Francisco
picture_url: https://example.com/picture.jpg
picture: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4QAqRXhpZgAASUkqAAgAAAABADEB...
source: address_book
suffix: Jr.
surname: Doe
web_pages:
- type: work
url: https://www.linkedin.com/in/johndoe
- type: home
url: https://www.johndoe.com
contact_groups:
description: Contact Groups
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/contact_group'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
group_type: system
id: starred
name: starred
object: contact_group
path: parentId/starred
- grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
group_type: user
id: friends
name: friends
object: contact_group
path: parentId/friends
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
get-notetakers-200:
description: Success. Returns list of Notetaker bots.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
prev_cursor:
type:
- string
- 'null'
description: A cursor pointing to the previous page of results for the request.
example: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBCQR28w4=
data:
type: array
items:
$ref: '#/components/schemas/notetaker'
invite-to-meeting-201:
description: Success. Returns information about Notetaker bot.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/notetaker'
400-2:
description: Bad Request
content:
application/json:
schema:
title: error
type: object
properties:
request_id:
type: string
description: The request ID.
error:
type: object
description: The response error object.
properties:
type:
type: string
description: The error type.
message:
type: string
description: The error message.
provider_error:
type: object
description: The error from the provider.
examples:
Bad Request:
value:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
error:
type: invalid_request_error
message: error parsing request body
provider_error:
code: TargetIdShouldNotBeMeOrWhitespace
message: Id is malformed.
get-notetaker-200:
description: Success. Returns Notetaker bot.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/notetaker'
delete-notetaker-200:
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
get-notetaker-history-200:
description: Success. Returns Notetaker bot history events.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
events:
type: array
description: A list of Notetaker history events, ordered by most recent first.
items:
$ref: '#/components/schemas/notetaker_history_event'
example:
request_id: abc-123-def
data:
events:
- created_at: 1700000300
event_type: notetaker.media
data:
grant_id: d4e78fca-2a90-4b6e-91c3-a7f2bcb0d498
id: 71c807752c744ad0902f64d43e6cc399
meeting_link: https://meet.google.com/abc-def-ghi
meeting_provider: Google Meet
join_time: 1700000050
object: notetaker
state: available
status: available
meeting_settings:
audio_recording: true
video_recording: true
transcription: true
transcription_settings:
expected_languages:
- en
- es
fallback_language: en
summary: true
action_items: true
media:
recording: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/recording.mp4
recording_duration: '3600'
transcript: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/transcript.json
thumbnail: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/thumbnail.jpg
summary: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/summary.txt
action_items: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/action_items.json
- created_at: 1700000200
event_type: notetaker.meeting_state
data:
grant_id: d4e78fca-2a90-4b6e-91c3-a7f2bcb0d498
id: 71c807752c744ad0902f64d43e6cc399
meeting_link: https://meet.google.com/abc-def-ghi
meeting_provider: Google Meet
join_time: 1700000050
object: notetaker
state: disconnected
status: disconnected
meeting_state: meeting_ended
- created_at: 1700000000
event_type: notetaker.created
data:
grant_id: d4e78fca-2a90-4b6e-91c3-a7f2bcb0d498
id: 71c807752c744ad0902f64d43e6cc399
meeting_link: https://meet.google.com/abc-def-ghi
meeting_provider: Google Meet
join_time: 1700000050
object: notetaker
state: scheduled
status: scheduled
cancel-notetaker-200:
description: OK
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The ID of the request.
example: 5fa64c92-e840-4357-86b9-2aa364d35b88
leave-meeting-200:
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
id:
type: string
description: The Notetaker ID.
message:
type: string
description: A message describing the API response.
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
id: AAAA-BBBB-1111-2222
message: Notetaker is leaving meeting.
leave-meeting-202:
description: Accepted
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
id:
type: string
description: The Notetaker ID.
message:
type: string
description: A message describing the API response.
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
id: AAAA-BBBB-1111-2222
message: Notetaker is already leaving meeting.
get-notetaker-media-200:
description: Success. Returns Notetaker media.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
action_items:
type: object
description: Details about the action items from the meeting.
properties:
created_at:
type: number
description: When the file was created, in seconds using the Unix timestamp format.
example: 1703088000
expires_at:
type: number
description: |-
When the file will be deleted from the Nylas servers, in seconds using the Unix
timestamp format.
example: 1704297600
name:
type: string
description: The file name.
example: meeting_action_items.json
size:
type: integer
description: The size of the file, in bytes.
example: 289
ttl:
type: number
description: |-
How long the link to the file is valid, in seconds. This is the difference
between `expires_at` and the time when you made your request.
example: 3600
type:
type: string
description: The file type.
example: application/json
url:
type: string
description: A link to the summary.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/...
recording:
type: object
description: Details about the meeting recording.
properties:
created_at:
type: number
description: When the file was created, in seconds using the Unix timestamp format.
example: 1703088000
duration:
type: integer
description: The duration of the recording, in seconds.
example: 1800
expires_at:
type: number
description: |-
When the file will be deleted from the Nylas servers, in seconds using the Unix
timestamp format.
example: 1704297600
name:
type: string
description: The file name.
example: meeting_recording.mp4
size:
type: integer
description: The size of the file, in bytes.
example: 52428800
ttl:
type: number
description: |-
How long the link to the file is valid, in seconds. This is the difference
between `expires_at` and the time when you made your request.
example: 3600
type:
type: string
description: The file type.
example: video/mp4
url:
type: string
description: A link to the meeting recording.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/...
summary:
type: object
description: Details about the meeting summary.
properties:
created_at:
type: number
description: When the file was created, in seconds using the Unix timestamp format.
example: 1703088000
expires_at:
type: number
description: |-
When the file will be deleted from the Nylas servers, in seconds using the Unix
timestamp format.
example: 1704297600
name:
type: string
description: The file name.
example: meeting_summary.json
size:
type: integer
description: The size of the file, in bytes.
example: 437
ttl:
type: number
description: |-
How long the link to the file is valid, in seconds. This is the difference
between `expires_at` and the time when you made your request.
example: 3600
type:
type: string
description: The file type.
example: application/json
url:
type: string
description: A link to the summary.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/...
thumbnail:
type: object
description: Details about the meeting thumbnail.
properties:
created_at:
type: number
description: When the file was created, in seconds using the Unix timestamp format.
example: 1703088000
expires_at:
type: number
description: |-
When the file will be deleted from the Nylas servers, in seconds using the Unix
timestamp format.
example: 1704297600
name:
type: string
description: The file name.
example: thumbnail.png
size:
type: integer
description: The size of the file, in bytes.
example: 437
ttl:
type: number
description: |-
How long the link to the file is valid, in seconds. This is the difference
between `expires_at` and the time when you made your request.
example: 3600
type:
type: string
description: The file type.
example: image/png
url:
type: string
description: A link to the thumbnail.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/...
transcript:
type: object
description: Details about the meeting transcript.
properties:
created_at:
type: number
description: When the file was created, in seconds using the Unix timestamp format.
example: 1703088000
expires_at:
type: number
description: |-
When the file will be deleted from the Nylas servers, in seconds using the Unix
timestamp format.
example: 1704297600
name:
type: string
description: The file name.
example: transcript.json
size:
type: integer
description: The size of the file, in bytes.
example: 10240
ttl:
type: number
description: |-
How long the link to the file is valid, in seconds. This is the difference
between `expires_at` and the time when you made your request.
example: 3600
type:
type: string
description: The file type.
example: application/json
url:
type: string
description: A link to the meeting transcript.
example: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/...
get-standalone-notetakers-200:
description: Success. Returns list of standalone Notetaker bots.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
prev_cursor:
type:
- string
- 'null'
description: A cursor pointing to the previous page of results for the request.
example: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBCQR28w4=
data:
type: array
items:
$ref: '#/components/schemas/standalone_notetaker'
invite-to-standalone-meeting-201:
description: Success. Returns information about standalone Notetaker bot.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/standalone_notetaker'
get-standalone-notetaker-200:
description: Success. Returns standalone Notetaker bot.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/standalone_notetaker'
get-standalone-notetaker-history-200:
description: Success. Returns standalone Notetaker bot history events.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
events:
type: array
description: A list of Notetaker history events, ordered by most recent first.
items:
$ref: '#/components/schemas/standalone_notetaker_history_event'
example:
request_id: abc-123-def
data:
events:
- created_at: 1700000300
event_type: notetaker.media
data:
id: 71c807752c744ad0902f64d43e6cc399
meeting_link: https://meet.google.com/abc-def-ghi
meeting_provider: Google Meet
join_time: 1700000050
object: notetaker
state: available
status: available
meeting_settings:
audio_recording: true
video_recording: true
transcription: true
transcription_settings:
expected_languages:
- en
- es
fallback_language: en
summary: true
action_items: true
media:
recording: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/recording.mp4
recording_duration: '3600'
transcript: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/transcript.json
thumbnail: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/thumbnail.jpg
summary: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/summary.txt
action_items: https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/action_items.json
- created_at: 1700000200
event_type: notetaker.meeting_state
data:
id: 71c807752c744ad0902f64d43e6cc399
meeting_link: https://meet.google.com/abc-def-ghi
meeting_provider: Google Meet
join_time: 1700000050
object: notetaker
state: disconnected
status: disconnected
meeting_state: meeting_ended
- created_at: 1700000000
event_type: notetaker.created
data:
id: 71c807752c744ad0902f64d43e6cc399
meeting_link: https://meet.google.com/abc-def-ghi
meeting_provider: Google Meet
join_time: 1700000050
object: notetaker
state: scheduled
status: scheduled
templates_list:
description: Success. Returns list of templates.
content:
application/json:
schema:
type: object
required:
- data
- next_cursor
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 3821703913-a3548169-0de0-49de-9801-37d972b51766
data:
type: array
items:
$ref: '#/components/schemas/template'
example:
- id: template_123
grant_id: grant_456
app_id: null
engine: mustache
name: Welcome Email
subject: Welcome {{user.name}}!
body: <p>Hello {{user.name}}, welcome to our service!</p><p>We're excited to have you on board.</p>
created_at: 1640995200
updated_at: 1640995200
object: template
- id: template_456
grant_id: grant_456
app_id: null
engine: handlebars
name: Password Reset
subject: Reset your password - {{company.name}}
body: <h1>Password Reset Request</h1><p>Hi {{user.name}},</p><p>Click <a href='{{reset_link}}'>here</a> to reset your password.</p><p>This link expires in {{expiry_hours}} hours.</p>
created_at: 1640995300
updated_at: 1640995400
object: template
- id: template_789
grant_id: grant_456
app_id: null
engine: twig
name: Order Confirmation
subject: 'Order #{{order.number}} confirmed'
body: '<h2>Thank you for your order!</h2><p>Order #{{order.number}} has been confirmed.</p><ul>{% for item in order.items %}<li>{{item.name}} - ${{item.price}}</li>{% endfor %}</ul><p>Total: ${{order.total}}</p>'
created_at: 1640995500
updated_at: 1640995500
object: template
next_cursor:
type: string
description: A cursor pointing to the next page of results for the request.
example: eyJjdXJzb3IiOiJ0ZW1wbGF0ZV8xMjMifQ==
template_400:
description: 'Error: Bad request'
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 3704952820-faf9214c-8bdd-4419-9d9c-f8f5ee464d57
error:
type: object
required:
- message
- type
properties:
type:
type: string
description: The type of error that occurred.
example: api.invalid_request_error
message:
type: string
description: A human-readable message describing the error.
example: Validation of request body failed
template:
description: Success. Returns template.
content:
application/json:
schema:
type: object
required:
- data
- request_id
properties:
request_id:
type: string
description: The ID of the request.
data:
$ref: '#/components/schemas/template'
example:
request_id: 3822087561-67d4f28f-a46b-4c90-8fd3-765a04105043
data:
id: 14c00cc8-648c-4381-ad10-52641d9bac8e
grant_id: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
app_id: null
engine: mustache
name: Booking confirmed message
subject: '{{user.name}}, your booking is confirmed!'
body: <p>Hello {{user.name}}, your booking has been confirmed.</p>
created_at: 1640995200
updated_at: 1640995200
object: template
delete_200_simple:
description: 'Success: Object deleted'
content:
application/json:
schema:
type: object
required:
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 3906564297-48e7fb5b-f220-427b-a4de-255736adba08
template_render_html:
description: Success. Returns rendered HTML.
content:
application/json:
schema:
type: object
required:
- data
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 3907012912-13b5a9a4-f136-4761-a31b-68c6a8af825d
data:
type: object
required:
- body
properties:
body:
type: string
description: The rendered HTML with variables substituted.
example: <p>Hello Leyah, your booking has been confirmed.</p>
template_render:
description: Success. Returns rendered template.
content:
application/json:
schema:
type: object
required:
- data
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 3822450015-47d9207c-4d06-4e15-b3e7-752c5dd5585d
data:
type: object
required:
- body
- subject
properties:
body:
type: string
description: The rendered HTML body content with variables substituted.
example: <p>Hello Leyah, your booking has been confirmed.</p>
subject:
type: string
description: The rendered subject content with variables substituted.
example: Leyah, your booking is confirmed!
workflows_list:
description: Success. Returns list of workflows.
content:
application/json:
schema:
type: object
required:
- data
- next_cursor
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 9ca1d434-5ac7-4331-b8fb-3749c9a758d3
data:
type: array
items:
$ref: '#/components/schemas/workflow'
example:
- id: b79c82b2-a51b-4c54-8469-28006a43551a
grant_id: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
app_id: null
is_enabled: true
name: Booking Confirmation Workflow
trigger_event: booking.created
delay: 1
template_id: 14c00cc8-648c-4381-ad10-52641d9bac8e
date_created: 1756477389
- id: c89d93c3-b62c-5d65-9570-39117b54662b
grant_id: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
app_id: null
is_enabled: true
name: Booking Reminder Workflow
trigger_event: booking.reminder
delay: 60
template_id: 25d11dd9-759d-5492-be21-63752e6cbd9f
date_created: 1756477500
- id: d90e04d4-c73d-6e76-a681-40228c65773c
grant_id: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
app_id: null
is_enabled: false
name: Booking Cancellation Workflow
trigger_event: booking.cancelled
delay: 0
template_id: 36e22ee0-86ae-6603-cf32-74863f7dce0g
date_created: 1756477600
next_cursor:
type: string
description: A cursor pointing to the next page of results for the request.
example: eyJjdXJzb3IiOiJub3RpZmljYXRpb25fd29ya2Zsb3dfYjc5YzgyYjIifQ==
workflow_400:
description: 'Error: Bad request'
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 02674fc0-b8cf-43cd-8bd2-506fa401b81f
error:
type: object
required:
- message
- type
properties:
type:
type: string
description: The type of error that occurred.
example: api.invalid_request_error
message:
type: string
description: A human-readable message describing the error.
example: invalid_event is not a valid option
workflow:
description: Success. Returns workflow.
content:
application/json:
schema:
type: object
required:
- data
- request_id
properties:
request_id:
type: string
description: The ID of the request.
data:
$ref: '#/components/schemas/workflow'
example:
request_id: 9ca1d434-5ac7-4331-b8fb-3749c9a758d3
data:
app_id: null
date_created: 1756477389
delay: 5
grant_id: 6c45fe5e-0bb6-41b9-9acc-ccb15bfc51eb
id: b79c82b2-a51b-4c54-8469-28006a43551a
is_enabled: true
name: New booking confirmation workflow
template_id: 14c00cc8-648c-4381-ad10-52641d9bac8e
trigger_event: booking.created
from:
email: support@example.com
name: Support
workflow_404:
description: 'Error: Not found'
content:
application/json:
schema:
type: object
required:
- error
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 02674fc0-b8cf-43cd-8bd2-506fa401b81f
error:
type: object
required:
- message
- type
properties:
type:
type: string
description: The type of error that occurred.
example: api.not_found_error
message:
type: string
description: A human-readable message describing the error.
example: template not found
configurations:
description: Configuration objects returned
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
type: object
oneOf:
- title: Standard Configuration
description: Single-host configuration for one-on-one bookings.
properties:
appearance:
type:
- object
- 'null'
example: null
availability:
type: object
description: The rules that determine available time slots for the event.
properties:
availability_rules:
type: object
description: A list of availability rules that apply to all participants.
properties:
availability_method:
type: string
description: The method Nylas uses to calculate availability for all participants.
example: collective
buffer:
type: object
description: A list of rules that set buffer time around events for all participants.
properties:
after:
type: integer
description: |-
The amount of buffer time to add after meetings. For example, if
an account has a meeting scheduled from 10:00–11:00a.m., and you
set an after buffer of 15 minutes, Nylas treats 10:00–11:15a.m. as
busy.
example: 15
before:
type: integer
description: |-
The amount of buffer time to add before meetings. For example, if
an account has a meeting scheduled from 10:00–11:00a.m., and you
set a before buffer of 30 minutes, Nylas treats 9:30–11:00a.m. as
busy.
example: 5
duration_minutes:
type: integer
description: The total duration of the event, in minutes.
example: 30
interval_minutes:
type: integer
description: The interval between meetings, in minutes.
example: 15
round_to:
type: integer
description: |-
Nylas rounds each time slot to the nearest `round_to` value. For example,
if a time slot starts at 9:05a.m. and `round_to` is set to 15, Nylas rounds
it to 9:15a.m.
example: 5
event_booking:
type: object
description: An object containing details about the booking.
properties:
booking_type:
type: string
description: The booking type.
example: booking
disable_emails:
type:
- boolean
- 'null'
description: |-
When `true`, Nylas doesn't send email notifications when an event is booked,
cancelled, or rescheduled. When `null`, the default behavior applies (emails are sent).
example: false
hide_participants:
type:
- boolean
- 'null'
description: When `true`, Nylas creates the event with `hide_participants=true`, so the host can see who's on the event but the guests cannot. When `null`, the default behavior applies (participants are visible).
example: false
location:
type: string
description: The location of the event.
example: Conference room 104
notify_participants:
type:
- boolean
- 'null'
description: |-
When `true`, the calendar provider sends notifications to participants
when the event is created, updated, or deleted. Microsoft grants ignore
this flag and always notify participants. This field may be `null` if not
explicitly set on the configuration; treat `null` the same as `false`.
example: false
reminders:
type: array
description: A list of reminders for the event.
items:
type: object
properties:
minutes_before_event:
type: integer
description: The number of minutes before the event to send the reminder.
example: 15
recipient:
type: string
description: (Email reminders only) Who should receive the reminder.
example: all
type:
type: string
description: The reminder type.
example: email
timezone:
type: string
description: |-
The event's timezone as an
[IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string.
example: America/New York
title:
type: string
description: The event title.
example: Weekly One-on-One
id:
type: string
description: The Configuration ID.
example: 26e98405-3b48-47d2-898a-7254f1fad8d7
name:
type: string
description: The name of the Scheduling Page.
example: Leyah & Nyla Weekly One-on-One
participants:
type: array
description: A list of participants included in the scheduled event.
items:
type: object
properties:
availability:
type: object
description: The availability settings for the participant.
properties:
calendar_ids:
type: array
description: A list of calendar IDs used to check the participant's availability.
items:
type: string
example:
- primary
open_hours:
type: array
description: |-
An array of objects representing the participant's open hours. Nylas
searches for free time slots within these open hours.
items:
type: object
properties:
days:
type: array
description: |-
The days of the week that the open hour settings are applied
to. Sunday corresponds to `0`, and Saturday corresponds to `6`.
items:
type: integer
example:
- 1
- 2
- 3
- 4
- 5
end:
type: string
description: The end time in 24-hour time format.
example: '14:00'
exdates:
type: array
description: |-
A list of dates that are excluded from the participant's open
hours, in `YYYY-MM-DD` format.
items:
type: string
example:
- '2025-01-18'
start:
type: string
description: The start time in 24-hour time format.
example: '10:00'
timezone:
type: string
description: |-
The participant's timezone as an
[IANA-formatted](https://en.wikipedia.org/wiki/Tz_database)
string. Nylas uses this when calculating the participant's open
hours and in email notifications.
example: America/New York
booking:
type: object
description: The participant's booking data.
properties:
calendar_id:
type: string
description: The ID of the calendar the event was created on.
example: primary
email:
type: string
description: The participant's email address.
example: leyah@example.com
name:
type: string
description: The participant's name.
example: Leyah Miller
is_organizer:
type: boolean
description: When `true`, shows that the participant is the organizer of the event.
example: true
requires_session_auth:
type:
- boolean
- 'null'
description: |-
When `true`, the scheduling Availability and Bookings endpoints require a valid
session ID to authenticate requests using the Configuration. This field may be
`null` if not explicitly set; treat `null` the same as `false`.
example: false
scheduler:
type: object
properties:
additional_fields:
type: object
description: An object containing additional custom fields.
properties:
example_field:
type: object
properties:
label:
type: string
description: The text label to be displayed in the Scheduler UI.
example: Sample field
order:
type: integer
description: |-
The order in which the field is displayed in the Scheduler UI.
Fields with lower order values are displayed first.
example: 4
required:
type: boolean
description: When `true`, marks the field as required.
example: false
type:
type: string
description: The field type.
example: multi_line_text
available_days_in_future:
type: integer
description: |-
The number of days in the future that Scheduler is available for scheduling
events.
example: 30
email_template:
type: object
description: Template settings for email notifications.
properties:
booking_confirmed:
type: object
description: Template settings for confirmation notifications.
properties:
body:
type: string
description: The body text of the message.
example: Your weekly one-on-one with Nyla has been confirmed.
title:
type: string
description: The title of the message.
example: 'Confirmed: Weekly One-on-One'
organizer_locale:
type: string
description: The organizer's locale settings.
example: en
min_booking_notice:
type:
- integer
- 'null'
description: |-
The minimum number of minutes in the future that a user can schedule a new
booking. This field may be `null` if not explicitly set; treat `null` the
same as `60`.
example: 30
min_cancellation_notice:
type: integer
description: |-
The minimum amount of time before a meeting that the booking can still be
cancelled, in minutes.
example: 30
slug:
type:
- string
- 'null'
description: |-
The Configuration slug. You can use this instead of the `configuration_id`
when making requests to other Scheduling endpoints. This field may be `null`
if no slug has been set.
example: xyz-en
- title: Group Configuration
description: Multi-host configuration for group event bookings.
properties:
appearance:
type:
- object
- 'null'
example: null
group_booking:
type: object
description: An object containing details about the group booking.
properties:
booking_type:
type: string
description: The booking type.
example: booking
calendar_id:
type: string
description: The ID of the calendar on which the group event is created.
example: primary
default_capacity:
type: integer
description: The default capacity for the booking.
example: 50
disable_emails:
type:
- boolean
- 'null'
description: |-
When `true`, Nylas doesn't send email notifications when an event is booked,
cancelled, or rescheduled. When `null`, the default behavior applies (emails are sent).
example: false
reminders:
type: array
description: A list of reminders for the event.
items:
type: object
properties:
minutes_before_event:
type: integer
description: The number of minutes before the event to send the reminder.
example: 15
recipient:
type: string
description: (Email reminders only) Who should receive the reminder.
example: all
type:
type: string
description: The reminder type.
example: email
title:
type: string
description: The event title.
example: Annual Philosophy Club Meeting
id:
type: string
description: The group Configuration ID.
example: 26e98405-3b48-47d2-898a-7254f1fad8d7
name:
type: string
description: The name of the Scheduling Page.
example: Annual Philosophy Club Meeting
requires_session_auth:
type:
- boolean
- 'null'
description: |-
When `true`, the scheduling Availability and Bookings endpoints require a valid
session ID to authenticate requests using the Configuration. This field may be
`null` if not explicitly set; treat `null` the same as `false`.
example: false
scheduler:
type: object
properties:
available_days_in_future:
type: integer
description: |-
The number of days in the future that Scheduler is available for scheduling
events.
example: 30
email_template:
type: object
description: Template settings for email notifications.
properties:
booking_confirmed:
type: object
description: Template settings for confirmation notifications.
properties:
body:
type: string
description: The body text of the message.
example: Our annual Philosophy Club meeting is confirmed!
title:
type: string
description: The title of the message.
example: 'Confirmed: Annual Philosophy Club Meeting'
min_booking_notice:
type:
- integer
- 'null'
description: |-
The minimum number of minutes in the future that a user can schedule a new
booking. This field may be `null` if not explicitly set; treat `null` the
same as `60`.
example: 30
min_cancellation_notice:
type: integer
description: |-
The minimum amount of time before a meeting that the booking can still be
cancelled, in minutes.
example: 30
slug:
type:
- string
- 'null'
description: |-
The group Configuration slug. You can use this instead of the `configuration_id`
when making requests to other Scheduling endpoints. This field may be `null`
if no slug has been set.
example: xyz-en
type:
type: string
description: |-
The booking type for the Scheduling Page. For group Configurations, this is
always `group`.
example: group
configuration:
description: Configuration returned
content:
application/json:
schema:
oneOf:
- title: Standard Configuration
description: Single-host configuration for one-on-one bookings.
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
appearance:
type:
- object
- 'null'
example: null
availability:
type: object
description: The rules that determine available time slots for the event.
properties:
availability_rules:
type: object
description: A list of availability rules that apply to all participants.
properties:
availability_method:
type: string
description: The method Nylas uses to calculate availability for all participants.
example: collective
buffer:
type: object
description: A list of rules that set buffer time around events for all participants.
properties:
after:
type: integer
description: |-
The amount of buffer time to add after meetings. For example, if
an account has a meeting scheduled from 10:00–11:00a.m., and you
set an after buffer of 15 minutes, Nylas treats 10:00–11:15a.m. as
busy.
example: 15
before:
type: integer
description: |-
The amount of buffer time to add before meetings. For example, if
an account has a meeting scheduled from 10:00–11:00a.m., and you
set a before buffer of 30 minutes, Nylas treats 9:30–11:00a.m. as
busy.
example: 5
duration_minutes:
type: integer
description: The total duration of the event, in minutes.
example: 30
interval_minutes:
type: integer
description: The interval between meetings, in minutes.
example: 15
round_to:
type: integer
description: |-
Nylas rounds each time slot to the nearest `round_to` value. For example,
if a time slot starts at 9:05a.m. and `round_to` is set to 15, Nylas rounds
it to 9:15a.m.
example: 5
event_booking:
type: object
description: An object containing details about the booking.
properties:
booking_type:
type: string
description: The booking type.
example: booking
disable_emails:
type:
- boolean
- 'null'
description: |-
When `true`, Nylas doesn't send email notifications when an event is booked,
cancelled, or rescheduled. When `null`, the default behavior applies (emails are sent).
example: false
hide_participants:
type:
- boolean
- 'null'
description: When `true`, Nylas creates the event with `hide_participants=true`, so the host can see who's on the event but the guests cannot. When `null`, the default behavior applies (participants are visible).
example: false
location:
type: string
description: The location of the event.
example: Conference room 104
notify_participants:
type:
- boolean
- 'null'
description: |-
When `true`, the calendar provider sends notifications to participants
when the event is created, updated, or deleted. Microsoft grants ignore
this flag and always notify participants. This field may be `null` if not
explicitly set on the configuration; treat `null` the same as `false`.
example: false
reminders:
type: array
description: A list of reminders for the event.
items:
type: object
properties:
minutes_before_event:
type: integer
description: The number of minutes before the event to send the reminder.
example: 15
recipient:
type: string
description: (Email reminders only) Who should receive the reminder.
example: all
type:
type: string
description: The reminder type.
example: email
timezone:
type: string
description: |-
The event's timezone as an
[IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string.
example: America/New York
title:
type: string
description: The event title.
example: Weekly One-on-One
id:
type: string
description: The Configuration ID.
example: 26e98405-3b48-47d2-898a-7254f1fad8d7
name:
type: string
description: The name of the Scheduling Page.
example: Leyah & Nyla Weekly One-on-One
participants:
type: array
description: A list of participants included in the scheduled event.
items:
type: object
properties:
availability:
type: object
description: The availability settings for the participant.
properties:
calendar_ids:
type: array
description: A list of calendar IDs used to check the participant's availability.
items:
type: string
example:
- primary
open_hours:
type: array
description: |-
An array of objects representing the participant's open hours. Nylas
searches for free time slots within these open hours.
items:
type: object
properties:
days:
type: array
description: |-
The days of the week that the open hour settings are applied
to. Sunday corresponds to `0`, and Saturday corresponds to `6`.
items:
type: integer
example:
- 1
- 2
- 3
- 4
- 5
end:
type: string
description: The end time in 24-hour time format.
example: '14:00'
exdates:
type: array
description: |-
A list of dates that are excluded from the participant's open
hours, in `YYYY-MM-DD` format.
items:
type: string
example:
- '2025-01-18'
start:
type: string
description: The start time in 24-hour time format.
example: '10:00'
timezone:
type: string
description: |-
The participant's timezone as an
[IANA-formatted](https://en.wikipedia.org/wiki/Tz_database)
string. Nylas uses this when calculating the participant's open
hours and in email notifications.
example: America/New York
booking:
type: object
description: The participant's booking data.
properties:
calendar_id:
type: string
description: The ID of the calendar the event was created on.
example: primary
email:
type: string
description: The participant's email address.
example: leyah@example.com
name:
type: string
description: The participant's name.
example: Leyah Miller
is_organizer:
type: boolean
description: When `true`, shows that the participant is the organizer of the event.
example: true
requires_session_auth:
type:
- boolean
- 'null'
description: |-
When `true`, the scheduling Availability and Bookings endpoints require a valid
session ID to authenticate requests using the Configuration. This field may be
`null` if not explicitly set; treat `null` the same as `false`.
example: false
scheduler:
type: object
properties:
additional_fields:
type: object
description: An object containing additional custom fields.
properties:
example_field:
type: object
properties:
label:
type: string
description: The text label to be displayed in the Scheduler UI.
example: Sample field
order:
type: integer
description: |-
The order in which the field is displayed in the Scheduler UI.
Fields with lower order values are displayed first.
example: 4
required:
type: boolean
description: When `true`, marks the field as required.
example: false
type:
type: string
description: The field type.
example: multi_line_text
available_days_in_future:
type: integer
description: |-
The number of days in the future that Scheduler is available for scheduling
events.
example: 30
email_template:
type: object
description: Template settings for email notifications.
properties:
booking_confirmed:
type: object
description: Template settings for confirmation notifications.
properties:
body:
type: string
description: The body text of the message.
example: Your weekly one-on-one with Nyla has been confirmed.
title:
type: string
description: The title of the message.
example: 'Confirmed: Weekly One-on-One'
organizer_locale:
type: string
description: The organizer's locale settings.
example: en
min_booking_notice:
type:
- integer
- 'null'
description: |-
The minimum number of minutes in the future that a user can schedule a new
booking. This field may be `null` if not explicitly set; treat `null` the
same as `60`.
example: 30
min_cancellation_notice:
type: integer
description: |-
The minimum amount of time before a meeting that the booking can still be
cancelled, in minutes.
example: 30
slug:
type:
- string
- 'null'
description: |-
The Configuration slug. You can use this instead of the `configuration_id`
when making requests to other Scheduling endpoints. This field may be `null`
if no slug has been set.
example: xyz-en
- title: Group Configuration
description: Multi-host configuration for group event bookings.
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
appearance:
type:
- object
- 'null'
example: null
group_booking:
type: object
description: An object containing details about the group booking.
properties:
booking_type:
type: string
description: The booking type.
example: booking
calendar_id:
type: string
description: The ID of the calendar on which the group event is created.
example: primary
default_capacity:
type: integer
description: The default capacity for the booking.
example: 50
disable_emails:
type:
- boolean
- 'null'
description: |-
When `true`, Nylas doesn't send email notifications when an event is booked,
cancelled, or rescheduled. When `null`, the default behavior applies (emails are sent).
example: false
reminders:
type: array
description: A list of reminders for the event.
items:
type: object
properties:
minutes_before_event:
type: integer
description: The number of minutes before the event to send the reminder.
example: 15
recipient:
type: string
description: (Email reminders only) Who should receive the reminder.
example: all
type:
type: string
description: The reminder type.
example: email
title:
type: string
description: The event title.
example: Annual Philosophy Club Meeting
id:
type: string
description: The group Configuration ID.
example: 26e98405-3b48-47d2-898a-7254f1fad8d7
name:
type: string
description: The name of the Scheduling Page.
example: Annual Philosophy Club Meeting
requires_session_auth:
type:
- boolean
- 'null'
description: |-
When `true`, the scheduling Availability and Bookings endpoints require a valid
session ID to authenticate requests using the Configuration. This field may be
`null` if not explicitly set; treat `null` the same as `false`.
example: false
scheduler:
type: object
properties:
available_days_in_future:
type: integer
description: |-
The number of days in the future that Scheduler is available for scheduling
events.
example: 30
email_template:
type: object
description: Template settings for email notifications.
properties:
booking_confirmed:
type: object
description: Template settings for confirmation notifications.
properties:
body:
type: string
description: The body text of the message.
example: Our annual Philosophy Club meeting is confirmed!
title:
type: string
description: The title of the message.
example: 'Confirmed: Annual Philosophy Club Meeting'
min_booking_notice:
type:
- integer
- 'null'
description: |-
The minimum number of minutes in the future that a user can schedule a new
booking. This field may be `null` if not explicitly set; treat `null` the
same as `60`.
example: 30
min_cancellation_notice:
type: integer
description: |-
The minimum amount of time before a meeting that the booking can still be
cancelled, in minutes.
example: 30
slug:
type:
- string
- 'null'
description: |-
The group Configuration slug. You can use this instead of the `configuration_id`
when making requests to other Scheduling endpoints. This field may be `null`
if no slug has been set.
example: xyz-en
type:
type: string
description: |-
The booking type for the Scheduling Page. For group Configurations, this is
always `group`.
example: group
group_events:
description: Group events returned
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response_with_cursor'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/group_event'
example:
List group events:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
- calendar_id: 7d93zl2palhxqdy6e5qinsakt
conferencing: null
provider: Zoom Meeting
details:
meeting_code: code-123456
password: password-123456
url: https://zoom.us/j/1234567890?pwd=1234567890
created_at: 1661874192
description: Description of my new group event
html_link: https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Ef3feD2VuM29fMjAyMjA2MjdUMjIwMDAwWiBoYWxsYUBueWxhcy5jb20
id: 5d3qmne77v32r8l4phyuksl2x
participants:
- comment: Leyah Miller
email: leyah@example.com
name: Leyah Miller
phone_number: +1 23456778
status: maybe
status: confirmed
title: Birthday Party
updated_at: 1661874192
when:
start_time: 1661874192
end_time: 1661877792
start_timezone: America/New_York
end_timezone: America/New_York
next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
group_event:
description: Group event returned
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: array
items:
ID:
type: string
description: The Configuration object ID.
$ref: '#/components/schemas/group_event'
example:
Return group event:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
ID: AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AeRryRUldasZYNfAbiKd_mQABCjz8fgAA
participants:
- name: Nyla
email: nyla@example.com
is_organizer: true
calendar_id: primary
capacity: 50
when:
- start_timezone: America/New_York
end_timezone: America/New_York
start_time: 1744286400
end_time: 1744290000
import-group-event:
description: Group events imported
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/import-group-event-response'
example:
Events imported:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
imported_events:
- event_id: 6oouub093fhj54se2rlp1ogjg56
import_failed:
- event_id: 6oouub093fhj54se2rlp1ogjg56
reason: Event already imported
validate-timeslot:
description: Time slot validated
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: ID of the request.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
session_create:
description: Create a new scheduling session
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
session_id:
type: string
description: The ID of the session
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
session_id: AAAA-BBBB-1111-2222
session_delete:
description: The response to a successful request to delete a scheduling session.
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: The ID of the request
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
booking_create:
description: Create a new booking
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
$ref: '#/components/schemas/booking'
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
booking_id: AAAA-BBBB-1111-2222
event_id: CCCC-DDDD-3333-4444
title: My test event
organizer:
name: John Doe
email: user@example.com
status: booked
description: This is an example of a description.
booking_confirm:
description: Booking confirmed or cancelled
content:
application/json:
schema:
oneOf:
- title: Booking confirmed
type: object
description: Returned when the booking was confirmed.
properties:
request_id:
type: string
description: The ID of the request.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
data:
type: object
properties:
booking_id:
type: string
description: The unique ID of the booking.
example: xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
description:
type: string
description: A brief description of the event.
example: Come ready to talk philosophy!
event_id:
type: string
description: The event ID associated with the booking.
example: 5d3qmne77v32r8l4phyuksl2x
organizer:
type: object
description: The participant designated as the organizer of the event.
properties:
email:
type: string
description: The organizer's email address.
example: leyah@example.com
name:
type: string
description: The organizer's name.
example: Leyah Miller
status:
type: string
description: The status of the booking.
enum:
- booked
- cancelled
- pending
example: booked
title:
type: string
description: The title of the event.
example: Annual Philosophy Club Meeting
- title: Booking cancelled
type: object
description: Returned when the booking was cancelled.
required:
- request_id
properties:
request_id:
type: string
description: The ID of the request.
example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
should-redirect:
description: Redirect slug to v3
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/common_response'
- properties:
data:
type: object
properties:
url:
type: string
description: The v3 URL for the redirected Scheduling Page.
example:
request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
data:
url: /scheduler/<NYLAS_APPLICATION_ID>/<V3_SCHEDULER_SLUG>
parameters:
provider:
name: provider
in: path
required: true
schema:
type: string
enum:
- google
- microsoft
- imap
- icloud
- yahoo
- ews
- virtual-calendar
- zoom
- nylas
example: google
id:
name: id
required: true
in: path
schema:
type: string
example: e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47
limit:
name: limit
in: query
required: false
schema:
type: integer
default: 50
maximum: 200
description: |-
The maximum number of objects to return. See [Pagination](/docs/reference/api/#pagination)
for more information.
metadata_pair:
name: metadata_pair
in: query
required: false
schema:
type: string
description: |-
Pass a metadata key/value pair (for example, `?metadata_pair=key1:value`) to search for metadata
associated with objects. See [Metadata](/docs/reference/api/#metadata) for more information.
page_token:
name: page_token
in: query
required: false
schema:
type: string
description: |-
An identifier that specifies which page of data to return. You can get this value from the
`next_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more
information.
query_imap_list:
name: query_imap
schema:
type: boolean
default: false
in: query
required: false
description: |-
(IMAP, Yahoo, and iCloud only) When `true`, Nylas queries the IMAP server directly instead of the
Nylas database. You also need to set the `in` query parameter in your request so Nylas knows which
folder to query.
field_selection:
name: select
in: query
required: false
schema:
type: string
description: |-
Specify fields that you want Nylas to return, as a comma-separated list (for example,
`select=id,updated_at`). This allows you to receive only the portion of object data that you're
interested in. You can use `select` to optimize response size and reduce latency by limiting queries
to only the information that you need.
shared_folder_id:
name: shared_folder_id
in: query
schema:
type: string
description: |-
(Microsoft only) When provided, Nylas returns items from the specified shared folder ID.
Required when using `shared_from`.
This parameter only accepts a single folder ID.
Check out the [Shared folders](/docs/provider-guides/microsoft/shared-folders) guide for more information.
shared_from:
name: shared_from
in: query
schema:
type: string
description: |-
(Microsoft only) When provided, Nylas returns items that were shared from the specified email address.
It also accepts grant ID.
This parameter only accepts single email address or grant ID.
Check out the [Shared folders](/docs/provider-guides/microsoft/shared-folders) guide for more information.
grant_id:
name: grant_id
schema:
type: string
in: path
required: true
description: |-
ID of the grant to access. You can also use the email address associated with the grant, or use `/me/`
to refer to the grant associated with an access token.
example: nyla@example.com
query_imap_get_by_id:
name: query_imap
schema:
type: boolean
default: false
in: query
required: false
description: |-
(IMAP, iCloud, and Yahoo only) When `true`, Nylas queries from the IMAP server directly instead of
the Nylas database.
hard_delete:
name: hard_delete
in: query
schema:
type: boolean
default: false
description: |-
When `true`, Nylas immediately deletes the specified message instead of sending it to the user's Trash
folder. This operation is irreversible.
To use this query parameter, you need to turn on "Enable hard delete" in the
[Nylas Dashboard](https://dashboard-v3.nylas.com/?utm_source=docs&utm_content=docs-hard-delete) under
**Customizations > API**.
include_hidden_folders:
name: include_hidden_folders
in: query
schema:
type: boolean
default: false
description: (Microsoft only) When `true`, Nylas includes hidden folders in its response.
parent_id:
name: parent_id
in: query
schema:
type: string
description: (Microsoft and EWS only) Use the ID of a folder to find all child folders it contains.
single_level:
name: single_level
schema:
type: boolean
default: false
in: query
required: false
description: (Microsoft only) If `true`, retrieves folders from a single-level hierarchy only. If `false`, retrieves folders across a multi-level hierarchy.
attendees:
name: attendees
in: query
required: false
schema:
type: string
description: |-
(Not supported for virtual calendars) Filter for events that include the specified attendees. This
parameter accepts a comma-delimited list of email addresses.
busy:
name: busy
in: query
required: false
schema:
type: boolean
description: (Not supported for iCloud) Filter for events with the specified `busy` status.
calendar_id:
name: calendar_id
in: query
required: true
schema:
type: string
description: |-
Filter for the specified calendar ID.
(Not supported for iCloud) You can use `primary` to query the user's primary calendar.
description:
name: description
in: query
required: false
schema:
type: string
description: Filter for events matching the specified description. The filter is case insensitive and will match partial descriptions.
end:
name: end
in: query
schema:
type: integer
description: |-
Filter for events that end at or before the specified time, in seconds using the Unix timestamp format. For example, if
you filter for events that end at 5:00p.m., and the calendar includes an event that runs from
4:30–5:30p.m., Nylas returns that event.
Defaults to one month from the time you make the request.
The `end` value cannot be earlier than `start`. For iCloud accounts, the difference between `start`
and `end` can't be greater than one year.
event_type:
name: event_type
in: query
required: false
schema:
type: string
enum:
- default
- outOfOffice
- focusTime
- workingLocation
description: |-
(Google only) Filter for events with the specified event type. You can pass this query parameter
multiple times to select or exclude multiple event types. For example,
`event_type=default&event_type=outOfOffice` returns all events that are default or `OOO`, and excludes
any events that are `focusTime` or that have a `workingLocation`.
If you don't specify an event type, Nylas uses `default` to filter for regular events that don't have
another specific type.
expand_recurring:
name: expand_recurring
in: query
schema:
type: boolean
default: true
required: false
deprecated: true
description: |-
**This parameter is deprecated. Use the
[Import Events endpoint](/docs/reference/api/events/import-events/)
instead**.
When `true`, Nylas returns all recurring events within the specified time range, including individual
occurrences of the recurring event. Otherwise, Nylas only returns the parent event and any event
overrides (individual occurrences that have been edited) in the time range.
ical_uid:
name: ical_uid
in: query
schema:
type: string
description: |-
(Not supported for iCloud) Filter for events with the specified `ical_uid`. You _cannot_ apply other
filters if you use this parameter.
location:
name: location
in: query
required: false
schema:
type: string
description: Filter for events with the specified location. The filter is case insensitive and will match partial locations.
master_event_id:
name: master_event_id
in: query
schema:
type: string
description: |-
(Not supported for iCloud) Filter for instances of recurring events with the specified `master_event_id`.
`master_event_id` is _not_ respected by metadata filtering.
When using `master_event_id` to fetch recurring events with a Google grant, the order of the results will not be sorted chronologically.
Instead, Nylas returns the unchanged occurrences first, followed by the modified occurrences.
For example, if you have a recurring event with the following occurrences:
- 2025-01-01
- 2025-01-02
- 2025-01-03
But you modify the time of the second occurrence to 2025-01-02, the results will be:
- 2025-01-01
- 2025-01-03
- 2025-01-02 (modified)
show_cancelled:
name: show_cancelled
in: query
required: false
schema:
type: boolean
default: false
description: |-
(Not supported for iCloud or EWS) If `true`, Nylas includes events whose `status` is `cancelled`.
Different providers have different semantics for cancelled events:
- **Google**: An event is considered cancelled after a user deletes it from their calendar, until
it's eventually hard-deleted and is no longer readable.
- **Microsoft**: An event is considered cancelled if the user is invited to an event and the
organizer deletes it. The cancelled version of the event stays on the participants' calendars until
they delete it manually.
start:
name: start
in: query
schema:
type: integer
description: |-
Filter for events that start at or after the specified time, in seconds using the Unix timestamp format. For example, if
you filter for events that start at 9:00a.m., and the calendar includes an event that runs from
8:30–9:30a.m., Nylas returns that event.
Defaults to the time that you make the request.
The `start` value cannot be later than `end`. For iCloud accounts, the difference between `start`
and `end` can't be greater than one year.
tentative_as_busy:
name: tentative_as_busy
in: query
required: false
schema:
type: boolean
default: true
description: (Microsoft and EWS only) When `true`, Nylas treats tentative events as busy.
title:
name: title
in: query
required: false
schema:
type: string
description: Filter for events that match the specified title. The filter is case insensitive and will match partial titles.
updated_after:
name: updated_after
in: query
required: false
schema:
type: integer
description: |-
(Google, Microsoft, and EWS only) Filter for events that have been updated after the specified time,
in seconds using the Unix timestamp format.
`updated_after` is _not_ respected by metadata filtering.
updated_before:
name: updated_before
in: query
required: false
schema:
type: integer
description: |-
(Google, Microsoft, and EWS only) Filter for events that have been updated before the specified time,
in seconds using the Unix timestamp format.
`updated_before` is _not_ respected by metadata filtering.
notify_participants:
schema:
type: boolean
default: true
in: query
name: notify_participants
description: |-
Filter for events matching the specified `notify_participants` setting.
Microsoft and iCloud do _not_ support `notify_participants=false`.
max_results:
name: limit
in: query
required: false
schema:
type: integer
default: 50
maximum: 500
description: |-
Specifies the maximum number of events Nylas returns in a single page of results. The actual number
of events Nylas returns might be lower than this limit, even if other events match your query
parameters.
calendar_id_no_validate:
name: calendar_id
in: query
required: true
schema:
type: string
description: |-
The calendar ID of the event.
For Microsoft, we do not validate whether the given calendar ID matches the real calendar ID of the event.
This is due to a limitation of the Microsoft Graph API.
(Not supported for iCloud) You can use `primary` to query the user's primary calendar.
skip_nylas_email:
name: skip_nylas_email
in: query
schema:
type: boolean
default: false
description: When `true`, Nylas does not send the RSVP email to the event organizer.
limit_contacts:
name: limit
in: query
required: false
schema:
type: integer
default: 30
maximum: 200
description: |-
The maximum number of objects to return. See [Pagination](/docs/reference/api/#pagination)
for more information.
join_time_start:
name: join_time_start
in: query
required: false
schema:
type: number
description: |-
Filter for Notetaker bots that have join times that start at or after a specific time, in Unix
timestamp format.
join_time_end:
name: join_time_end
in: query
required: false
schema:
type: number
description: |-
Filter for Notetaker bots that have join times that end at or are before a specific time, in Unix
timestamp format.
notetaker_order_by:
name: order_by
in: query
required: false
schema:
type: string
enum:
- name
- join_time
- created_at
default: created_at
description: The field to order the Notetaker bots by.
notetaker_order_direction:
name: order_direction
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: The direction to order the Notetaker bots by.
notetaker_state:
name: state
in: query
required: false
schema:
type: string
enum:
- scheduled
- connecting
- waiting_for_entry
- failed_entry
- attending
- media_processing
- media_available
- media_error
- media_deleted
description: Filter for Notetaker bots with the specified meeting state.
prev_page_token:
name: prev_page_token
in: query
required: false
schema:
type: string
description: |-
An identifier that specifies which page of data to return. You can get this value from the
`prev_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more
information.
start_time:
name: start_time
in: query
required: true
schema:
type: integer
description: |-
Filter for events that start at or after the specified time, in seconds using the Unix timestamp format. For example,
if you filter for events that start at 9:00a.m. and the calendar includes an event that runs from
8:30–9:30a.m., Nylas returns that event.
end_time:
name: end_time
in: query
required: true
schema:
type: integer
description: |-
Filter for events that end at or before the specified time, in seconds using the Unix timestamp format. For example,
if you filter for events that end at 5:00p.m. and the calendar includes an event that runs from
4:30–5:30p.m., Nylas returns that event.
account_id:
name: account_id
required: true
in: path
schema:
type: string
example: df0yq6c9okc6t9j4ejd5nyrt7
](https://god.gw.postman.com/run-collection/21157315-b864762a-ddbb-4e08-bcc5-e87bb51a825a?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D21157315-b864762a-ddbb-4e08-bcc5-e87bb51a825a%26entityType%3Dcollection%26workspaceId%3De36cf1fc-a749-494d-9c8c-f3c28f18c342#?env%5Bv3%20Environment%5D=W3sia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly9hcGkudXMubnlsYXMuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6Ik55bGFzIEFQSSBiYXNlIFVSTC4gVXNlIGh0dHBzOi8vYXBpLmV1Lm55bGFzLmNvbSBmb3IgdGhlIEVVIHJlZ2lvbi4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImJlYXJlclRva2VuIiwidmFsdWUiOiIiLCJ0eXBlIjoic2VjcmV0IiwiZGVzY3JpcHRpb24iOiJZb3VyIE55bGFzIEFQSSBrZXkgZnJvbSB0aGUgRGFzaGJvYXJkIChodHRwczovL2Rhc2hib2FyZC12My5ueWxhcy5jb20pLiBVc2VkIGZvciBhbGwgYXV0aGVudGljYXRlZCByZXF1ZXN0cy4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImdyYW50X2lkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiVGhlIGdyYW50IElEIHJlcHJlc2VudGluZyBhbiBlbmQgdXNlcidzIGNvbm5lY3RlZCBhY2NvdW50LiBSZXF1aXJlZCBmb3IgRUNDICYgU2NoZWR1bGVyIGNvbGxlY3Rpb25zLiBGaW5kIHRoaXMgaW4gdGhlIERhc2hib2FyZCB1bmRlciBHcmFudHMuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJhY2Nlc3NfdG9rZW4iLCJ2YWx1ZSI6IiIsInR5cGUiOiJzZWNyZXQiLCJkZXNjcmlwdGlvbiI6IkEgdXNlci1sZXZlbCBhY2Nlc3MgdG9rZW4gcmV0dXJuZWQgZnJvbSB0aGUgT0F1dGggZmxvdy4gQWx0ZXJuYXRpdmUgdG8gdXNpbmcgQVBJIGtleSArIGdyYW50X2lkIGZvciBwZXItdXNlciBhdXRoLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBwbGljYXRpb25faWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJZb3VyIE55bGFzIGFwcGxpY2F0aW9uIElELiBBdXRvLXNldCBieSB0aGUgJ1ZlcmlmeSBBUEkga2V5JyByZXF1ZXN0IGluIHRoZSBBZG1pbiBjb2xsZWN0aW9uLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoicHJvdmlkZXIiLCJ2YWx1ZSI6Imdvb2dsZSIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJBdXRoIHByb3ZpZGVyIGZvciBjb25uZWN0b3Igb3BlcmF0aW9uczogZ29vZ2xlLCBtaWNyb3NvZnQsIGltYXAsIG9yIHZpcnR1YWwtY2FsZW5kYXIuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjYWxsYmFja19pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IlJlZGlyZWN0IFVSSSBJRC4gU2V0IGFmdGVyIGNyZWF0aW5nIGEgY2FsbGJhY2sgVVJJIGluIHRoZSBBZG1pbiBjb2xsZWN0aW9uLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY3JlZGVudGlhbF9pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IkNvbm5lY3RvciBjcmVkZW50aWFsIElEIGZvciBzZXJ2aWNlIGFjY291bnRzIG9yIGFwcCBwYXNzd29yZHMuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ3ZWJob29rX2lkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiV2ViaG9vayBkZXN0aW5hdGlvbiBJRC4gU2V0IGFmdGVyIGNyZWF0aW5nIGEgd2ViaG9vay4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNoYW5uZWxfaWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJQdWIvU3ViIGNoYW5uZWwgSUQuIFNldCBhZnRlciBjcmVhdGluZyBhIGNoYW5uZWwuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ3b3Jrc3BhY2VfaWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJXb3Jrc3BhY2UgSUQgZm9yIGdyYW50IGdyb3VwaW5nICYgb3JnYW5pemF0aW9uLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBpX2tleV9pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IkFQSSBrZXkgcmVzb3VyY2UgSUQgKG5vdCB0aGUga2V5IGl0c2VsZikuIFVzZWQgZm9yIG1hbmFnaW5nIEFQSSBrZXlzIHZpYSB0aGUgQWRtaW4gQVBJLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibnlsYXNfY2xpZW50X2lkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiWW91ciBOeWxhcyBhcHBsaWNhdGlvbidzIGNsaWVudCBJRC4gVXNlZCBpbiBob3N0ZWQgT0F1dGggYXV0aG9yaXphdGlvbiBVUkxzLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibnlsYXNfY2xpZW50X3NlY3JldCIsInZhbHVlIjoiIiwidHlwZSI6InNlY3JldCIsImRlc2NyaXB0aW9uIjoiWW91ciBOeWxhcyBhcHBsaWNhdGlvbidzIGNsaWVudCBzZWNyZXQuIFVzZWQgaW4gdGhlIE9BdXRoIHRva2VuIGV4Y2hhbmdlIHN0ZXAuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJyZWRpcmVjdF91cmkiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJPQXV0aCBjYWxsYmFjayBVUkwgcmVnaXN0ZXJlZCB3aXRoIHlvdXIgTnlsYXMgYXBwbGljYXRpb24uIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJyZXNwb25zZV90eXBlIiwidmFsdWUiOiJjb2RlIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6Ik9BdXRoIHJlc3BvbnNlIHR5cGUuIFVzZSAnY29kZScgZm9yIHNlcnZlci1zaWRlIGF1dGggKHJlY29tbWVuZGVkKSBvciAndG9rZW4nIGZvciBjbGllbnQtc2lkZS4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNvZGUiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJBdXRob3JpemF0aW9uIGNvZGUgcmV0dXJuZWQgZnJvbSBob3N0ZWQgT0F1dGguIFVzZWQgdG8gZXhjaGFuZ2UgZm9yIGFuIGFjY2VzcyB0b2tlbi4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImlkX3Rva2VuIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiSUQgdG9rZW4gZm9yIGN1c3RvbSBhdXRoZW50aWNhdGlvbiBmbG93cy4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImVtYWlsIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiRW1haWwgYWRkcmVzcyB1c2VkIGFzIGxvZ2luX2hpbnQgaW4gT0F1dGggZmxvd3MuIFByZS1maWxscyB0aGUgcHJvdmlkZXIgc2lnbi1pbiBwYWdlLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZ29vZ2xlX2NsaWVudF9pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IllvdXIgR29vZ2xlIE9BdXRoIGNsaWVudCBJRC4gVXNlZCB3aGVuIGNyZWF0aW5nIGEgR29vZ2xlIGNvbm5lY3Rvci4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Imdvb2dsZV9jbGllbnRfc2VjcmV0IiwidmFsdWUiOiIiLCJ0eXBlIjoic2VjcmV0IiwiZGVzY3JpcHRpb24iOiJZb3VyIEdvb2dsZSBPQXV0aCBjbGllbnQgc2VjcmV0LiBVc2VkIHdoZW4gY3JlYXRpbmcgYSBHb29nbGUgY29ubmVjdG9yLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY2FsZW5kYXJfaWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJDYWxlbmRhciBJRC4gQ2FuIGJlIHRoZSBncmFudCdzIGVtYWlsIGFkZHJlc3Mgb3IgJ3ByaW1hcnknIGZvciB0aGUgZGVmYXVsdCBjYWxlbmRhci4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImV2ZW50X2lkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiRXZlbnQgSUQuIEF1dG8tc2V0IGJ5IHRlc3Qgc2NyaXB0cyB3aGVuIGNyZWF0aW5nIG9yIGxpc3RpbmcgZXZlbnRzLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibWVzc2FnZV9pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6Ik1lc3NhZ2UgSUQuIEF1dG8tc2V0IGJ5IHRlc3Qgc2NyaXB0cyB3aGVuIGxpc3Rpbmcgb3Igc2VuZGluZyBtZXNzYWdlcy4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRocmVhZF9pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IlRocmVhZCBJRC4gQXV0by1zZXQgYnkgdGVzdCBzY3JpcHRzIHdoZW4gbGlzdGluZyB0aHJlYWRzLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZHJhZnRfaWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJEcmFmdCBJRC4gQXV0by1zZXQgYnkgdGVzdCBzY3JpcHRzIHdoZW4gY3JlYXRpbmcgZHJhZnRzLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZm9sZGVyX2lkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiRm9sZGVyIG9yIGxhYmVsIElELiBBdXRvLXNldCBieSB0ZXN0IHNjcmlwdHMgd2hlbiBsaXN0aW5nIGZvbGRlcnMuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJhdHRhY2htZW50X2lkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiQXR0YWNobWVudCBJRC4gQXV0by1zZXQgYnkgdGVzdCBzY3JpcHRzIHdoZW4gbGlzdGluZyBtZXNzYWdlIGF0dGFjaG1lbnRzLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29udGFjdF9pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IkNvbnRhY3QgSUQuIEF1dG8tc2V0IGJ5IHRlc3Qgc2NyaXB0cyB3aGVuIGxpc3Rpbmcgb3IgY3JlYXRpbmcgY29udGFjdHMuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJub3RldGFrZXJfaWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJOb3RldGFrZXIgSUQuIFNldCBhZnRlciBpbnZpdGluZyBhIG5vdGV0YWtlciBib3QgdG8gYSBtZWV0aW5nLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidGVtcGxhdGVfaWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJNZXNzYWdlIHRlbXBsYXRlIElELiBBdXRvLXNldCBieSB0ZXN0IHNjcmlwdHMgd2hlbiBjcmVhdGluZyB0ZW1wbGF0ZXMuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ3b3JrZmxvd19pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IldvcmtmbG93IElELiBBdXRvLXNldCBieSB0ZXN0IHNjcmlwdHMgd2hlbiBjcmVhdGluZyB3b3JrZmxvd3MuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzY2hlZHVsZV9pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IlNjaGVkdWxlIElEIGZvciBFeHRyYWN0QUkgb3BlcmF0aW9ucy4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRvbWFpbl9uYW1lIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiRG9tYWluIG5hbWUgZm9yIGN1c3RvbSBkb21haW4gb3BlcmF0aW9ucy4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNvbmZpZ3VyYXRpb25faWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJTY2hlZHVsZXIgY29uZmlndXJhdGlvbiBJRC4gQXV0by1zZXQgYnkgdGVzdCBzY3JpcHRzIHdoZW4gY3JlYXRpbmcgYSBjb25maWd1cmF0aW9uLiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic2Vzc2lvbl9pZCIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IlNjaGVkdWxlciBzZXNzaW9uIElELiBBdXRvLXNldCBieSB0ZXN0IHNjcmlwdHMgd2hlbiBjcmVhdGluZyBhIHNlc3Npb24uIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJib29raW5nX2lkIiwidmFsdWUiOiIiLCJ0eXBlIjoiZGVmYXVsdCIsImRlc2NyaXB0aW9uIjoiQm9va2luZyBJRC4gQXV0by1zZXQgYnkgdGVzdCBzY3JpcHRzIHdoZW4gY3JlYXRpbmcgYSBib29raW5nLiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZ3JvdXBfZXZlbnRfaWQiLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJHcm91cCBldmVudCBJRCBmb3IgY29sbGFib3JhdGl2ZSBzY2hlZHVsaW5nIHdpdGggbXVsdGlwbGUgcGFydGljaXBhbnRzLiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic2NoZWR1bGVyU2Vzc2lvblRva2VuIiwidmFsdWUiOiIiLCJ0eXBlIjoic2VjcmV0IiwiZGVzY3JpcHRpb24iOiJTaG9ydC1saXZlZCBzZXNzaW9uIHRva2VuIGZvciBwdWJsaWMtZmFjaW5nIFNjaGVkdWxlciBlbmRwb2ludHMgKEF2YWlsYWJpbGl0eSwgQm9va2luZ3MpLiBDcmVhdGVkIHZpYSB0aGUgU2Vzc2lvbnMgZW5kcG9pbnQuIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJ2Ml9zY2hlZHVsZXJfc2x1ZyIsInZhbHVlIjoiIiwidHlwZSI6ImRlZmF1bHQiLCJkZXNjcmlwdGlvbiI6IlNsdWcgZnJvbSBhIHYyIFNjaGVkdWxlciBwYWdlLiBVc2VkIGZvciBtaWdyYXRpbmcgdjIgc2NoZWR1bGluZyBwYWdlcyB0byB2MyBjb25maWd1cmF0aW9ucy4iLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InBhZ2VfdG9rZW4iLCJ2YWx1ZSI6IiIsInR5cGUiOiJkZWZhdWx0IiwiZGVzY3JpcHRpb24iOiJQYWdpbmF0aW9uIGN1cnNvci4gUGFzcyB0aGUgbmV4dF9jdXJzb3IgdmFsdWUgZnJvbSBhIGxpc3QgcmVzcG9uc2UgdG8gZ2V0IHRoZSBuZXh0IHBhZ2Ugb2YgcmVzdWx0cy4iLCJlbmFibGVkIjp0cnVlfV0=)
## Enable compression to optimize performance
The Email, Calendar, Contacts, and Scheduler APIs return gzip-compressed responses when your request includes the [`Accept-Encoding: gzip`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header. Most HTTP libraries negotiate and decompress gzip responses automatically. With curl, use `--compressed`. Nylas skips compression for responses under about 200 bytes.
Compression pairs well with [query parameters](#query-parameters) that limit the number of objects returned and [field selection](#reduce-response-size-with-field-selection) that limits which fields come back in each object. For the full walkthrough, including webhook, Pub/Sub, and SNS compression, see [Reducing payload size with compression](/docs/dev-guide/best-practices/compression/).
## Query parameters
Nylas allows you to include query parameters in `GET` requests that return a list of results. Query parameters let you narrow the results Nylas returns, meaning fewer requests to the provider and less data for your application to sift through. For more information, see [Rate limits in Nylas](/docs/dev-guide/platform/rate-limits/).
The table below shows the query parameters you can use for the `GET` requests in the Email, Calendar, Contacts, and Notetaker APIs.
| Endpoint | Query parameters |
| :------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`GET /v3/grants/