&metadata_pair=key1:on-site`\n\nYou 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.\n\n## Reduce response size with field selection\n\nField selection allows you to use the `select` query parameter to specify which fields you want Nylas to include in the response.\n\nYou can use field selection for all Nylas API endpoints, _except_ the following:\n\n- All `DELETE` endpoints.\n- All Attachments endpoints.\n- All Smart Compose endpoints.\n- The Send Message endpoint.\n- The Create a Draft endpoint.\n\nField 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.\n\nField selection can evaluate top-level object fields only. You cannot use it to return only nested fields.\n\n📝 Note: Nylas strongly suggests you always use field selection, so you only get the data that you need.
\n\nFor example, the following request specifies Nylas should return only the `id` and `name` fields of the Calendar object.\n\n```bash\ncurl --request GET \\\n --url 'https://api.us.nylas.com/v3/grants/me/calendars?select=id,name'\n```\n\nThe response payload includes only the `id` and `name` fields in the `data` object, as in the example below.\n\n```json\n{\n \"request_id\": \"5fa64c92-e840-4357-86b9-2aa364d35b88\",\n \"data\": [\n {\n \"id\": \"5d3qmne77v32r8l4phyuksl2x\",\n \"name\": \"My Calendar\"\n },\n {\n \"id\": \"5d3qmne77v32r23aphyuksl2x\",\n \"name\": \"My Calendar 2\"\n }\n ]\n}\n```\n\n## Nylas encoding\n\nResponse bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise.\n",
"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.\n\n🔍 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.
\n\nThe 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.\n\nNylas 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.\n\n## Application callback URIs\n\nYour 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.\n\nYou 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.\n\n## Application limitations\n\n⚠️ You can create, edit, and delete applications from the Nylas Dashboard. You cannot create, edit, or delete them using the Nylas APIs.
\n\nKeep the following limitations in mind as you work with Nylas applications:\n\n- 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.\n- 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.\n- Applications cannot be nested, and cannot be set up with parent-child relationships.\n- 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.\n - In an ideal scenario, your application will have multiple callback URIs defined.\n"
},
{
"name": "Authentication APIs",
"description": "Nylas provides two ways to handle authentication:\n\n- **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/).\n- **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.\n\n## Hosted authentication with OAuth\n\nOAuth 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.\n\nDuring 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.\n\n### Using Hosted OAuth\n\nTo 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.\n\nNylas can detect which provider a user is authenticating with and redirect them to the correct provider's authentication system.\n\nIf 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.\n\nA successful OAuth authorization results in a [grant](/docs/reference/api/manage-grants/) with the scopes that the user allowed.\n\nSee [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.\n\n### Adding the \"Sign in with Google\" button\n\nYour 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.\n\nFor Hosted authentication, Nylas recommends you do one of the following:\n\n- 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/).\n\n ⚠️ 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.\n
\n\n- 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).\n\nFor 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.\n\nLearn more about [Google verification and security assessment](/docs/provider-guides/google/google-verification-security-assessment-guide/).\n"
},
{
"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.\n\nThere are several ways to create grants:\n\n- Using [Hosted OAuth and an API key](/docs/v3/auth/hosted-oauth-apikey/).\n- 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.\n- Using [Bring Your Own Authentication](/docs/v3/auth/custom/).\n- Using a special [bulk auth grant](/docs/v3/auth/bulk-auth-grants/) (also called a \"service account\").\n\nYou can re-authenticate grants using any of these methods, and Nylas handles all the re-authentication logic internally.\n\n## Grant expiry\n\nGrants, 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.\n\nUsually 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.\n\n## Re-authentication and notifications\n\nGrants 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.\n\nWhen 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.\n\nIf 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.\n\n\n\n## Grant limitations\n\nWhen working with grants, keep the following limitations in mind:\n\n- You can re-authenticate a grant to add new scopes, remove scopes, or extend its expiry date.\n- 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.\n- Grants expire after a pre-defined period of time. When this happens, they must be re-authenticated.\n\n## Grant notifications\n\nYou can subscribe to the following triggers so Nylas notifies you about changes to your users' data:\n\n- `grant.created`\n- `grant.updated`\n- `grant.deleted`\n- `grant.expired`\n\nFor more information, see the [Grant notification schemas](/docs/reference/notifications/#grant-notifications).\n"
},
{
"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.\n\nA 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.\n\n## Connector contents\n\nThe 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.\n\nThe \"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.\n\nNylas 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.\n\n### What are limitations of connectors?\n\nConnectors are associated with a single [Nylas application](/docs/reference/api/applications/).\n\nYou can have only one Nylas connector for each type of provider. For example, your Nylas application can have only one Google connector.\n\nIf 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/).\n"
},
{
"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.\n\nBulk 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/).\n\nBoth Google and Microsoft bulk authentication grants can use connector credentials.\n\nTo 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.\n\n## Connector credential limitations\n\nKeep the following limitations in mind as you work with connector credentials:\n\n- A connector credential _must_ be connected to an existing Nylas connector.\n- Each connector credential must have a unique name.\n- 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.\n"
},
{
"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`).\n\n## Assign grants to workspaces\n\nNylas offers two endpoints to manage workspaces and the grants they contain:\n\n- [**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.\n- [**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.\n\n## Default workspace\n\nA 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`.\n\nWhen 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.\n\nThe 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.\n\n## Policies and rules\n\nWorkspaces 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.\n\n## Workspace limitations\n\n- 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`.\n- 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/).\n- 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/).\n"
},
{
"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.\n\n## Nylas Service Account\n\n⚠️
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.
\n\nTo 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.\n\nWebhooks 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.\n\n## Testing webhooks\n\nNylas includes two utility API endpoints to help you identify problems with your webhook configuration.\n\nUse 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.\n\nUse 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.\n\n## Monitor grant status\n\nThe 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.\n\nThe `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).\n\n 📝 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.\n\nIf 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.
\n\n## iCloud limitation for Calendar notifications\n\nBecause iCloud doesn't support the `primary` property for calendars, Nylas sends `calendar.updated` notifications for changes to all calendars on an iCloud account.\n\n## Gmail metadata notifications\n\nNylas 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.\n\nWhen 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/).\n\n## Payload size limit and truncation\n\nNylas 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.\n\nWhen 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.\n\nIf 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.\n\nYou 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.\n\n## Payload compression\n\nSet `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/).\n\n## How to handle webhook failures\n\nNylas 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.\n\n- **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.\n- **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.\n\n⚠️ Nylas does not automatically restart or reactivate failed webhooks.
\n\nThis 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.\n\n## Duplicate webhook notifications\n\nNylas 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).\n\n## Webhook triggers\n\n- `contact.updated`: A contact was modified or updated.\n- `contact.deleted`: A contact was deleted.\n- `calendar.created`: A calendar was created.\n- `calendar.updated`: A calendar was updated or modified.\n- `calendar.deleted`: A calendar was deleted.\n- `event.created`: An event was created on a user's calendar.\n- `event.updated`: An event was updated or modified.\n- `event.deleted`: An event was deleted.\n- `grant.created`: A new grant was authenticated.\n- `grant.updated`: A grant was modified, updated, or re-authenticated.\n- `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/).\n- `grant.expired`: A grant's credentials have expired, and the user must re-authenticate.\n- `message.created`: A message was created.\n- `message.created.cleaned`: A cleaned (parsed) version of a newly created message was processed. Requires Clean Conversations to be enabled.\n- `message.updated`: A message was updated.\n- `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/).\n- `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/).\n- `message.bounce_detected`: (Available for Google, Microsoft Graph, iCloud, and Yahoo) A message bounced or was not delivered.\n- `message.opened`, `message.opened.legacy`: A participant opened a tracked message.\n- `message.link_clicked`, `message.link_clicked.legacy`: A participant clicked a link in a tracked message.\n- `thread.replied`, `thread.replied.legacy`: A participant replied to a message in a tracked thread.\n- `folder.created`: A folder or label was created.\n- `folder.updated`: A folder or label was modified or updated.\n- `folder.deleted`: A folder or label was deleted.\n- `booking.created`: A new Scheduler event was created.\n- `booking.rescheduled`: A Scheduler event was rescheduled through Scheduler.\n- `booking.cancelled`: A Scheduler event was cancelled through the Scheduler.\n- `booking.pending`: A pending booking was created.\n- `booking.reminder`: Nylas sent a reminder about a booking.\n\nFor more information on webhook trigger types, and for schema examples, see the [notification schemas](/docs/reference/notifications/).\n\n## Scheduler events in Calendar webhooks\n\nCalendar events that Nylas Scheduler creates also produce standard `event.*` notifications. Nylas stamps these events with metadata so you can identify them in Calendar webhooks:\n\n- `source`: Always `scheduler`.\n- `key5`: The Scheduler Configuration ID.\n- `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.\n\nTo 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.\n\nThese 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.\n"
},
{
"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.\n\nNylas offers Pub/Sub and Amazon SNS notification channels. These can be used in place of, or in addition to, normal webhook notifications.\n\nTo 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/).\n\nTo 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/).\n\nNylas 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/).\n\n## Payload compression\n\nBoth 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/).\n\n## Monitor grant status\n\nThe 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.\n\nThe `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).\n\n 📝 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.\n\nIf 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.\n\n
\n"
},
{
"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.\n\nTo 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/).\n\nThe 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/).\n\nNylas 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/).\n"
},
{
"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`.\n\nNylas 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/).\n\n## Adding attachments to messages\n\nUse 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/).\n\n### Provider IDs for messages\n\nNylas 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.\n\n## Metadata on messages\n\nYou 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/).\n\n[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.\n\n## Messages scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :------------------------------------------------------- | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |\n| **GET** `/messages`
**GET** `/messages/` | `/gmail.readonly` ☑️
`/gmail.modify` | `Mail.Read` ☑️
`Mail.ReadWrite`
`Mail.Read.Shared``Mail.ReadWrite.Shared` |\n| **PUT**`/messages/` | `/gmail.modify` ☑️ | `Mail.ReadWrite` ☑️
`Mail.ReadWrite.Shared` |\n| **DELETE** `/messages/` | `/gmail.modify` ☑️
`https://mail.google.com/` (for hard-delete) | `Mail.ReadWrite` ☑️
`Mail.ReadWrite.Shared` |\n| **POST** `/messages/send` | `/gmail.send` ☑️
`/gmail.compose`
`/gmail.modify` | `Mail.ReadWrite` ☑️
`Mail.ReadWrite.Shared` |\n\nNo 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.\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n\n## Messages notifications\n\nYou can subscribe to the following triggers so Nylas notifies you about changes to your users' data:\n\n- `message.created`\n- `message.updated`\n\nYou can subscribe to the following triggers to get notifications about the status of a scheduled message:\n\n- `message.send_success`\n- `message.send_failed`\n- `message.bounce_detected` (Available for Google, Microsoft Graph, iCloud, and Yahoo.)\n\nTo 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).\n\n## Message tracking and send status monitoring\n\nYou 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/).\n\nNylas 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.\n\nYou 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/).\n\n## Search messages\n\nSearch for messages by making a [`GET /v3/grants//messages` request](/docs/reference/api/messages/get-messages/) that includes any of the following query parameters:\n\n- `subject`, `thread_id`\n- `any_email`, `to`, `from`, `cc`, `bcc`\n- `received_before`, `received_after`\n- `in`, `unread`, `starred`, `has_attachment`\n- `search_query_native`\n- `fields`\n\n⚠️
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` |\n| **POST** `/folders`
**PUT** `/folders/`
**DELETE** `/folders/` | `/gmail.labels` ☑️
`/gmail.modify` | `Mail.ReadWrite` ☑️
`Mail.ReadWrite.Shared` |\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n\n## Folders notifications\n\nYou can subscribe to the following triggers so Nylas notifies you about changes to your users' data:\n\n- `folder.created`\n- `folder.updated`\n- `folder.deleted`\n\nFor more information, see the [Folder notification schemas](/docs/reference/notifications/#folder-notifications).\n\n## Folders limitations\n\nKeep the following limitations in mind when you're working with folders:\n\n- 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.\n - For Microsoft, you can use the `parent_id` to reflect the folder hierarchy in your project.\n - On IMAP, the hierarchy is reflected in the folder name (for example, `Accounting.Taxes` or `INBOX\\Accounting\\Taxes`).\n- 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).\n- 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.\n- 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.\n- It might take up to 10 minutes for folders to be available in Nylas after you authenticate an IMAP grant.\n"
},
{
"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/).\n\nIf 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.\n\nYou can make a [Get Attachment Metadata request](/docs/reference/api/attachments/get-attachments-id/) to retrieve a single attachment's metadata using its ID.\n\n## What counts as an attachment?\n\nIn Nylas, an attachment is any file included either inline as part of a message, or attached to a message as a file.\n\nSome 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.\n\n## Attachment size discrepancies\n\nWhen 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.\n\n## Attachments scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :----------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------- |\n| **GET** `/attachments/`**GET** `/attachments//download` | `/gmail.readonly` ☑️`/gmail.modify` | `Mail.Read` ☑️`Mail.ReadWrite``Mail.ReadWrite.Shared``Mail.Read.Shared` |\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n\n## Query IMAP server directly\n\nSet 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.\n\nKeep 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.\n\n## Microsoft attachment size discrepancies\n\nIf 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.\n\nWhen working with attachments on Microsoft grants, we recommend you...\n\n- Treat the metadata `size` field as an estimate for UI display purposes.\n- Always use the actual downloaded file for storage calculations and file operations.\n- Implement flexible buffer handling when the exact byte count of a file matters to your project.\n- Test your Nylas integration with a number of different attachment types and sizes.\n"
},
{
"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.\n\nIf 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.\n\nTo enable SSE for a request, add the `Accept: text/event-stream` header.\n\nFor more information, see the [Smart Compose documentation](/docs/v3/email/smart-compose/).\n\n## Smart Compose scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------- |\n| **POST** `/messages/smart-compose`**POST** `/messages//smart-compose` | `/gmail.readonly` ☑️`/gmail.modify` | `Mail.Read` ☑️`Mail.ReadWrite``Mail.ReadWrite.Shared``Mail.Read.Shared` |\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n"
},
{
"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`.\n\nDepending 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.\n\nA 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.\n\n## Find a calendar ID\n\nYou 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.\n\nFor virtual calendars, the `primary` calendar is the first created for a virtual account. You _cannot_ delete a virtual calendar that's designated as `primary`.\n\nFor iCloud, there is no `primary` calendar.\n\n## Free/Busy information\n\nThe [Get Free/Busy Schedule endpoint](/docs/reference/api/calendar/post-calendars-free-busy/) is available for all providers, including Virtual Calendars, except for iCloud.\n\nThe [Get Availability endpoint](/docs/reference/api/calendar/post-availability/) doesn't support the `free_busy` object.\n\n## Virtual calendars\n\nNylas 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.\n\nFor more information, see [Using virtual calendars](/docs/v3/calendar/virtual-calendars/).\n\n## Metadata on calendars\n\nYou 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/).\n\n## Calendar scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |\n| **GET** `/calendars`**GET** `/calendars/`**POST** `/calendars/free-busy`**POST** `/calendars/availability` | `/calendar.readonly` ☑️`/calendar` | `Calendars.Read` ☑️`Calendars.ReadWrite` |\n| **POST** `/calendars`**PUT** `/calendars/`**DELETE** `/calendars/` | `/calendar` ☑️ | `Calendars.ReadWrite` ☑️ |\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n\n## Calendar activity notifications\n\nYou can subscribe to the following triggers so Nylas notifies you about changes to your users' calendar data:\n\n- `calendar.created`\n- `calendar.updated`\n- `calendar.deleted`\n\nFor more information, see the [Calendar webhook notification schemas](/docs/reference/notifications/#calendar-notifications).\n\n## Microsoft event considerations\n\nMicrosoft 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.\n"
},
{
"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.\n\nThe 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.\n\n## Metadata on events\n\nYou 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/).\n\n[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.\n\n## Virtual calendars\n\nNylas 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.\n\nFor more information, see [Using virtual calendars](/docs/v3/calendar/virtual-calendars/).\n\n## Events scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------- |\n| **GET** `/events`**GET** `/events/` | `/calendar.events.readonly` ☑️`/calendar.events``/calendar` (Required to use `primary` keyword when referencing calendars.) | `Calendars.Read` ☑️`Calendars.ReadWrite` |\n| **POST** `/events`**PUT** `/events/`**DELETE** `/events/`**POST** `/events//send-rsvp` | `/calendar.events` ☑️`/calendar` (Required to use `primary` keyword when referencing calendars.) | `Calendars.ReadWrite` ☑️ |\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n\n## Events notifications\n\nYou can subscribe to the following notification triggers so Nylas notifies you about changes to your users' event data:\n\n- `event.created`\n- `event.updated`\n- `event.deleted`\n\nThese 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).\n\n## Microsoft event considerations\n\nMicrosoft 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.\n\n## iCloud query considerations\n\nIf 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.\n\n```json\n\"error\": {\n \"type\": \"invalid_request_error\",\n \"message\": \"The maximum time range for iCloud event queries is 6 months.\"\n}\n```\n\nFor more information about searching for events, see [Searching with Nylas](/docs/dev-guide/best-practices/search/#search-for-events).\n"
},
{
"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.\n\n## Room resource booking scopes\n\nThe 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.\n\nThe ☑️ character indicates the most restrictive scopes you can use for each provider.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :---------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |\n| **GET** `/v3/grants//resources` | `/admin.directory.resource.calendar.readonly` ☑️️ | `Place.Read.All` ☑️️ |\n\nFor more information, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n"
},
{
"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`.\n\n## Contacts scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------- | :----------------------------------------------------- |\n| **GET** `/contacts`**GET** `/contacts/`**GET** `/contact_groups` | `/contacts.readonly` ☑️`/contacts.other.readonly` ☑️`/directory.readonly`\\* ☑️ | `Contacts.Read` ☑️`People.Read`\\* ☑️ |\n| **POST** `/contacts`**PUT** `/contacts/`**DELETE** `/contacts/` | `/contacts` ☑️ | `Contacts.ReadWrite` ☑️ |\n\n 📝 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.\n
\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n\n## Contacts notifications\n\nYou can subscribe to the following triggers so Nylas notifies you about changes to your users' data:\n\n- `contact.updated`\n- `contact.deleted`\n\nFor more information, see the [Contact notification schemas](/docs/reference/notifications/#contact-notifications).\n"
},
{
"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.\n\nThe [`/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.\n\nThe [`/v3/notetakers` endpoints](/docs/reference/api/standalone-notetaker/) let you send Notetakers that aren't connected to a grant as **standalone Notetakers**.\n\n## Calendar sync\n\nNotetaker 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.\n\n## Webhook notifications\n\nNylas sends [webhook notifications](/docs/reference/notifications/#notetaker-notifications) when a Notetaker bot is created, updated, or deleted, and when the recording media is available.\n"
},
{
"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.\n\nThe `/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.\n"
},
{
"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/).\n\n\n\nNylas supports the following templating engines:\n\n- [Handlebars](https://handlebarsjs.com/)\n- [mustache }}](https://mustache.github.io/)\n- [Nunjucks](https://mozilla.github.io/nunjucks/)\n- [Twig](https://twig.symfony.com/)\n\nWe 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/).\n"
},
{
"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/).\n\n\n\nNylas supports the following templating engines:\n\n- [Handlebars](https://handlebarsjs.com/)\n- [mustache }}](https://mustache.github.io/)\n- [Nunjucks](https://mozilla.github.io/nunjucks/)\n- [Twig](https://twig.symfony.com/)\n\nWe 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/).\n"
},
{
"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).\n\nEach 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/).\n\n\n"
},
{
"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).\n\nEach workflow is linked to the grant specified in the [Create Workflow request](/docs/reference/api/grant-level-workflows/create-grant-workflow/).\n\n\n"
},
{
"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.\n\nA 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`.\n\nAfter 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.\n\n## Agent Accounts as the organizer\n\nThe `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.\n\nTwo limits apply when an Agent Account is a participant:\n\n- Set `availability.calendar_ids` to `[\"primary\"]` and `booking.calendar_id` to `\"primary\"`. Scheduler reads and writes the Agent Account's primary calendar only.\n- 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.\n\nThe 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/).\n\n## Configurations scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :-------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |\n| **POST** `/scheduling/configurations`**PUT** `/scheduling/configuration/` | `/calendar.readonly` ☑️`/calendar` | `Calendars.Read` ☑️`Calendars.ReadWrite` |\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n"
},
{
"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.\n"
},
{
"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.\n\nWhen 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`).\n\n## Time to live\n\nFor security purposes, Nylas recommends you set the `time_to_live` value for each session and refresh the sessions as they expire.\n"
},
{
"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.\n\nWhen 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.\n\n## Availability scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :--------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |\n| **GET** `/scheduling/availability` | `/calendar.readonly` ☑️`/calendar` | `Calendars.Read` ☑️`Calendars.ReadWrite` |\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n"
},
{
"name": "Bookings",
"description": "Nylas Scheduler uses the `/v3/scheduling/bookings` endpoint to manage bookings.\n\nBookings 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).\n\n## Booking types\n\nNylas Scheduler supports two booking types, `booking` and `organizer-confirmation`.\n\n`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.\n\n### Finalizing pending bookings\n\nThe [`PUT /v3/scheduling/bookings/{booking_id}` request](/docs/reference/api/bookings/put-bookings-id/) allows the organizer to confirm or cancel a pending booking.\n\n## Booking flow\n\nThe 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:\n\n1. Validates the provided session ID and uses it to retrieve the related Configuration object.\n2. Confirms if the selected time slot is still available.\n3. Retrieves the booking participant's `grant_id`, using the list of participants' email addresses in the Configuration object.\n4. Creates an event. \n If the booking type is set to `organizer-confirmation`, a placeholder event is created in the organizer's calendar.\n5. Creates a booking entry in the database and maps the provider's event ID and Scheduler's `booking_id`.\n 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.\n6. 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.\n7. (Optional) Emits a booking (`booking.created`) or a pending booking (`booking.pending`) webhook, depending on the booking type.\n\n## Bookings scopes\n\nThe 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.\n\nThe ☑️ 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.\n\n| Endpoint | Google Scopes`https://www.googleapis.com/auth/...` | Microsoft Scopes`https://graph.microsoft.com/...` |\n| :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |\n| **POST** `/scheduling/bookings`**DELETE** `/scheduling/bookings/`**PATCH** `/scheduling/bookings/` | `/calendar.events` ☑️`/calendar` | `Calendars.ReadWrite` ☑️ |\n\nFor more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).\n"
},
{
"name": "App migration",
"description": "Before you begin, you should already have:\n\n- 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).\n- Created v3 applications to serve as the destinations for your v2 settings and connected account information.\n- [Set up equivalent provider auth apps as needed](/docs/v2/upgrade-to-v3/upgrade/auth/), especially if your users are authenticating with Microsoft.\n- [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.\n\nYou make Migration API requests using the v3 API route, using an API key from the destination v3 application.\n\nFor each application to be migrated:\n\n1. [Link apps](#post-/v3/migration-tools/link-v2v3-apps)\n2. [Import app settings](#post-/v3/migration-tools/import-v2-app)\n3. [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)\n\nMake 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.
\n"
},
{
"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.\n\nBecause every project is different, we leave it up to you to decide how your project updates the v2 IDs to v3 provider IDs.\n\nThese 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.
\n\nSome 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`.\n"
},
{
"name": "v2 Redirects",
"description": "Nylas Scheduler uses the `/v3/scheduling/should-redirect/` endpoint to redirect existing v2 Scheduling Pages to v3.\n"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/applications' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nconst applicationDetails = await nylas.applications.getDetails();\n\nconsole.log({ applicationDetails });\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\",\n)\n\napplication = nylas.applications.info()\napplication_id = application[1]\nprint(\"Application ID:\", application_id)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: ''\n)\n\napplication = nylas.applications.get_details()\nputs application\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class getApplication {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n Response application = nylas.applications().getDetails();\n \n System.out.println(application);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n val application = nylas.applications().getDetails()\n \n print(application)\n}"
}
],
"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.\n\n⚠️ This endpoint will be removed in the future when application settings are available in the Nylas Dashboard.
\n\nWhen you make a `PATCH` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[Updating objects](/docs/reference/api/#updating-objects).",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request PATCH \\\n --url 'https://api.us.nylas.com/v3/applications' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --data '{\n \"branding\": {\n \"name\": \"\",\n \"icon_url\": \"\",\n \"website_url\": \"\",\n \"description\": \"\"\n },\n \"hosted_authentication\": {\n \"background_image_url\": \"\",\n \"alignment\": \"\",\n \"color_primary\": \"\",\n \"color_secondary\": \"\",\n \"title\": \"\",\n \"subtitle\": \"<SUBTITLE>\",\n \"background_color\": \"<BACKGROUND_COLOR>\",\n \"spacing\": 10\n },\n \"callback_uris\": [\n {\n \"id\": \"<CALLBACK_URI_ID>\",\n \"url\": \"<CALLBACK_URL>\",\n \"platform\": \"<PLATFORM>\",\n \"settings\": {\n \"origin\": \"<ORIGIN>\",\n \"bundle_id\": \"<BUNDLE_ID>\",\n \"package_name\": \"<PACKAGE_NAME>\",\n \"sha1_certificate_fingerprint\": \"<SHA1_FINGERPRINT>\"\n }\n }\n ]\n }'\n"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/applications/redirect-uris' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst redirectUris = await nylas.applications.redirectUris.list();\n\nconsole.log(\"Redirect URIs:\", redirectUris);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\napplication_redirect_uris = nylas.applications.redirect_uris.list()\nprint(\"Application Redirects:\", application_redirect_uris.data)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: '<NYLAS_API_KEY>'\n)\n\nredirect_uris, _ = nylas.applications.redirect_uris.list\n\nredirect_uris.each do |uri|\n puts uri[:url]\nend\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.ListResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.RedirectUri;\n\npublic class GetApplicationCallbackUris {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<RedirectUri> redirectUris = nylas.applications().redirectUris().list();\n\n System.out.println(\"Redirect URIs: \" + redirectUris.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n\n val redirectUris = nylas.applications().redirectUris().list()\n\n println(\"Redirect URIs: ${redirectUris.data}\")\n}\n"
}
],
"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\nto your project after they complete the authentication flow. If you don't specify a `platform`,\nNylas defaults to `web`.\n\nThe OAuth protocol requires that you include the `client_secret` field for calls made to this\nendpoint, depending on the `platform` you define. If you're using\n[OAuth 2.0 with PKCE](/docs/v3/auth/hosted-oauth-accesstoken/#create-grants-with-oauth-2.0-and-pkce)\nand your platform is `js`, `ios`, `android`, or `desktop`, the `client_secret` field is not\nrequired.",
"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 \\\n --url 'https://api.us.nylas.com/v3/applications/redirect-uris' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"platform\": \"web\",\n \"url\": \"<CALLBACK_URI>\",\n \"id\": \"<CALLBACK_URI_ID>\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst redirectUri = await nylas.applications.redirectUris.create({\n requestBody: {\n url: \"<CALLBACK_URI>\",\n platform: \"web\",\n },\n});\n\nconsole.log(\"Redirect URI created:\", redirectUri);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nredirect_uri = nylas.applications.redirect_uris.create(\n request_body={\n \"url\": \"https://example.com/oauth/exchange\",\n \"platform\": \"web\",\n },\n)\n\nprint(\"Created redirect URI:\", redirect_uri)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.CreateRedirectUriRequest;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Platform;\nimport com.nylas.models.RedirectUri;\nimport com.nylas.models.Response;\n\npublic class CreateRedirectUri {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CreateRedirectUriRequest requestBody = new CreateRedirectUriRequest.Builder(\n \"<CALLBACK_URI>\", Platform.WEB)\n .build();\n\n Response<RedirectUri> redirectUri = nylas.applications().redirectUris().create(requestBody);\n\n System.out.println(\"Redirect URI created: \" + redirectUri.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.CreateRedirectUriRequest\nimport com.nylas.models.Platform\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val requestBody = CreateRedirectUriRequest.Builder(\"<CALLBACK_URI>\", Platform.WEB)\n .build()\n\n val redirectUri = nylas.applications().redirectUris().create(requestBody)\n\n println(\"Redirect URI created: ${redirectUri.data}\")\n}\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/applications/redirect-uris/<CALLBACK_URI_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function getRedirectUri() {\n try {\n const redirectUris = await nylas.applications.redirectUris.find({\n redirectUriId: \"<CALLBACK_URI_ID>\",\n });\n\n console.log(\"Callback URI:\", redirectUris);\n } catch (error) {\n console.error(\"Couldn't get callback URI:\", error);\n }\n}\n\ngetRedirectUri();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nredirect_uri = nylas.applications.redirect_uris.find(\n redirect_uri_id=\"<CALLBACK_URI_ID>\",\n)\n\nprint(redirect_uri)\n"
},
{
"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;\nimport com.nylas.models.*;\n\npublic class GetApplicationURIs {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n Response<RedirectUri> redirect_uris = nylas.applications().redirectUris().find(\"<CALLBACK_URI_ID>\");\n\n System.out.println(redirect_uris);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val redirecturis = nylas.applications().redirectUris().find(\"<CALLBACK_URI_ID>\")\n\n print(redirecturis)\n}"
}
],
"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.\n\nIf you don't define the `platform`, Nylas doesn't modify the existing settings.\n\nWhen you make a `PATCH` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[Updating objects](/docs/reference/api/#updating-objects).",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request PATCH \\\n --url 'https://api.us.nylas.com/v3/applications/redirect-uris/<CALLBACK_URI_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'\n --data '{\n \"url\": \"<UPDATED_CALLBACK_URI>\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst updated = await nylas.applications.redirectUris.update({\n redirectUriId: \"<CALLBACK_URI_ID>\",\n requestBody: {\n url: \"<UPDATED_CALLBACK_URI>\",\n },\n});\n\nconsole.log(\"Redirect URI updated:\", updated);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nredirect_uri = nylas.applications.redirect_uris.update(\n redirect_uri_id=\"<REDIRECT_URI_ID>\",\n request_body={\n \"url\": \"https://example.com/oauth/exchange\",\n \"platform\": \"web\",\n },\n)\n\nprint(\"Updated redirect URI:\", redirect_uri)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.RedirectUri;\nimport com.nylas.models.Response;\nimport com.nylas.models.UpdateRedirectUriRequest;\n\npublic class UpdateRedirectUri {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateRedirectUriRequest requestBody = new UpdateRedirectUriRequest.Builder()\n .url(\"<UPDATED_CALLBACK_URI>\")\n .build();\n\n Response<RedirectUri> updated = nylas.applications().redirectUris()\n .update(\"<CALLBACK_URI_ID>\", requestBody);\n\n System.out.println(\"Redirect URI updated: \" + updated.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.UpdateRedirectUriRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val requestBody = UpdateRedirectUriRequest.Builder()\n .url(\"<UPDATED_CALLBACK_URI>\")\n .build()\n\n val updated = nylas.applications().redirectUris().update(\"<CALLBACK_URI_ID>\", requestBody)\n\n println(\"Redirect URI updated: ${updated.data}\")\n}\n"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/applications/redirect-uris/<CALLBACK_URI_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteRedirectUriId() {\n try {\n const response = await nylas.applications.redirectUris.destroy({\n redirectUriId: \"<CALLBACK_URI_ID>\",\n });\n\n console.log(\"Callback URI deleted:\", response);\n } catch (error) {\n console.error(\"Couldn't delete callback URI:\", error);\n }\n}\n\ndeleteRedirectUriId();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.applications.redirect_uris.destroy(\n redirect_uri_id=\"<CALLBACK_URI_ID>\",\n)\n\nprint(response)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\nrequire 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: '<NYLAS_API_KEY>'\n)\n\nredirect_uris = nylas.applications.redirect_uris.destroy(redirect_uri_id: \"<CALLBACK_URI_ID>\")\n\nputs redirect_uris"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class DeleteApplicationURIs {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse redirect_uris = \n nylas.applications().redirectUris().destroy(\"<REDIRECT_URI>\");\n System.out.println(redirect_uris);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val redirecturis = nylas.applications().redirectUris().destroy(\"<REDIRECT_URIS>\")\n print(redirecturis)\n}\n"
}
],
"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.\n\nConnectors are how your Nylas application stores information it needs to connect to external\nservices. Creating a connector is the first step in setting up authentication for your project.\nSee [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.\nFor 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.\n\nHowever, 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\n[Authenticating iCloud accounts](/docs/provider-guides/icloud/) for more\ninformation.",
"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\n[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\n[Authenticating Exchange on-premises accounts](/docs/provider-guides/exchange-on-prem/)\nfor 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\n[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 \\\n --url 'https://api.us.nylas.com/v3/connectors' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"provider\": \"google\",\n \"settings\": {\n \"client_id\": \"<NYLAS_CLIENT_ID>\",\n \"client_secret\": \"<NYLAS_CLIENT_SECRET>\",\n \"topic_name\": \"<TOPIC_NAME>\"\n },\n \"scope\": [\n \"https://www.googleapis.com/auth/userinfo.email\",\n \"https://www.googleapis.com/auth/userinfo.profile\"\n ]\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createConnector() {\n try {\n const connector = await nylas.connectors.create({\n requestBody: {\n name: \"google\",\n provider: \"google\",\n settings: {\n clientId: \"<GCP_CLIENT_ID>\",\n clientSecret: \"<GCP_CLIENT_SECRET>\",\n },\n scope: [\n \"openid\",\n \"https://www.googleapis.com/auth/userinfo.email\",\n \"https://www.googleapis.com/auth/gmail.modify\",\n \"https://www.googleapis.com/auth/calendar\",\n \"https://www.googleapis.com/auth/contacts\",\n ],\n },\n });\n\n console.log(\"Connector created:\", connector);\n } catch (error) {\n console.error(\"Error creating connector:\", error);\n }\n}\n\ncreateConnector();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nconnector = nylas.connectors.create(\n request_body={\n \"provider\": \"google\",\n \"settings\": {\n \"client_id\": \"<GCP_CLIENT_ID>\",\n \"client_secret\": \"<GCP_CLIENT_SECRET>\",\n },\n \"scopes\": [\n \"openid\",\n \"https://www.googleapis.com/auth/userinfo.email\",\n \"https://www.googleapis.com/auth/gmail.modify\",\n \"https://www.googleapis.com/auth/calendar\",\n \"https://www.googleapis.com/auth/contacts\",\n ],\n }\n)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n provider: \"google\",\n settings: {\n clientId: \"<GCP_CLIENT_ID>\",\n clientSecret: \"<GCP_CLIENT_SECRET>\",\n },\n scope: [\n 'openid',\n 'https://www.googleapis.com/auth/userinfo.email',\n 'https://www.googleapis.com/auth/gmail.modify',\n 'https://www.googleapis.com/auth/calendar',\n 'https://www.googleapis.com/auth/contacts',\n ]\n}\n\nnylas.connectors.create(request_body: request_body)"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class connector {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n List<String> scope = new ArrayList<>();\n scope.add(\"openid\");\n scope.add(\"https://www.googleapis.com/auth/userinfo.email\");\n scope.add(\"https://www.googleapis.com/auth/gmail.modify\");\n scope.add(\"https://www.googleapis.com/auth/calendar\");\n scope.add(\"https://www.googleapis.com/auth/contacts\");\n\n GoogleCreateConnectorSettings settings = new GoogleCreateConnectorSettings(\n \"<GCP_CLIENT_ID>\",\n \"<GCP_CLIENT_SECRET>\",\n \"\"\n );\n\n CreateConnectorRequest request = new CreateConnectorRequest.Google(settings, scope);\n\n nylas.connectors().create(request);\n }\n} "
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.CreateConnectorRequest\nimport com.nylas.models.GoogleCreateConnectorSettings\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n var scope = listOf(\n \"openid\",\n \"https://www.googleapis.com/auth/userinfo.email\",\n \"https://www.googleapis.com/auth/gmail.modify\",\n \"https://www.googleapis.com/auth/calendar\",\n \"https://www.googleapis.com/auth/contacts\"\n )\n\n val settings : GoogleCreateConnectorSettings = GoogleCreateConnectorSettings(\n \"<GCP_CLIENT_ID>\",\n \"<GCP_CLIENT_SECRET>\",\n \"\"\n )\n\n val request : CreateConnectorRequest = CreateConnectorRequest.Google(settings, scope)\n \n nylas.connectors().create(request)\n}"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/connectors' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst listConnectors = async () => {\n try {\n const connectors = await nylas.connectors.list({});\n\n console.log(\"Connectors:\", connectors);\n } catch (error) {\n console.error(\"Error fetching connectors:\", error);\n }\n};\n\nlistConnectors();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nconnectors = nylas.connectors.list\n\nprint(\"Connectors:\", connectors)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\",\n)\n\nconnectors = nylas.connectors.list()\n\nputs connectors\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class ListDraft {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = \n new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<Connector> connectors =\n nylas.connectors().list();\n System.out.println(connectors);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n \n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val connectors = nylas.connectors().list()\n println(connectors)\n}\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/connectors/<PROVIDER>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst getConnector = async () => {\n try {\n const connector = await nylas.connectors.find({\n provider: \"google\",\n });\n\n console.log(\"Connector\", connector);\n } catch (error) {\n console.error(\"Error fetching connector:\", error);\n }\n};\n\ngetConnector();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nconnector = nylas.connectors.find(\n provider=\"google\"\n)\n\nprint(\"Connector:\", connector)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\",\n)\n\nconnectors = nylas.connectors.find(provider: \"google\")\n\nputs connectors\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class ListDraft {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = \n new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Connector> connector = \n nylas.connectors().find(AuthProvider.GOOGLE);\n System.out.println(connector);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AuthProvider\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val connector = \n nylas.connectors().find(AuthProvider.GOOGLE)\n println(connector)\n}\n"
}
]
},
"patch": {
"operationId": "update_connector_by_provider",
"tags": [
"Connectors (Integrations)"
],
"summary": "Update a connector",
"description": "Update the connector for the specified provider.\n\nWhen you make a `PATCH` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/connectors/<PROVIDER>' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"name\": \"google\"\n }'"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nconnector = nylas.connectors.update(\n provider=\"google\",\n request_body={\n \"name\": \"google\"\n }\n)\n\nprint(\"Connector:\", connector)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n scope: [\n 'https://www.googleapis.com/auth/contacts'\n ]\n}\n\nconnector = nylas.connectors.update(provider: \"google\", request_body: request_body)\n\nputs connector\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class ListDraft {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = \n new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n List<String> scope = new ArrayList<>();\n scope.add(\"https://www.googleapis.com/auth/contacts\");\n\n GoogleConnectorSettings settings = new GoogleConnectorSettings();\n\n UpdateConnectorRequest.Google request = new UpdateConnectorRequest.Google.Builder()\n .settings(settings)\n .scope(scope)\n .build();\n\n nylas.connectors().update(AuthProvider.GOOGLE, request);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AuthProvider\nimport com.nylas.models.GoogleConnectorSettings\nimport com.nylas.models.UpdateConnectorRequest\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val settings : GoogleConnectorSettings = \n GoogleConnectorSettings()\n\n val request = \n UpdateConnectorRequest.Google(settings)\n\n val connector = \n nylas.connectors().update(AuthProvider.GOOGLE, \n request)\n println(connector)\n}\n"
}
]
},
"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.\n\nTo 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 \\\n --url 'https://api.us.nylas.com/v3/connectors/<PROVIDER>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst provider = \"google\";\n\ntry {\n await nylas.connectors.destroy({ provider });\n console.log(`Connector with ID ${provider} removed successfully.`);\n} catch (error) {\n console.error(\"Error removing connector:\", error);\n}\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nprovider = \"google\"\n\nrequest = nylas.connectors.destroy(\n provider,\n)\n\nprint(request)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\",\n)\n\nconnector = nylas.connectors.destroy(provider: \"google\")\n\nputs connector\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class ListDraft {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse connector = \n nylas.connectors().destroy(AuthProvider.GOOGLE);\n System.out.println(connector);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AuthProvider\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val connector = \n nylas.connectors().destroy(AuthProvider.GOOGLE)\n println(connector)\n}\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/providers/detect?email=<EMAIL>&all_provider_types=false' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst detectProvider = async () => {\n try {\n const response = await nylas.auth.detectProvider({\n email: \"<EMAIL>\",\n });\n\n console.log(\"Detected provider:\", response);\n } catch (error) {\n console.error(\"Error detecting provider:\", error);\n }\n};\n\ndetectProvider();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.auth.detect_provider({\n \"email\": \"<EMAIL>\",\n})\n\nprint(\"Detected provider:\", response)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nprovider, _ = nylas.auth.detect_provider({ email: \"<EMAIL>\" })\n\nputs provider\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class detect_provider {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n ProviderDetectParams params = new ProviderDetectParams.Builder(\"<EMAIL>\").build();\n Response<ProviderDetectResponse> provider = nylas.auth().detectProvider(params);\n\n System.out.println(provider);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ProviderDetectParams\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val params = ProviderDetectParams(\"<EMAIL>\")\n val provider = nylas.auth().detectProvider(params)\n\n print(provider)\n}"
}
],
"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.\nThis 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 \\\n --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'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\n// Build a hosted-authentication URL. Redirect the user to this URL to start\n// the OAuth flow; Nylas calls back to your `redirectUri` with an authorization\n// code that you exchange for a grant via `nylas.auth.exchangeCodeForToken()`.\nconst authUrl = nylas.auth.urlForOAuth2({\n clientId: \"<NYLAS_CLIENT_ID>\",\n provider: \"google\",\n redirectUri: \"http://localhost:3000/oauth/exchange\",\n loginHint: \"email_to_connect@example.com\",\n accessType: \"offline\",\n});\n\nconsole.log(authUrl);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "@app.route(\"/nylas/auth\", methods=[\"GET\"])\ndef login():\n if session.get(\"grant_id\") is None:\n config = URLForAuthenticationConfig({\"client_id\": \"<NYLAS_CLIENT_ID>\", \n \"redirect_uri\" : \"http://localhost:5000/oauth/exchange\"})\n\n url = nylas.auth.url_for_oauth2(config)\n return redirect(url)\n else:\n return f'{session[\"grant_id\"]}'\n\n@app.route(\"/oauth/exchange\", methods=[\"GET\"])\ndef authorized():\n if session.get(\"grant_id\") is None:\n code = request.args.get(\"code\")\n\n exchangeRequest = CodeExchangeRequest({\"redirect_uri\": \"http://localhost:5000/oauth/exchange\",\n \"code\": code, \"client_id\": \"<NYLAS_CLIENT_ID>\"})\n\n exchange = nylas.auth.exchange_code_for_token(exchangeRequest)\n session[\"grant_id\"] = exchange.grant_id\n\n return redirect(url_for(\"login\"))\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\nrequire 'nylas'\nrequire 'sinatra'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nset :show_exceptions, :after_handler\n\nerror 404 do\n 'No authorization code returned from Nylas'\nend\n\nerror 500 do\n 'Failed to exchange authorization code for token'\nend\n\n# Build the hosted-authentication URL and redirect the user there.\nget '/nylas/auth' do\n config = {\n client_id: \"<NYLAS_CLIENT_ID>\",\n provider: 'google',\n redirect_uri: 'http://localhost:4567/oauth/exchange',\n login_hint: '<email_to_connect>',\n access_type: 'offline'\n }\n\n url = nylas.auth.url_for_oauth2(config)\n redirect url\nend\n\n# Receive the authorization code and exchange it for a grant.\nget '/oauth/exchange' do\n code = params[:code]\n status 404 if code.nil?\n\n begin\n response = nylas.auth.exchange_code_for_token({\n client_id: \"<NYLAS_CLIENT_ID>\",\n redirect_uri: 'http://localhost:4567/oauth/exchange',\n code: code\n })\n rescue StandardError\n status 500\n else\n \"Grant_Id: #{response[:grant_id]} \\n Email: #{response[:email]}\"\n end\nend\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.AccessType;\nimport com.nylas.models.AuthProvider;\nimport com.nylas.models.UrlForAuthenticationConfig;\n\npublic class HostedAuthUrl {\n public static void main(String[] args) {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Build a hosted-authentication URL. Redirect the user to this URL to start\n // the OAuth flow; Nylas calls back to your `redirectUri` with an authorization\n // code that you exchange for a grant via `nylas.auth().exchangeCodeForToken()`.\n UrlForAuthenticationConfig config = new UrlForAuthenticationConfig.Builder(\n \"<NYLAS_CLIENT_ID>\",\n \"http://localhost:3000/oauth/exchange\")\n .provider(AuthProvider.GOOGLE)\n .accessType(AccessType.OFFLINE)\n .loginHint(\"email_to_connect@example.com\")\n .build();\n\n String url = nylas.auth().urlForOAuth2(config);\n\n System.out.println(url);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AccessType\nimport com.nylas.models.AuthProvider\nimport com.nylas.models.UrlForAuthenticationConfig\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n // Build a hosted-authentication URL. Redirect the user to this URL to start\n // the OAuth flow; Nylas calls back to your `redirectUri` with an authorization\n // code that you exchange for a grant via `nylas.auth().exchangeCodeForToken()`.\n val config = UrlForAuthenticationConfig.Builder(\n \"<NYLAS_CLIENT_ID>\",\n \"http://localhost:3000/oauth/exchange\")\n .provider(AuthProvider.GOOGLE)\n .accessType(AccessType.OFFLINE)\n .loginHint(\"email_to_connect@example.com\")\n .build()\n\n val url = nylas.auth().urlForOAuth2(config)\n\n println(url)\n}\n"
}
],
"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\nisn't set, the user is directed to the Nylas Hosted login page and prompted to select their\nprovider. 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\non 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\nseparated by a comma, without spaces in between. The order of the prompts affects the UI of\nthe Hosted login page.\n\nIf `provider` is not set, the user is redirected to the provider page directly, and the prompt\nis 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.\nIf 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.\nIf 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\nauthorization 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>\n"
}
}
}
},
"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.\nYou can pass one of the following `grant_type` values:\n- `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.\n - `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.\n\nThis 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.\nFor more information, see the [Hosted authentication with access token documentation](/docs/v3/auth/hosted-oauth-accesstoken/).\n### Failed token exchange requests\nEach 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\nthe authorization flow. This should match the `callback_uri` or `redirect_uri` that\nyou used to get the `code` during your initial\n[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\n[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\nsigned 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 \\\n --url \"https://api.us.nylas.com/v3/connect/token\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"client_id\": \"<NYLAS_CLIENT_ID>\",\n \"client_secret\": \"<NYLAS_API_KEY>\",\n \"grant_type\": \"authorization_code\",\n \"code\": \"<AUTHORIZATION_CODE>\",\n \"redirect_uri\": \"https://example.com/callback-handler\",\n \"code_verifier\": \"<CODE_VERIFIER>\"\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\n// Exchange the authorization code returned by Nylas for an access token and\n// grant ID. Call this from your OAuth callback handler with the `code` query\n// parameter that Nylas appends to your `redirectUri`.\nconst code = \"<AUTHORIZATION_CODE>\";\n\ntry {\n const response = await nylas.auth.exchangeCodeForToken({\n clientId: \"<NYLAS_CLIENT_ID>\",\n redirectUri: \"http://localhost:3000/oauth/exchange\",\n code,\n // Only set `codeVerifier` if you used PKCE in the initial authorization request.\n // codeVerifier: \"<PKCE_CODE_VERIFIER>\",\n });\n\n console.log(\"Grant ID:\", response.grantId);\n console.log(\"Access token:\", response.accessToken);\n} catch (error) {\n console.error(\"Error exchanging code for token:\", error);\n}\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from flask import Flask, request\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\napp = Flask(__name__)\nREDIRECT_URI = \"http://localhost:9000/oauth/exchange\"\n\n@app.route(\"/oauth/exchange\", methods=[\"GET\"])\ndef exchange_code_for_token():\n code_exchange_response = nylas.auth.exchange_code_for_token(\n request={\n \"code\": request.args.get(\"code\"),\n \"client_id\": \"<NYLAS_CLIENT_ID>\",\n \"redirect_uri\": REDIRECT_URI,\n }\n )\n\n return {\n \"email_address\": code_exchange_response.email,\n \"grant_id\": code_exchange_response.grant_id,\n }\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\nrequire 'nylas'\nrequire 'sinatra'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nset :show_exceptions, :after_handler\n\n# Receive the authorization code from Nylas and exchange it for a grant.\nget '/oauth/exchange' do\n code = params[:code]\n status 404 if code.nil?\n\n begin\n response = nylas.auth.exchange_code_for_token({\n client_id: \"<NYLAS_CLIENT_ID>\",\n redirect_uri: 'http://localhost:4567/oauth/exchange',\n code: code\n })\n rescue StandardError\n status 500\n else\n grant_id = response[:grant_id]\n email = response[:email]\n\n \"Grant_Id: #{grant_id} \\n Email: #{email}\"\n end\nend\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.CodeExchangeRequest;\nimport com.nylas.models.CodeExchangeResponse;\n\npublic class ExchangeCodeForToken {\n public static void main(String[] args) {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Exchange the authorization code returned by Nylas for an access token and\n // grant ID. Call this from your OAuth callback handler with the `code` query\n // parameter that Nylas appends to your `redirectUri`.\n CodeExchangeRequest codeRequest = new CodeExchangeRequest.Builder(\n \"http://localhost:3000/oauth/exchange\",\n \"<AUTHORIZATION_CODE>\",\n \"<NYLAS_CLIENT_ID>\")\n // Only set codeVerifier if you used PKCE in the initial authorization request.\n // .codeVerifier(\"<PKCE_CODE_VERIFIER>\")\n .build();\n\n try {\n CodeExchangeResponse codeResponse = nylas.auth().exchangeCodeForToken(codeRequest);\n\n System.out.println(\"Grant ID: \" + codeResponse.getGrantId());\n System.out.println(\"Access token: \" + codeResponse.getAccessToken());\n } catch (Exception e) {\n System.err.println(\"Error exchanging code for token: \" + e);\n }\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.CodeExchangeRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n // Exchange the authorization code returned by Nylas for an access token and\n // grant ID. Call this from your OAuth callback handler with the `code` query\n // parameter that Nylas appends to your `redirectUri`.\n val codeRequest = CodeExchangeRequest.Builder(\n \"http://localhost:3000/oauth/exchange\",\n \"<AUTHORIZATION_CODE>\",\n \"<NYLAS_CLIENT_ID>\")\n // Only set codeVerifier if you used PKCE in the initial authorization request.\n // .codeVerifier(\"<PKCE_CODE_VERIFIER>\")\n .build()\n\n try {\n val codeResponse = nylas.auth().exchangeCodeForToken(codeRequest)\n\n println(\"Grant ID: ${codeResponse.grantId}\")\n println(\"Access token: ${codeResponse.accessToken}\")\n } catch (e: Exception) {\n System.err.println(\"Error exchanging code for token: $e\")\n }\n}\n"
}
]
}
},
"/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\ngrant or the associated provider token. This means that a user can re-authenticate to get a new\naccess token for the existing grant, so their `grant_id` doesn't change.\n\nIf you revoke a Nylas access token, Nylas also revokes all child tokens and the parent\n`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 \\\n --url 'https://api.us.nylas.com/v3/connect/revoke?token=<TOKEN>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\n// Configure the Nylas SDK with your API key and server URL\nconst NylasConfig = {\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\nconst revokeToken = async () => {\n try {\n const token = \"<TOKEN>\";\n const response = await nylas.auth.revoke(token);\n\n console.log(\"Token Revoked:\", response);\n } catch (error) {\n console.error(\"Error removing connector:\", error);\n }\n};\n\nrevokeToken();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\nrequest = nylas.auth.revoke(\n \"<TOKEN>\",\n)\n\nprint(request)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\nrequire 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nbegin\n nylas.auth.revoke(\"<NYLAS_AUTH_TOKEN>\")\n puts \"The token was successfully revoked\"\nrescue Nylas::NylasApiError => e\n puts \"The token could not be revoked: #{e.message}\"\nend\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.TokenParams;\n\npublic class Main {\n public static void main(String[] args) {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n TokenParams token = new TokenParams(\"<NYLAS_ACCESS_TOKEN>\");\n\n try {\n boolean tokenStatus = nylas.auth().revoke(token);\n if (tokenStatus) {\n System.out.println(\"The token was successfully removed\");\n } else {\n System.out.println(\"The token cannot be removed\");\n }\n } catch (Exception e) {\n System.out.println(\"Invalid token cannot be removed\");\n }\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main() {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val token = TokenParams(\"<NYLAS_ACCESS_TOKEN>\")\n\n try {\n val tokenStatus = nylas.auth().revoke(token)\n if (tokenStatus) {\n println(\"The token was successfully removed\")\n } else {\n println(\"The token cannot be removed\")\n }\n } catch (e: Exception) {\n print(\"Invalid token cannot be removed\")\n }\n}\n"
}
]
}
},
"/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.\n",
"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 \\\n --url 'https://api.us.nylas.com/v3/connect/tokeninfo?id_token=<ACCESS_TOKEN_ID>&access_token=<NYLAS_ACCESS_TOKEN>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst accessToken = \"<ACCESS_TOKEN>\";\n\ntry {\n const tokenInfo = await nylas.auth.accessTokenInfo(accessToken);\n console.log(\"Token info:\", tokenInfo);\n} catch (error) {\n console.error(\"Error fetching token info:\", error);\n}\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\nrequest = nylas.auth.id_token_info(\n \"<ACCESS_TOKEN_ID>\",\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class GetTokenInfo {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n Response<TokenInfoResponse> token = nylas.auth().idTokenInfo(\"<ACCESS_TOKEN_ID>\");\n \n System.out.println(token);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val token = nylas.auth().idTokenInfo(\"<ACCESS_TOKEN_ID>\")\n \n print(token)\n}\n"
}
]
}
},
"/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\nOAuth flow in your own project or you want to migrate existing users, BYO Auth lets you provide\nthe user's `refresh_token` to create a grant.\n\nIf a user previously authenticated with your Nylas application using the same email address, Nylas\ndetects this and re-authenticates their existing grant instead of creating a new one. The API\nresponse contains the user's existing `grant_id`.\n\n### Supported providers\n\nPick the request body variant that matches your provider:\n\n- **Refresh token** — OAuth providers (`google`, `microsoft`, `yahoo`, `zoom`) using a standard refresh token.\n- **Credential override** — OAuth providers, but using a stored [credential record](/docs/reference/api/connector-credentials/) to swap in different client credentials.\n- **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).\n- **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).\n- **IMAP** — direct IMAP/SMTP credentials for any IMAP provider.\n- **iCloud** — an iCloud email address plus an [Apple app password](https://support.apple.com/en-us/HT204397).\n- **EWS** — on-premises Microsoft Exchange; hosted Exchange should use Microsoft Graph instead.\n- **Virtual calendar** — a [Virtual Calendar](/docs/v3/calendar/virtual-calendars/) grant for scheduling without a third-party provider.\n- **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`.\n- **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`.\n\nIf you add the `credential_id` field with the UUID of an existing\n[credential record](/docs/reference/api/connector-credentials/), Nylas uses the\nprovider'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\n[credential record](/docs/reference/api/connector-credentials/) that Nylas\ncan 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\nthe Nylas `credential_id`.\n\nIf a grant already exists for the provided email address, Nylas automatically starts\nthe 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\nauthenticate 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\nNylas `credential_id`.\n\nIf a grant already exists for the provided email address, Nylas automatically starts\nthe 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\nauthenticate 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\nthe provider uses a different address or credentials for SMTP (to send email),\ninclude 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\nto auto-detect the hostname using the provided `imap_username`. If you're using\na 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\ntries to auto-detect it using the provided `imap_username`. If you're using a\nself-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\nto auto-detect it using the provided `imap_username`. If you're using a self-\nhosted 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\ntries to auto-detect it using the provided `imap_username`. If you're using a\nself-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\nIMAP credentials.",
"example": "nyla@example.com"
},
"smtp_password": {
"type": "string",
"description": "The user's SMTP password, if their SMTP credentials are different from their\nIMAP 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\nto auto-detect it using the provided `ews_username`. If you're using a self-\nhosted 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\nhave 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\nflow completes. If you include the `state`, Nylas returns the unmodified value to\nyour project. You can use this for verification, or to track information about the\naccount.\n\nFor more information about the `state` parameter, see the\n[OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749) or the\n[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\nas the default `From` display name when the account sends email, so a recipient sees\n`Sales Agent <sales-agent@agents.yourcompany.com>` instead of the bare address. Omit it\nand the account sends with no display name. You can override the name on an individual\nmessage 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.\nThe workspace's `policy_id` and `rule_ids` govern the account's limits, spam detection,\nand mail rules. If omitted, Nylas auto-groups the account into a workspace whose `domain`\nmatches the email address (when `auto_group` is enabled), or places it in the\napplication'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\n[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.\nOmit it and protocol-level access stays disabled. Must be 18–40 printable ASCII\ncharacters (codes 33–126) and contain at least one uppercase letter, one lowercase\nletter, and one digit. Stored as a bcrypt hash — it can't be retrieved later, only\nreset 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 \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"microsoft\",\n \"settings\": {\n \"refresh_token\": \"<REFRESH_TOKEN>\"\n }\n }'\n"
},
{
"lang": "bash",
"label": "cURL (Google)",
"source": "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"google\",\n \"settings\": {\n \"refresh_token\": \"<GOOGLE_REFRESH_TOKEN>\"\n }\n }'\n"
},
{
"lang": "bash",
"label": "cURL (IMAP)",
"source": "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"imap\",\n \"settings\": {\n \"imap_username\": \"user@example.com\",\n \"imap_password\": \"<IMAP_PASSWORD>\",\n \"imap_host\": \"imap.example.com\",\n \"imap_port\": 993,\n \"smtp_host\": \"smtp.example.com\",\n \"smtp_port\": 587,\n \"smtp_username\": \"user@example.com\",\n \"smtp_password\": \"<SMTP_PASSWORD>\"\n }\n }'\n"
},
{
"lang": "bash",
"label": "cURL (iCloud)",
"source": "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"icloud\",\n \"settings\": {\n \"username\": \"user@icloud.com\",\n \"password\": \"<ICLOUD_APP_PASSWORD>\"\n }\n }'\n"
},
{
"lang": "bash",
"label": "cURL (Virtual Calendar)",
"source": "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/connect/custom\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"virtual-calendar\",\n \"settings\": {\n \"email\": \"conference-room-3a@example.com\"\n }\n }'\n"
},
{
"lang": "bash",
"label": "cURL (Nylas Agent Account)",
"source": "curl --location 'https://api.us.nylas.com/v3/connect/custom' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"provider\": \"nylas\",\n \"name\": \"Sales Agent\",\n \"workspace_id\": \"<WORKSPACE_ID>\",\n \"settings\": {\n \"email\": \"user@yourdomain.com\"\n }\n}'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\n// Microsoft (refresh-token) Bring-Your-Own-Auth grant.\nasync function authenticateMicrosoft() {\n const grant = await nylas.auth.customAuthentication({\n requestBody: {\n provider: \"microsoft\",\n settings: {\n refreshToken: \"<MICROSOFT_REFRESH_TOKEN>\",\n },\n scope: [\"Mail.Read\", \"Mail.Send\"],\n },\n });\n\n return grant;\n}\n\n// Nylas Agent Account grant — provisions a Nylas-hosted mailbox on a domain\n// you've registered with Nylas. No OAuth refresh token required.\nasync function authenticateAgentAccount() {\n const grant = await nylas.auth.customAuthentication({\n requestBody: {\n provider: \"nylas\",\n name: \"Sales Agent\",\n settings: {\n email: \"agent@yourdomain.com\",\n policyId: \"<POLICY_ID>\",\n },\n },\n });\n\n return grant;\n}\n\nauthenticateMicrosoft()\n .then((grant) => console.log(\"Microsoft grant:\", grant))\n .catch((error) => console.error(\"Microsoft auth error:\", error));\n\nauthenticateAgentAccount()\n .then((grant) => console.log(\"Agent Account grant:\", grant))\n .catch((error) => console.error(\"Agent Account auth error:\", error));\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\",\n)\n\nrequest_body = {\n provider: '<PROVIDER>',\n settings: {'username': '<USERNAME>', 'password': '<PASSWORD>'},\n scope: 'email.read_only,calendar.read_only,contacts.read_only',\n state: '<STATE>'\n}\n\nauth = nylas.auth.custom_authentication(request_body)\nputs auth\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nrequest_body = {\n \"provider\": \"icloud\",\n \"settings\": {\n \"username\": \"<USERNAME>\",\n \"password\": \"<PASSWORD>\",\n },\n \"scope\": [\"email.read_only\", \"calendar.read_only\", \"contacts.read_only\"],\n \"state\": \"<STATE>\",\n}\n\ngrant = nylas.auth.custom_authentication(request_body)\nprint(grant)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\n\npublic class Main {\n public static void main(String[] args) throws\n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n AuthProvider provider = AuthProvider.ICLOUD;\n\n Map<String, Object> settings = new HashMap<>();\n settings.put(\"username\", \"<USERNAME>\");\n settings.put(\"password\", \"<PASSWORD>\");\n\n List<String> scopes = List.of(\n \"email.read_only\", \"calendar.read_only\", \"contacts.read_only\");\n\n CreateGrantRequest requestBody = new CreateGrantRequest.Builder(provider, settings)\n .state(\"<STATE>\")\n .scopes(scopes)\n .build();\n\n Response<Grant> grant = nylas.auth().customAuthentication(requestBody);\n System.out.println(grant);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main() {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val provider = AuthProvider.ICLOUD\n val settings = mapOf(\"username\" to \"<USERNAME>\", \"password\" to \"<PASSWORD>\")\n val scopes = listOf(\"email.read_only\", \"calendar.read_only\", \"contacts.read_only\")\n\n val requestBody = CreateGrantRequest(provider, settings, \"<STATE>\", scopes)\n val grant = nylas.auth().customAuthentication(requestBody)\n\n println(grant)\n}\n"
}
],
"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\nNylas 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\nfrom 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\nusing 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\n[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\n[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\nseconds 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 \\\n--url 'https://api.us.nylas.com/v3/grants?limit=3&provider=google' \\\n--header 'Accept: application/json' \\\n--header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listGrants() {\n try {\n const grants = await nylas.grants.list();\n\n console.log(\"Grants found:\", grants);\n } catch (error) {\n console.error(\"Error finding grants:\", error);\n }\n}\n\nlistGrants();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\ngrants = nylas.grants.list()\n\nprint(grants)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: '<NYLAS_API_KEY>'\n)\n\ngrants, _ = nylas.grants.list()\n\ngrants.each do |grant|\n puts \"#{grant}\\n\\n\"\nend\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "// Import Nylas packages\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.List;\n\npublic class read_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n ListResponse<Grant> grants = nylas.grants().list();\n\n for(Grant grant : grants.getData()){\n System.out.println(grant);\n }\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "// Import Nylas packages\nimport com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val grants = nylas.grants().list().data;\n \n for(grant in grants){\n println(grant)\n }\n}\n"
}
],
"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.\nApplicable only for Google and Microsoft grants. Not set by default.\nFor Microsoft, aliases are only available for Microsoft 365 / Exchange Online mailboxes. Free\nOutlook.com (consumer) accounts have no aliases to expose, so the `email_aliases` field is\nomitted from the response entirely.\nEmail 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.\n\nIf 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\n// Instantiate Nylas SDK\nconst NylasConfig = {\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\n// Define the ID of the grant to find\nconst grantId = \"<NYLAS_GRANT_ID>\";\n\n// Function to find the grant\nasync function findGrant() {\n try {\n const grant = await nylas.grants.find({ grantId });\n\n console.log(\"Grant found:\", grant);\n } catch (error) {\n console.error(\"Error finding grant:\", error);\n }\n}\n\nfindGrant();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ngrant = nylas.grants.find(\n grant_id\n)\n\nprint(grant)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: '<NYLAS_API_KEY>'\n)\n\ngrant, _ = nylas.grants.find(grant_id: \"<NYLAS_GRANT_ID>\")\n\nputs grant"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class get_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n Response<Grant> grant = nylas.grants().find(\"<NYLAS_GRANT_ID>\");\n \n System.out.println(grant);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val grant = nylas.grants().find(\"<NYLAS_GRANT_ID>\")\n print(grant)\n}\n"
}
],
"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.\n\n**Common use cases:**\n\n- **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`.\n- **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.\n\nWhen you make a `PATCH` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[Updating objects](/docs/reference/api/#updating-objects).",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request PATCH \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"settings\": {\n \"refresh_token\": \"<NEW_REFRESH_TOKEN>\"\n },\n \"scope\": [\"Mail.Read\", \"Mail.Send\", \"User.Read\", \"offline_access\"]\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst NylasConfig = {\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\nasync function updateGrant() {\n try {\n const grant = await nylas.grants.update({\n grantId: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n scope: [\"mail.ready\"],\n },\n });\n\n console.log(\"Updated Grant:\", grant);\n } catch (error) {\n console.error(\"Error to update grant:\", error);\n }\n}\n\nupdateGrant();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ngrant = nylas.grants.update(\n grant_id,\n request_body={\n \"scope\": [\"mail.ready\"]\n }\n)\n\nprint(grant)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n scope: [\"mail.read\"]\n}\n\nstatus, _ = nylas.grants.update(grant_id: \"a57cdf3e-6580-4097-9d71-a95e867fb79c\", request_body: request_body)\n\nputs status"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class update_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n List<String> scope = new ArrayList<>();\n scope.add(\"mail.read\");\n\n UpdateGrantRequest requestBody = new UpdateGrantRequest.Builder().scopes(scope).build();\n Response<Grant> grant = nylas.grants().update(\"<NYLAS_GRANT_ID>\", requestBody);\n\n System.out.println(grant);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.UpdateGrantRequest\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val scope = listOf(\"mail.read\")\n val requestBody = UpdateGrantRequest(null, scope)\n val grant = nylas.grants().update(\"<NYLAS_GRANT_ID>\", requestBody);\n \n print(grant)\n}"
}
],
"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.\n\n**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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\n// Instantiate Nylas SDK\nconst NylasConfig = {\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\n// Define the identifier for the grant\nconst identifier = \"<NYLAS_GRANT_ID>\";\n\n// Function to delete the grant\nasync function destroyGrant() {\n try {\n const response = await nylas.grants.destroy({\n grantId: identifier,\n });\n\n console.log(\"Grant deleted:\", response);\n } catch (error) {\n console.error(\"Error finding grant:\", error);\n }\n}\n\ndestroyGrant();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nresponse = nylas.grants.destroy(\n grant_id\n)\n\nprint(response)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: '<NYLAS_API_KEY>'\n)\n\nstatus, _ = nylas.grants.destroy(grant_id: \"<NYLAS_GRANT_ID>\")\n\nputs status"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class read_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n DeleteResponse grant = nylas.grants().destroy(\"<NYLAS_GRANT_ID>\");\n \n System.out.println(grant);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val grant = nylas.grants().destroy(\"<NYLAS_GRANT_ID>\")\n \n print(grant)\n}"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/me' \\\n --header 'Authorization: Bearer <NYLAS_USER_ACCESS_TOKEN>' \\\n --header 'Accept: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\n// \"me\" resolves to the grant associated with the access token used on the\n// request. Pair with an ACCESS_TOKEN auth header rather than the API key.\nasync function getCurrentGrant() {\n try {\n const grant = await nylas.grants.find({\n grantId: \"me\",\n });\n\n console.log(\"Current grant:\", grant);\n } catch (error) {\n console.error(\"Error retrieving current grant:\", error);\n }\n}\n\ngetCurrentGrant();\n"
}
],
"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\nthe API key you use to authorize your request.",
"security": [
{
"NYLAS_API_KEY": []
}
],
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url \"https://api.us.nylas.com/v3/workspaces\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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\nassigned 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\nthe 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\nworkspace.",
"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\nthe workspace.",
"example": [
"3f2504e0-4f89-41d3-9a0c-0305e82c3301"
]
}
}
}
}
}
},
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url \"https://api.us.nylas.com/v3/workspaces\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"The Nylas Workspace\",\n \"domain\": \"nylas.com\",\n \"auto_group\": true,\n \"policy_id\": \"<POLICY_ID>\",\n \"rule_ids\": [\"<RULE_ID>\"]\n }'\n"
}
],
"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\nfor 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 \\\n --url \"https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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.\n\nOn 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\nassigned 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\nworkspace. Set a policy ID to attach the policy, set `null` to detach the current policy,\nor 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\nthe workspace. Set an array to replace the current rules, set `null` or an empty array to\ndetach all rules, or omit the field to keep the current value. Each rule must belong to\nyour application.",
"example": [
"3f2504e0-4f89-41d3-9a0c-0305e82c3301"
]
}
}
}
}
}
},
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request PATCH \\\n --url \"https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"policy_id\": \"<POLICY_ID>\",\n \"rule_ids\": [\"<RULE_ID>\"]\n }'\n"
}
],
"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\nvalue other than `policy_id` or `rule_ids` on the application's default workspace, or set a\n`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.\n\nTo 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 \\\n --url \"https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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\nset. 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,\nin 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\n`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 \\\n --url \"https://api.us.nylas.com/v3/workspaces/auto-group\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"after_created_at\": 1725273600,\n \"invalid_also\": true,\n \"specific_domain\": \"nylas.com\"\n }'"
}
],
"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\nleast one grant ID in either `assign_grants` or `remove_grants`. You can include up to 500 grants\nper 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 \\\n --url \"https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>/manual-assign\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"assign_grants\": [\n \"10726e7c-89c3-4a1d-9f4a-5f3f37f6f2d9\",\n \"3b9f5c1a-21d4-46c1-b84f-0e8d1f9eaa42\"\n ],\n \"remove_grants\": [\n \"5f1a2c9e-739b-4c66-9a3d-2c88a0c6d123\",\n \"9c6e4b7d-2e4a-4ef0-a1b8-badf5a76a555\"\n ]\n }'"
}
],
"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\nstring 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\nnonce, 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\na 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>\n\nCreates 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\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -H \"X-Nylas-Timestamp: 1676412353123\" \\\n -d '{\n \"name\": \"example-key\",\n \"expires_in\": 3600\n }'"
}
],
"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,\nthis 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>\n\nReturns 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\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -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\nstring 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\nnonce, 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\na 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>\n\nReturns 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>\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -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>\n\nDeletes 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>\" \\\n --header \"Content-Type: application/json\" \\\n --header \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n --header \"X-Nylas-Nonce: <NONCE>\" \\\n --header \"X-Nylas-Timestamp: 1676412353123\" \\\n --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.\n\n### Webhook destinations and retry logic\n\nYou should limit the number of webhook destinations you have for each trigger type. When Nylas\nretries a webhook, the retry goes to all the destinations for that trigger type. This can result\nin _a lot_ of notifications.\n\nSome webhook testing tools rate-limit or block you if your endpoint generates too much traffic.\nNylas blocks Ngrok connections for this reason.\n\n### Webhook notification header\n\nEvery webhook notification Nylas sends includes the `x-nylas-signature` header. If you're using\nthe 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 \\\n --url 'https://api.us.nylas.com/v3/webhooks/' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data-raw '{\n \"trigger_types\": [\n \"grant.created\",\n \"grant.deleted\",\n \"grant.expired\"\n ],\n \"description\": \"local\",\n \"webhook_url\": \"<WEBHOOK_URL>\",\n \"notification_email_addresses\": [\n \"leyah@example.com\",\n \"nyla@example.com\"\n ]\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas, { WebhookTriggers } from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst createWebhook = async () => {\n try {\n const webhook = await nylas.webhooks.create({\n requestBody: {\n triggerTypes: [WebhookTriggers.EventCreated],\n webhookUrl: \"<WEBHOOK_URL>\",\n description: \"My first webhook\",\n notificationEmailAddresses: [\"<EMAIL_ADDRESS>\"],\n },\n });\n\n console.log(\"Webhook created:\", webhook);\n } catch (error) {\n console.error(\"Error creating webhook:\", error);\n }\n};\n\ncreateWebhook();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.models.webhooks import WebhookTriggers\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nwebhook = nylas.webhooks.create(\n request_body={\n \"trigger_types\": [WebhookTriggers.EVENT_CREATED],\n \"webhook_url\": \"<WEBHOOK_URL>\",\n \"description\": \"My first webhook\",\n \"notification_email_addresses\": [\"<EMAIL_ADDRESS>\"],\n }\n)\n\nprint(webhook)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nrequest_body = {\n trigger_types: [Nylas::WebhookTrigger::EVENT_CREATED],\n webhook_url: \"<WEBHOOK_URL>\",\n description: 'My first webhook',\n notification_email_addresses: [\"<EMAIL_ADDRESS>\"]\n}\n\nbegin\n webhook, _request_id = nylas.webhooks.create(request_body: request_body)\n\n puts \"Webhook created: #{webhook}\"\nrescue Nylas::NylasApiError => e\n puts \"Error creating webhook: #{e.message}\"\nend\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class webhooks {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n List<WebhookTriggers> triggers = new ArrayList<>();\n triggers.add(WebhookTriggers.EVENT_CREATED);\n\n CreateWebhookRequest webhookRequest = new CreateWebhookRequest(\n triggers,\n \"<WEBHOOK_URL>\",\n \"My first webhook\",\n List.of(\"<EMAIL_ADDRESS>\"));\n\n try {\n Response<WebhookWithSecret> webhook = nylas.webhooks().create(webhookRequest);\n\n System.out.println(webhook.getData());\n } catch (Exception e) {\n System.out.println(\"Error: \" + e);\n }\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>){\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n val triggersList: List<WebhookTriggers> = listOf(WebhookTriggers.EVENT_CREATED)\n\n val webhookRequest: CreateWebhookRequest = CreateWebhookRequest(\n triggersList,\n \"<WEBHOOK_URL>\",\n \"My first webhook\",\n listOf(\"<EMAIL_ADDRESS>\"))\n\n try {\n val webhook: Response<WebhookWithSecret> = nylas.webhooks().create(webhookRequest)\n\n println(webhook.data)\n } catch(exception : Exception) {\n println(\"Error :$exception\")\n }\n}\n"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/webhooks' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst listWebhooks = async () => {\n try {\n const webhooks = await nylas.webhooks.list({});\n\n console.log(\"webhooks:\", webhooks);\n } catch (error) {\n console.error(\"Error fetching webhooks:\", error);\n }\n};\n\nlistWebhooks();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nwebhooks = nylas.webhooks.list()\n\nprint(\"webhooks:\", webhooks)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nwebhooks = nylas.webhooks.list()\nputs webhooks\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class webhooks {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<Webhook> webhooks = nylas.webhooks().list();\n System.out.println(webhooks.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>){\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val webhooks = nylas.webhooks().list()\n println(webhooks.data)\n}\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchWebhookById() {\n try {\n const webhook = await nylas.webhooks.find({\n webhookId: \"<WEBHOOK_ID>\",\n });\n\n console.log(\"webhook:\", webhook);\n } catch (error) {\n console.error(\"Error fetching webhook:\", error);\n }\n}\n\nfetchWebhookById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nmessage = nylas.webhooks.find(\n \"<WEBHOOK_ID>\",\n)\n\nprint(message)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nwebhook = nylas.webhooks.find(webhook_id: \"<WEBHOOK_ID>\")\nputs webhook\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class webhooks {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Webhook> webhook = nylas.webhooks().find(\"<WEBHOOK_ID>\");\n System.out.println(webhook.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>){\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val webhooks = nylas.webhooks().find(\"<WEBHOOK_ID>\")\n println(webhooks.data)\n}\n"
}
]
},
"put": {
"operationId": "put-webhook-by-id",
"tags": [
"Webhook Notifications"
],
"summary": "Update a webhook destination",
"description": "Update the values in a specific webhook destination.\n\n### Limitations\n\n- You only need to specify fields that need to change when you make a request to this endpoint.\nEmpty fields in the request do not overwrite existing fields.\n- You should limit how many webhook destinations you have for each trigger type. When Nylas retries\na webhook, the retry goes to _all destinations for the specific trigger type_. This can result in\na lot of notifications.\n- Some webhook testing tools rate-limit or block you if your webhook destination endpoint generates\ntoo 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 \\\n --url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \\ \n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"notification_email_addresses\": [\"leyah@example.com\"]\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateWebhook() {\n try {\n const webhook = await nylas.webhooks.update({\n webhookId: \"<WEBHOOK_ID>\",\n requestBody: {\n notificationEmailAddresses: [\"<EMAIL_ADDRESS>\"],\n },\n });\n\n console.log(\"Updated Webhook:\", webhook);\n } catch (error) {\n console.error(\"Error updating webhook:\", error);\n }\n}\n\nupdateWebhook();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nwebhook = nylas.webhooks.update(\n \"<WEBHOOK_ID>\",\n request_body={\n \"notification_email_addresses\": [\"<EMAIL_ADDRESS>\"],\n }\n)\n\nprint(webhook)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n description: 'My updated webhook'\n}\n\nwebhooks = nylas.webhooks.update(webhook_id: \"<WEBHOOK_ID>\", \nrequest_body: request_body)\nputs webhooks\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class webhooks {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateWebhookRequest webhookRequest = new\n UpdateWebhookRequest.Builder().\n description(\"My updated webhook\").\n build();\n\n Response<Webhook> webhook = nylas.webhooks().update(\"<WEBHOOK_ID>\", \n webhookRequest);\n System.out.println(webhook.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.UpdateWebhookRequest\n\nfun main(args: Array<String>){\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val webhookRequest : UpdateWebhookRequest =\n UpdateWebhookRequest.Builder().\n description(\"My updated webhook\").\n build()\n\n val webhooks = nylas.webhooks().update(\"<WEBHOOK_ID>\", \n webhookRequest)\n println(webhooks.data)\n}\n"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/webhooks/<WEBHOOK_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst deleteWebhook = async () => {\n try {\n await nylas.webhooks.destroy({ webhookId: \"<WEBHOOK_ID>\" });\n console.log(\"Webhook deleted successfully.\");\n } catch (error) {\n console.error(\"Error deleting webhook:\", error);\n }\n};\n\ndeleteWebhook();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nrequest = nylas.webhooks.destroy(\n \"<WEBHOOK_ID>\",\n)\n\nprint(request)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nstatus = nylas.webhooks.destroy(webhook_id: \"<WEBHOOK_ID>\")\nputs status\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class webhooks {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n WebhookDeleteResponse deleteResponse = \n nylas.webhooks().destroy(\"<WEBHOOK_ID>\");\n System.out.println(deleteResponse);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotllin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>){\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val webhooks = nylas.webhooks().destroy(\"<WEBHOOK_ID>\")\n println(webhooks.data)\n}\n"
}
]
}
},
"/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.\n\n### Webhook notification header\n\nEvery 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 \\\n --url 'https://api.us.nylas.com/v3/webhooks/rotate-secret/<WEBHOOK_ID>' \\ \n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst rotated = await nylas.webhooks.rotateSecret({\n webhookId: \"<WEBHOOK_ID>\",\n});\n\nconsole.log(\"Rotated webhook secret:\", rotated);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nwebhook = nylas.webhooks.rotate_secret(\n \"<WEBHOOK_ID>\"\n)\n\nprint(webhook)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "# frozen_string_literal: true\n\n# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: '<NYLAS_API_KEY>'\n)\n\nsecret, _ = nylas.webhooks.rotate_secret(webhook_id: \"<WEBHOOK_ID>\")\n\nputs secret\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.List;\n\npublic class read_grants {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n Response<WebhookWithSecret> secret = nylas.webhooks().rotateSecret(\"<WEBHOOK_ID>\");\n \n System.out.println(secret);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.UpdateGrantRequest\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val secret = nylas.webhooks().rotateSecret(\"<WEBHOOK_ID>\")\n \n print(secret)\n}\n"
}
],
"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,\nto the webhook URL you specify.",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/webhooks/mock-payload' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"trigger_type\": \"calendar.created\",\n \"webhook_url\": \"<WEBHOOK_URL>\"\n }'"
}
],
"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\nsends a test webhook payload to the webhook URL you specify, and listens for a success\nacknowledgement.\n\nThe secret used is `mock-webhook-secret`.",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/webhooks/send-test-event' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"trigger_type\": \"calendar.created\",\n \"webhook_url\": \"<WEBHOOK_URL>\"\n }'"
}
],
"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.\n",
"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 \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data-raw '{\n \"description\": \"PubSub Test\",\n \"trigger_types\": [\"message.send_success\"],\n \"encryption_key\": \"\",\n \"topic\": \"projects/<YOUR_PROJECT_ID>/topics/<YOUR_TOPIC_ID>\",\n \"notification_email_addresses\": [\"leyah@example.com\"]\n }'"
}
]
},
"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.\n",
"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 \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub/' \\\n --header 'Accept: application/json' \\\n --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 \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \\\n --header 'Accept: application/json' \\\n --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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data-raw '{\n \"description\": \"PubSub Update Test\",\n \"trigger_types\": [\"message.updated\"],\n \"encryption_key\": \"\",\n \"topic\": \"projects/<YOUR_PROJECT_NAME>/topics/<YOUR_TOPIC_NAME>\",\n \"notification_email_addresses\": [\"leyah@example.com\"]\n }'"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/channels/pubsub/<PUBSUB_ID>' \\\n --header 'Accept: application/json' \\\n --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.\n\nThe `topic` must be a valid Amazon SNS topic ARN (starting with `arn:aws:sns:`).\n",
"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 \\\n --url 'https://api.us.nylas.com/v3/channels/sns' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data-raw '{\n \"description\": \"SNS Test\",\n \"trigger_types\": [\"message.send_success\"],\n \"topic\": \"arn:aws:sns:us-east-1:123456789012:my-topic\",\n \"role_arn\": \"arn:aws:iam::123456789012:role/nylas-sns-role\",\n \"notification_email_addresses\": [\"leyah@example.com\"]\n }'"
}
]
},
"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.\n",
"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 \\\n --url 'https://api.us.nylas.com/v3/channels/sns/' \\\n --header 'Accept: application/json' \\\n --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 \\\n --url 'https://api.us.nylas.com/v3/channels/sns/<SNS_CHANNEL_ID>' \\\n --header 'Accept: application/json' \\\n --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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/channels/sns/<SNS_CHANNEL_ID>' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data-raw '{\n \"description\": \"Updated SNS channel\",\n \"trigger_types\": [\"event.created\", \"event.updated\"],\n \"topic\": \"arn:aws:sns:us-east-1:123456789012:my-updated-topic\",\n \"notification_email_addresses\": [\"sysadmin@example.com\"]\n }'"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/channels/sns/<SNS_CHANNEL_ID>' \\\n --header 'Accept: application/json' \\\n --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.\nThis information is securely encrypted and stored, and isn't visible to users.\n\nYou must include data such as the `client_id` and `client_secret` for the provider\nauth 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-----\n...\n-----END PRIVATE KEY-----\n",
"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.\nThis information is securely encoded and stored, and isn't visible to users.\n\nFor the Microsoft Admin Consent 2.0 flow, this field must contain the `tenant`\n(either yours or the user's). If you don't specify the Azure `client_id` and\n`client_secret` Nylas uses the information from your Nylas application's\nMicrosoft 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 \\\n --url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"name\": \"CONNECTOR\",\n \"credential_type\": \"connector\",\n \"credential_data\": {\n \"client_id\": \"<CLIENT_ID>\", // PROVIDER_CLIENT_ID or NYLAS_CLIENT_ID, depending on credential type.\n \"client_secret\": \"<CLIENT_SECRET>\" // PROVIDER_CLIENT_SECRET or NYLAS_CLIENT_SECRET, depending on credential type.\n }\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas, { CredentialType } from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst credential = await nylas.connectors.credentials.create({\n provider: \"google\",\n requestBody: {\n name: \"Google connector override\",\n credentialType: CredentialType.CONNECTOR,\n credentialData: {\n client_id: \"<CLIENT_ID>\",\n client_secret: \"<CLIENT_SECRET>\",\n },\n },\n});\n\nconsole.log(\"Credential created:\", credential);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\ncredential = nylas.connectors.credentials.create(\n provider=\"google\",\n request_body={\n \"name\": \"Google connector override\",\n \"credential_type\": \"connector\",\n \"credential_data\": {\n \"client_id\": \"<CLIENT_ID>\",\n \"client_secret\": \"<CLIENT_SECRET>\",\n },\n },\n)\n\nprint(\"Created credential:\", credential)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.AuthProvider;\nimport com.nylas.models.Credential;\nimport com.nylas.models.CreateCredentialRequest;\nimport com.nylas.models.CredentialData;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class CreateCredential {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CredentialData.ConnectorOverride credentialData = new CredentialData.ConnectorOverride(\n \"<CLIENT_ID>\", \"<CLIENT_SECRET>\", null);\n\n CreateCredentialRequest requestBody = new CreateCredentialRequest.Connector(\n \"Google connector override\", credentialData);\n\n Response<Credential> credential = nylas.connectors().credentials()\n .create(AuthProvider.GOOGLE, requestBody);\n\n System.out.println(\"Credential created: \" + credential.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AuthProvider\nimport com.nylas.models.CreateCredentialRequest\nimport com.nylas.models.CredentialData\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val credentialData = CredentialData.ConnectorOverride(\n clientId = \"<CLIENT_ID>\",\n clientSecret = \"<CLIENT_SECRET>\")\n\n val requestBody = CreateCredentialRequest.Connector(\n name = \"Google connector override\",\n credentialData = credentialData)\n\n val credential = nylas.connectors().credentials().create(AuthProvider.GOOGLE, requestBody)\n\n println(\"Credential created: ${credential.data}\")\n}\n"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds' \\ \n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst credentials = await nylas.connectors.credentials.list({\n provider: \"google\",\n});\n\nconsole.log(\"Credentials:\", credentials);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\ncredentials = nylas.connectors.credentials.list(\n provider=\"google\",\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(\"Credentials:\", credentials)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.AuthProvider;\nimport com.nylas.models.Credential;\nimport com.nylas.models.ListResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class ListCredentials {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<Credential> credentials = nylas.connectors().credentials().list(AuthProvider.GOOGLE);\n\n System.out.println(\"Credentials: \" + credentials.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AuthProvider\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val credentials = nylas.connectors().credentials().list(AuthProvider.GOOGLE)\n\n println(\"Credentials: ${credentials.data}\")\n}\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds/<CREDENTIAL_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst credential = await nylas.connectors.credentials.find({\n provider: \"google\",\n credentialsId: \"<CREDENTIAL_ID>\",\n});\n\nconsole.log(\"Credential:\", credential);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\ncredential = nylas.connectors.credentials.find(\n provider=\"google\",\n credential_id=\"<CREDENTIAL_ID>\",\n)\n\nprint(\"Credential:\", credential)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.AuthProvider;\nimport com.nylas.models.Credential;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class FindCredential {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Credential> credential = nylas.connectors().credentials()\n .find(AuthProvider.GOOGLE, \"<CREDENTIAL_ID>\");\n\n System.out.println(\"Credential: \" + credential.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AuthProvider\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val credential = nylas.connectors().credentials().find(AuthProvider.GOOGLE, \"<CREDENTIAL_ID>\")\n\n println(\"Credential: ${credential.data}\")\n}\n"
}
]
},
"patch": {
"operationId": "patch_credential_by_id",
"tags": [
"Connector credentials"
],
"summary": "Update a connector credential",
"description": "Updates the specified connector credential.\n\nWhen you make a `PATCH` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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.\nThis information is securely encoded and stored, and is _not_ visible to users.\n\nFor the\n[Google App Permission flow](/docs/v3/auth/bulk-auth-grants/#google-app-permission-via-nylas),\nthis field must contain the `private_key_id`, `private_key`, and `client_email`.\n\nFor the\n[Microsoft App Permission flow](/docs/v3/auth/bulk-auth-grants/#use-a-microsoft-bulk-authentication-grant),\nthis field must contain the Azure `client_id` and `client_secret`.\n\nTo use the credential to override a connector, this field must contain the `client_id`\nand `client_secret`.",
"example": {
"type": "service_account",
"project_id": "marketplace-sa-test",
"private_key_id": "abcd1234defg5678",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
"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 \\\n --url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds/<CREDENTIAL_ID>' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"name\": \"google\",\n \"credential_data\": {\n \"client_id\": \"<PROVIDER_CLIENT_ID>\",\n \"client_secret\": \"<PROVIDER_CLIENT_SECRET>\"\n }\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst updated = await nylas.connectors.credentials.update({\n provider: \"google\",\n credentialsId: \"<CREDENTIAL_ID>\",\n requestBody: {\n name: \"google\",\n credentialData: {\n client_id: \"<PROVIDER_CLIENT_ID>\",\n client_secret: \"<PROVIDER_CLIENT_SECRET>\",\n },\n },\n});\n\nconsole.log(\"Credential updated:\", updated);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\ncredential = nylas.connectors.credentials.update(\n provider=\"google\",\n credential_id=\"<CREDENTIAL_ID>\",\n request_body={\n \"name\": \"Updated connector override\",\n },\n)\n\nprint(\"Updated credential:\", credential)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.AuthProvider;\nimport com.nylas.models.Credential;\nimport com.nylas.models.CredentialData;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\nimport com.nylas.models.UpdateCredentialRequest;\n\npublic class UpdateCredential {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CredentialData.ConnectorOverride credentialData = new CredentialData.ConnectorOverride(\n \"<PROVIDER_CLIENT_ID>\", \"<PROVIDER_CLIENT_SECRET>\", null);\n\n UpdateCredentialRequest requestBody = new UpdateCredentialRequest.Builder()\n .name(\"google\")\n .credentialData(credentialData)\n .build();\n\n Response<Credential> updated = nylas.connectors().credentials()\n .update(AuthProvider.GOOGLE, \"<CREDENTIAL_ID>\", requestBody);\n\n System.out.println(\"Credential updated: \" + updated.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AuthProvider\nimport com.nylas.models.CredentialData\nimport com.nylas.models.UpdateCredentialRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val credentialData = CredentialData.ConnectorOverride(\n clientId = \"<PROVIDER_CLIENT_ID>\",\n clientSecret = \"<PROVIDER_CLIENT_SECRET>\")\n\n val requestBody = UpdateCredentialRequest.Builder()\n .name(\"google\")\n .credentialData(credentialData)\n .build()\n\n val updated = nylas.connectors().credentials()\n .update(AuthProvider.GOOGLE, \"<CREDENTIAL_ID>\", requestBody)\n\n println(\"Credential updated: ${updated.data}\")\n}\n"
}
]
},
"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.\n\nTo 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 \\\n --url 'https://api.us.nylas.com/v3/connectors/<CONNECTOR>/creds/<CREDENTIAL_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst result = await nylas.connectors.credentials.destroy({\n provider: \"google\",\n credentialsId: \"<CREDENTIAL_ID>\",\n});\n\nconsole.log(\"Deleted:\", result);\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.connectors.credentials.destroy(\n provider=\"google\",\n credential_id=\"<CREDENTIAL_ID>\",\n)\n\nprint(\"Credential deleted:\", response)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.AuthProvider;\nimport com.nylas.models.DeleteResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class DeleteCredential {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse result = nylas.connectors().credentials()\n .destroy(AuthProvider.GOOGLE, \"<CREDENTIAL_ID>\");\n\n System.out.println(\"Deleted: \" + result);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.AuthProvider\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val result = nylas.connectors().credentials().destroy(AuthProvider.GOOGLE, \"<CREDENTIAL_ID>\")\n\n println(\"Deleted: $result\")\n}\n"
}
]
}
},
"/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\nstring 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\nnonce, 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\na 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>\n\nRegisters a new email domain for your organization. After creating a domain, you must\n[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\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -H \"X-Nylas-Timestamp: 1742932766\" \\\n -d '{\n \"name\": \"My transactional domain\",\n \"domain_address\": \"mail.example.com\"\n }'"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.handler.service_account import ServiceAccountSigner\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nsigner = ServiceAccountSigner(\n private_key_pem=\"<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>\",\n private_key_id=\"<SERVICE_ACCOUNT_ID>\",\n)\n\ndomain = nylas.domains.create(\n request_body={\n \"name\": \"My transactional domain\",\n \"domain_address\": \"mail.example.com\",\n },\n signer=signer,\n)\n\nprint(domain)\n"
}
],
"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>\n\nReturns 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\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -H \"X-Nylas-Timestamp: 1742932766\""
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.handler.service_account import ServiceAccountSigner\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nsigner = ServiceAccountSigner(\n private_key_pem=\"<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>\",\n private_key_id=\"<SERVICE_ACCOUNT_ID>\",\n)\n\ndomains = nylas.domains.list(signer=signer)\n\nprint(domains)\n"
}
],
"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\nstring 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\nnonce, 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\na 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>\n\nReturns the specified domain.",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl -X GET \"https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -H \"X-Nylas-Timestamp: 1742932766\""
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.handler.service_account import ServiceAccountSigner\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nsigner = ServiceAccountSigner(\n private_key_pem=\"<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>\",\n private_key_id=\"<SERVICE_ACCOUNT_ID>\",\n)\n\ndomain = nylas.domains.find(\n domain_id=\"<DOMAIN_ID>\",\n signer=signer,\n)\n\nprint(domain)\n"
}
],
"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>\n\nUpdates 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>\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -H \"X-Nylas-Timestamp: 1742932766\" \\\n -d '{\n \"name\": \"Updated domain name\"\n }'"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.handler.service_account import ServiceAccountSigner\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nsigner = ServiceAccountSigner(\n private_key_pem=\"<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>\",\n private_key_id=\"<SERVICE_ACCOUNT_ID>\",\n)\n\ndomain = nylas.domains.update(\n domain_id=\"<DOMAIN_ID>\",\n request_body={\n \"name\": \"Updated domain name\",\n },\n signer=signer,\n)\n\nprint(domain)\n"
}
],
"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>\n\nDeletes 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>\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -H \"X-Nylas-Timestamp: 1742932766\""
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.handler.service_account import ServiceAccountSigner\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nsigner = ServiceAccountSigner(\n private_key_pem=\"<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>\",\n private_key_id=\"<SERVICE_ACCOUNT_ID>\",\n)\n\nresponse = nylas.domains.destroy(\n domain_id=\"<DOMAIN_ID>\",\n signer=signer,\n)\n\nprint(response)\n"
}
],
"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\nstring 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\nnonce, 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\na 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>\n\nReturns the DNS record information and verification status for the specified verification type.\nUse this endpoint to retrieve the DNS records you need to add at your DNS provider before\ncalling 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\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -H \"X-Nylas-Timestamp: 1742932766\" \\\n -d '{\n \"type\": \"ownership\"\n }'"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.handler.service_account import ServiceAccountSigner\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nsigner = ServiceAccountSigner(\n private_key_pem=\"<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>\",\n private_key_id=\"<SERVICE_ACCOUNT_ID>\",\n)\n\ninfo = nylas.domains.get_info(\n domain_id=\"<DOMAIN_ID>\",\n request_body={\n \"type\": \"ownership\",\n },\n signer=signer,\n)\n\nprint(info)\n"
}
],
"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\nstring 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\nnonce, 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\na 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>\n\nTriggers a verification check for the specified DNS record type. Before calling this endpoint,\nadd the required DNS records to your domain's DNS configuration. You can get the required records\nby 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\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Nylas-Signature: <BASE64_SIGNATURE>\" \\\n -H \"X-Nylas-Kid: <SERVICE_ACCOUNT_ID>\" \\\n -H \"X-Nylas-Nonce: <NONCE>\" \\\n -H \"X-Nylas-Timestamp: 1742932766\" \\\n -d '{\n \"type\": \"dkim\"\n }'"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.handler.service_account import ServiceAccountSigner\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nsigner = ServiceAccountSigner(\n private_key_pem=\"<SERVICE_ACCOUNT_PRIVATE_KEY_PEM>\",\n private_key_id=\"<SERVICE_ACCOUNT_ID>\",\n)\n\nresult = nylas.domains.verify(\n domain_id=\"<DOMAIN_ID>\",\n request_body={\n \"type\": \"dkim\",\n },\n signer=signer,\n)\n\nprint(result)\n"
}
],
"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\nrules for Nylas Agent Accounts. The `application_id` and `organization_id` are derived from your API key, so you\ndon'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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Standard Agent Account Policy\",\n \"spam_detection\": {\n \"use_list_dnsbl\": true,\n \"use_header_anomaly_detection\": true,\n \"spam_sensitivity\": 1.5\n },\n \"limits\": {\n \"limit_attachment_size_limit\": 26214400,\n \"limit_attachment_count_limit\": 20,\n \"limit_inbox_retention_period\": 365,\n \"limit_spam_retention_period\": 30\n }\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createPolicy() {\n try {\n const policy = await nylas.policies.create({\n requestBody: {\n name: \"Standard Agent Account Policy\",\n rules: [\"<RULE_ID>\"],\n limits: {\n limitAttachmentSizeLimit: 26214400,\n limitAttachmentCountLimit: 20,\n limitInboxRetentionPeriod: 365,\n limitSpamRetentionPeriod: 30,\n },\n spamDetection: {\n useListDnsbl: true,\n useHeaderAnomalyDetection: true,\n spamSensitivity: 1.5,\n },\n },\n });\n\n console.log(\"Policy:\", policy);\n } catch (error) {\n console.error(\"Error creating policy:\", error);\n }\n}\n\ncreatePolicy();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\npolicy = nylas.policies.create(\n request_body={\n \"name\": \"Standard Agent Account Policy\",\n \"spam_detection\": {\n \"use_list_dnsbl\": True,\n \"use_header_anomaly_detection\": True,\n \"spam_sensitivity\": 1.5,\n },\n \"limits\": {\n \"limit_attachment_size_limit\": 26214400,\n \"limit_attachment_count_limit\": 20,\n \"limit_inbox_retention_period\": 365,\n \"limit_spam_retention_period\": 30,\n },\n },\n)\n\nprint(policy)\n"
}
],
"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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listPolicies() {\n try {\n const policies = await nylas.policies.list({\n queryParams: {\n limit: 10,\n },\n });\n\n console.log(\"Policies:\", policies);\n } catch (error) {\n console.error(\"Error listing policies:\", error);\n }\n}\n\nlistPolicies();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\npolicies = nylas.policies.list(\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(policies)\n"
}
],
"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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function findPolicy() {\n try {\n const policy = await nylas.policies.find({\n policyId: \"<POLICY_ID>\",\n });\n\n console.log(\"Policy:\", policy);\n } catch (error) {\n console.error(\"Error finding policy:\", error);\n }\n}\n\nfindPolicy();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\npolicy = nylas.policies.find(\n policy_id=\"<POLICY_ID>\",\n)\n\nprint(policy)\n"
}
],
"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,\nspam 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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"rules\": [\"<RULE_ID_1>\", \"<RULE_ID_2>\"]\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updatePolicy() {\n try {\n const policy = await nylas.policies.update({\n policyId: \"<POLICY_ID>\",\n requestBody: {\n limits: {\n limitInboxRetentionPeriod: 180,\n },\n },\n });\n\n console.log(\"Updated policy:\", policy);\n } catch (error) {\n console.error(\"Error updating policy:\", error);\n }\n}\n\nupdatePolicy();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\npolicy = nylas.policies.update(\n policy_id=\"<POLICY_ID>\",\n request_body={\n \"rules\": [\"<RULE_ID_1>\", \"<RULE_ID_2>\"],\n },\n)\n\nprint(policy)\n"
}
],
"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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deletePolicy() {\n try {\n const result = await nylas.policies.destroy({\n policyId: \"<POLICY_ID>\",\n });\n\n console.log(\"Deleted policy:\", result);\n } catch (error) {\n console.error(\"Error deleting policy:\", error);\n }\n}\n\ndeletePolicy();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.policies.destroy(\n policy_id=\"<POLICY_ID>\",\n)\n\nprint(response)\n"
}
],
"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\nsender or recipient fields, and actions to apply when the conditions match. Inbound rules run on incoming\nmessages; outbound rules run on sends before they're submitted to the email provider. Inbound and outbound\nrules are isolated — inbound rules never run during sends, and outbound rules never run on message receipt.\n\nInbound rules can match `from.address`, `from.domain`, or `from.tld`. Outbound rules can match\n`from.address`, `from.domain`, `from.tld`, `recipient.address`, `recipient.domain`, `recipient.tld`, or\n`outbound.type` (`compose` or `reply`). Link inbound rules to a policy to apply them to specific Agent\nAccounts. Outbound rules are currently evaluated from the sending application's enabled outbound rules.\n\nThe `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\non sends before they're submitted to the email provider. Inbound rules accept only `from.*`\nconditions. 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,\ndomain, or top-level domain. Inbound rules accept only `from.*`. Outbound rules also\naccept `recipient.*` and `outbound.type`. For outbound rules, `recipient.*` matches\nagainst any recipient — To, CC, BCC, and SMTP envelope recipients. `outbound.type`\nclassifies the send as `compose` (new message) or `reply` (replying to an existing\nthread).",
"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`;\n`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\n`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\nfolder's name (or its full path for a nested folder, e.g. `Clients/Acme`), or a system\nfolder 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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Block spam domains\",\n \"priority\": 1,\n \"trigger\": \"inbound\",\n \"match\": {\n \"operator\": \"any\",\n \"conditions\": [\n {\n \"field\": \"from.domain\",\n \"operator\": \"is\",\n \"value\": \"spam-domain.com\"\n }\n ]\n },\n \"actions\": [\n { \"type\": \"block\" }\n ]\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createRule() {\n try {\n const rule = await nylas.rules.create({\n requestBody: {\n name: \"Block spam domains\",\n description: \"Rejects messages from known spam domains.\",\n priority: 1,\n trigger: \"inbound\",\n match: {\n operator: \"any\",\n conditions: [\n {\n field: \"from.domain\",\n operator: \"is\",\n value: \"spam-domain.com\",\n },\n ],\n },\n actions: [{ type: \"block\" }],\n },\n });\n\n console.log(\"Rule:\", rule);\n } catch (error) {\n console.error(\"Error creating rule:\", error);\n }\n}\n\ncreateRule();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nrule = nylas.rules.create(\n request_body={\n \"name\": \"Block spam domains\",\n \"priority\": 1,\n \"trigger\": \"inbound\",\n \"match\": {\n \"operator\": \"any\",\n \"conditions\": [\n {\n \"field\": \"from.domain\",\n \"operator\": \"is\",\n \"value\": \"spam-domain.com\",\n },\n ],\n },\n \"actions\": [\n {\"type\": \"block\"},\n ],\n },\n)\n\nprint(rule)\n"
}
],
"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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listRules() {\n try {\n const rules = await nylas.rules.list({\n queryParams: {\n limit: 10,\n },\n });\n\n console.log(\"Rules:\", rules);\n } catch (error) {\n console.error(\"Error listing rules:\", error);\n }\n}\n\nlistRules();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nrules = nylas.rules.list(\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(rules)\n"
}
],
"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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function findRule() {\n try {\n const rule = await nylas.rules.find({\n ruleId: \"<RULE_ID>\",\n });\n\n console.log(\"Rule:\", rule);\n } catch (error) {\n console.error(\"Error finding rule:\", error);\n }\n}\n\nfindRule();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nrule = nylas.rules.find(\n rule_id=\"<RULE_ID>\",\n)\n\nprint(rule)\n"
}
],
"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\napply 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\nrules 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.\n`recipient.*` fields and `outbound.type` apply only to `outbound` rules.\n`recipient.*` matches any recipient on the send, including To, CC, BCC, and SMTP\nenvelope 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\n`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\nfolder's name (or its full path for a nested folder, e.g. `Clients/Acme`), or a system\nfolder 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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"enabled\": false\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateRule() {\n try {\n const rule = await nylas.rules.update({\n ruleId: \"<RULE_ID>\",\n requestBody: {\n enabled: false,\n priority: 5,\n },\n });\n\n console.log(\"Updated rule:\", rule);\n } catch (error) {\n console.error(\"Error updating rule:\", error);\n }\n}\n\nupdateRule();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nrule = nylas.rules.update(\n rule_id=\"<RULE_ID>\",\n request_body={\n \"enabled\": False,\n },\n)\n\nprint(rule)\n"
}
],
"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\nduring 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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteRule() {\n try {\n const result = await nylas.rules.destroy({\n ruleId: \"<RULE_ID>\",\n });\n\n console.log(\"Deleted rule:\", result);\n } catch (error) {\n console.error(\"Error deleting rule:\", error);\n }\n}\n\ndeleteRule();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.rules.destroy(\n rule_id=\"<RULE_ID>\",\n)\n\nprint(response)\n"
}
],
"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\nwhich rules were evaluated against an inbound message, SMTP envelope, or outbound send, the\nnormalized sender or recipient data that was matched, which rules matched, and which actions were\napplied.\n\nRule evaluations are created automatically as inbound mail is processed and as outbound sends are\nevaluated, and serve as an audit trail for the Rules engine. Records are returned in reverse\nchronological 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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listRuleEvaluations() {\n try {\n const evaluations = await nylas.rules.listEvaluations({\n identifier: \"<NYLAS_GRANT_ID>\",\n queryParams: {\n limit: 10,\n },\n });\n\n console.log(\"Rule evaluations:\", evaluations);\n } catch (error) {\n console.error(\"Error listing rule evaluations:\", error);\n }\n}\n\nlistRuleEvaluations();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nevaluations = nylas.rules.list_evaluations(\n grant_id=\"<NYLAS_GRANT_ID>\",\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(\"Rule evaluations:\", evaluations)\n"
}
],
"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\nvalue 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)\nthat can be referenced by rules using the `in_list` condition operator.\n\nThe 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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Blocked domains\",\n \"description\": \"Domains we have identified as sending unwanted mail.\",\n \"type\": \"domain\"\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createList() {\n try {\n const list = await nylas.lists.create({\n requestBody: {\n name: \"Blocked domains\",\n description: \"Domains we have identified as sending unwanted mail.\",\n type: \"domain\",\n },\n });\n\n console.log(\"List:\", list);\n } catch (error) {\n console.error(\"Error creating list:\", error);\n }\n}\n\ncreateList();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnylas_list = nylas.lists.create(\n request_body={\n \"name\": \"Blocked domains\",\n \"description\": \"Domains we have identified as sending unwanted mail.\",\n \"type\": \"domain\",\n },\n)\n\nprint(nylas_list)\n"
}
],
"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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listAgentLists() {\n try {\n const lists = await nylas.lists.list({\n queryParams: {\n limit: 10,\n },\n });\n\n console.log(\"Lists:\", lists);\n } catch (error) {\n console.error(\"Error listing lists:\", error);\n }\n}\n\nlistAgentLists();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nlists = nylas.lists.list(\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(lists)\n"
}
],
"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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function findList() {\n try {\n const list = await nylas.lists.find({\n listId: \"<LIST_ID>\",\n });\n\n console.log(\"List:\", list);\n } catch (error) {\n console.error(\"Error finding list:\", error);\n }\n}\n\nfindList();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnylas_list = nylas.lists.find(\n list_id=\"<LIST_ID>\",\n)\n\nprint(nylas_list)\n"
}
],
"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\ncreation.",
"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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Blocked domains (updated)\",\n \"description\": \"Updated description.\"\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateList() {\n try {\n const list = await nylas.lists.update({\n listId: \"<LIST_ID>\",\n requestBody: {\n name: \"Updated list name\",\n description: \"Updated description.\",\n },\n });\n\n console.log(\"Updated list:\", list);\n } catch (error) {\n console.error(\"Error updating list:\", error);\n }\n}\n\nupdateList();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnylas_list = nylas.lists.update(\n list_id=\"<LIST_ID>\",\n request_body={\n \"name\": \"Blocked domains (updated)\",\n \"description\": \"Updated description.\",\n },\n)\n\nprint(nylas_list)\n"
}
],
"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\nreference 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>\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteList() {\n try {\n const result = await nylas.lists.destroy({\n listId: \"<LIST_ID>\",\n });\n\n console.log(\"Deleted list:\", result);\n } catch (error) {\n console.error(\"Error deleting list:\", error);\n }\n}\n\ndeleteList();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.lists.destroy(\n list_id=\"<LIST_ID>\",\n)\n\nprint(response)\n"
}
],
"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\n`type` — `domain` lists accept domain names, `tld` lists accept top-level domains, and `address` lists accept full\nemail addresses. Duplicate additions are silently ignored.\n\nThe response returns the updated List object with a refreshed `items_count`. You can submit up to 1000 items per\nrequest, 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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"items\": [\"spam-domain.com\", \"another-bad-domain.net\"]\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function addItems() {\n try {\n const list = await nylas.lists.addItems({\n listId: \"<LIST_ID>\",\n requestBody: {\n items: [\"spam-domain.com\", \"another-bad-domain.net\"],\n },\n });\n\n console.log(\"Updated list:\", list);\n } catch (error) {\n console.error(\"Error adding items:\", error);\n }\n}\n\naddItems();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnylas_list = nylas.lists.add_items(\n list_id=\"<LIST_ID>\",\n request_body={\n \"items\": [\"spam-domain.com\", \"another-bad-domain.net\"],\n },\n)\n\nprint(nylas_list)\n"
}
],
"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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\"\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listItems() {\n try {\n const items = await nylas.lists.listItems({\n listId: \"<LIST_ID>\",\n queryParams: {\n limit: 10,\n },\n });\n\n console.log(\"List items:\", items);\n } catch (error) {\n console.error(\"Error listing items:\", error);\n }\n}\n\nlistItems();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nitems = nylas.lists.list_items(\n list_id=\"<LIST_ID>\",\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(items)\n"
}
],
"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\nreturns 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\" \\\n -H \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"items\": [\"spam-domain.com\"]\n }'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function removeItems() {\n try {\n const list = await nylas.lists.removeItems({\n listId: \"<LIST_ID>\",\n requestBody: {\n items: [\"another-bad-domain.net\"],\n },\n });\n\n console.log(\"Updated list:\", list);\n } catch (error) {\n console.error(\"Error removing items:\", error);\n }\n}\n\nremoveItems();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnylas_list = nylas.lists.remove_items(\n list_id=\"<LIST_ID>\",\n request_body={\n \"items\": [\"spam-domain.com\"],\n },\n)\n\nprint(nylas_list)\n"
}
],
"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\nuse `/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).\n\n<div id=\"admonition-warning\">\n⚠️ <b>Your users receive a large number of messages</b>. If you encounter\n<a href=\"/docs/api/errors/400-response/\"><code>429</code> errors</a> or provider\n<a href=\"/docs/dev-guide/platform/rate-limits/\">rate limits</a> when listing messages, Nylas\nrecommends you set the <code>limit</code> parameter to 20 and add\n<a href=\"#query-parameters\">query parameters</a> to your request to\nlimit 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\n(for example, `leyah@example.com,nyla@example.com`). Nylas returns messages that contain one\nof the specified email addresses in the To, From, CC, or BCC fields. You can specify up to 25\nemail 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\ngateways remove BCC information, Nylas usually returns messages sent from the current grant.\n\nFor Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of\nthis query parameter. This is because of a limitation on the provider. Instead, you can use\nthe `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.\n\nFor Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of\nthis query parameter. This is because of a limitation on the provider. Instead, you can use\nthe `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.\n\n- `standard`: Returns the standard message payload.\n- `include_headers`: Returns messages and their full set of headers.\n- `include_basic_headers`: Returns messages with only the three RFC threading headers\n (`Message-ID`, `In-Reply-To`, `References`) in the `headers` array. Use this option when you\n only need to track message identity and thread relationships — payload size is significantly\n smaller than `include_headers`.\n- `include_tracking_options`: Returns messages and their [tracking settings](/docs/v3/email/message-tracking/).\n- `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\nfrom the current grant, use the `in` query parameter and specify the Sent folder instead.\n\nFor Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of\nthis query parameter. This is because of a limitation on the provider. Instead, you can use\nthe `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.\nRequired 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,\nwhile Nylas Agent Accounts use Nylas full-text search syntax. The query parameters that you can\nuse alongside `search_query_native` depend on the provider:\n\n- **Google**: `in`, `limit`, and `page_token`\n- **Microsoft**: `in`, `limit`, and `page_token`\n- **IMAP/Yahoo/iCloud**: Any parameter\n- **EWS**: Any parameter _except_ `thread_id`\n- **Nylas Agent Accounts**: Any other parameter supported for Agent Accounts by this endpoint\n\nRequired when using `shared_from`.\n\nFor an overview of searching messages and threads with `search_query_native` across providers,\nsee [Searching with Nylas](/docs/dev-guide/best-practices/search/#search-messages-and-threads-using-search_query_native).\nIf you're using a Nylas Agent Account, see\n[Email search for Agent Accounts](/docs/v3/agent-accounts/email-search/) for the complete Nylas\nsearch 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.\n\nEWS 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\nmatches."
},
{
"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.\n\nFor Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of\nthis query parameter. This is because of a limitation on the provider. Instead, you can use\nthe `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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?limit=5\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchRecentEmails() {\n try {\n const messages = await nylas.messages.list({\n identifier: \"<NYLAS_GRANT_ID>\",\n queryParams: {\n limit: 5,\n },\n });\n\n console.log(\"Messages:\", messages);\n } catch (error) {\n console.error(\"Error fetching emails:\", error);\n }\n}\n\nfetchRecentEmails();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nmessages = nylas.messages.list(\n grant_id,\n query_params={\n \"limit\": 5\n }\n)\n\nprint(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;\nimport com.nylas.models.*;\nimport java.text.SimpleDateFormat;\n\npublic class ReadEmail {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n ListResponse<Message> message = nylas.messages().list(\"<NYLAS_GRANT_ID>\");\n\n for(Message email : message.getData()){\n String date = new SimpleDateFormat(\"yyyy-MM-dd HH:mm:ss\").\n format(new java.util.Date((email.getDate() == null ? 1 : 1000L)));\n\n System.out.println(email.getId() + \"[\" + date + \"] | \" + \n email.getSubject() + \" | \" +\n email.getFolders());\n }\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\nimport java.text.SimpleDateFormat\nimport java.util.*\n\nfun dateFormatter(milliseconds: String): String {\n return SimpleDateFormat(\"dd/MM/yyyy HH:mm:ss\").\n format(Date(milliseconds.toLong() * 1000)).\n toString()\n}\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val messages : List<Message> = nylas.messages().list(\"<NYLAS_GRANT_ID>\").data\n\n for(message in messages){\n println(\"[${message.id}] | \" +\n \"${message.subject} | \" +\n \"${message.folders}\")\n }\n}"
}
],
"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\n[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for example,\n`#`)."
}
],
"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.\n\n - `standard`: Returns the standard message payload.\n - `include_headers`: Returns the message and its full set of headers.\n - `include_basic_headers`: Returns the message with only the three RFC threading headers\n (`Message-ID`, `In-Reply-To`, `References`) in the `headers` array. Use this option when you\n only need to track message identity and thread relationships — payload size is significantly\n smaller than `include_headers`.\n - `include_tracking_options`: Returns the message and its [tracking settings](/docs/v3/email/message-tracking/).\n - `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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchMessageById() {\n try {\n const message = await nylas.messages.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n messageId: \"<MESSAGE_ID>\",\n });\n\n console.log(\"message:\", message);\n } catch (error) {\n console.error(\"Error fetching message:\", error);\n }\n}\n\nfetchMessageById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nmessage_id = \"<MESSAGE_ID>\"\n\nmessage = nylas.messages.find(\n grant_id,\n message_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class ReturnMessage {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Message> message = \n nylas.messages().find(\"<NYLAS_GRANT_ID>\", \"<MESSAGE_ID>\");\n System.out.println(message);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "// Import Nylas packages\nimport com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val message = nylas.messages().find( \"<NYLAS_GRANT_ID>\", \"<MESSAGE_ID>\")\n\n println(message)\n}"
}
]
},
"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\nmessage.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"folders\": [\"<FOLDER_ID>\"]\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\nconst identifier = \"<NYLAS_GRANT_ID>\";\nconst folderId = \"<FOLDER_ID>\";\nconst messageId = \"<MESSAGE_ID>\";\n\nconst updateMessageFolder = async () => {\n try {\n const updatedMessage = await nylas.messages.update({\n identifier,\n messageId,\n requestBody: {\n folders: [folderId],\n },\n });\n\n console.log(\"Message updated:\", updatedMessage);\n } catch (error) {\n console.error(\"Error updating message folder:\", error);\n }\n};\n\nupdateMessageFolder();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nfolder_id = \"<FOLDER_ID>\"\nmessage_id = \"<MESSAGE_ID>\"\n\nmessage = nylas.messages.update(\n grant_id,\n message_id,\n request_body={\n \"folders\": [folder_id]\n }\n)\n\nprint(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;\nimport com.nylas.models.*;\nimport java.util.List;\n\npublic class UpdateMessage {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateMessageRequest request = new UpdateMessageRequest.Builder().\n unread(true).\n starred(true).\n build();\n\n Response<Message> message = nylas.messages().\n update(\"<NYLAS_GRANT_ID>\", \"<MESSAGE_ID>\", request);\n\n System.out.println(message);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.UpdateMessageRequest\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val request : UpdateMessageRequest =\n UpdateMessageRequest.Builder().\n unread(true).\n starred(true).\n build()\n\n val message = nylas.messages().update(\n \"<NYLAS_GRANT_ID>\",\n \"<MESSAGE_ID>\", request\n )\n print(message)\n}\n"
}
]
},
"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\nmessage 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteMessage() {\n try {\n const result = await nylas.messages.destroy({\n identifier: \"<NYLAS_GRANT_ID>\",\n messageId: \"<MESSAGE_ID>\",\n });\n\n console.log(\"Result:\", result);\n } catch (error) {\n console.error(\"Error deleting message:\", error);\n }\n}\n\ndeleteMessage();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nmessage_id = \"<MESSAGE_ID>\"\n\nresult = nylas.messages.destroy(\n grant_id,\n message_id,\n)\n\nprint(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\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val message =\n nylas.messages().destroy(\"<NYLAS_GRANT_ID>\",\n \"<MESSAGE_ID>\")\n println(message)\n}\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class ReturnMessage {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse message = nylas.messages().destroy(\"<NYLAS_GRANT_ID>\", \n \"<MESSAGE_ID>\");\n System.out.println(message);\n }\n}\n"
}
],
"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.\n\n**Note**: Nylas removes all extra information, such as `<script>` and `<style>` tags, regardless\nof 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/clean' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"message_id\": [\"<MESSAGE_ID>\"],\n \"ignore_links\": true,\n \"ignore_images\": true,\n \"images_as_markdown\": false,\n \"ignore_tables\": true,\n \"remove_conclusion_phrases\": true,\n \"html_as_markdown\": false\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function cleanMessages() {\n try {\n const messages = await nylas.messages.cleanMessages({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n messageId: [\"<MESSAGE_ID>\"],\n ignoreImages: true,\n ignoreLinks: true,\n ignoreTables: true,\n imagesAsMarkdown: true,\n removeConclusionPhrases: true,\n },\n });\n\n console.log(\"Cleaned messages:\", messages);\n } catch (error) {\n console.error(\"Error cleaning messages:\", error);\n }\n}\n\ncleanMessages();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n api_key = \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n \"message_id\": [\"<MESSAGE_ID>\"],\n \"ignore_images\": True,\n \"ignore_links\": True,\n \"ignore_tables\": True,\n \"images_as_markdown\": True,\n \"remove_conclusion_phrases\": True,\n }\n\nresponse = nylas.messages.clean_messages(\"<NYLAS_GRANT_ID>\",\n request_body=request_body).data\nprint(response[0].body)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n message_id: [\"<MESSAGE_ID>\"],\n ignore_images: true,\n ignore_links: true,\n ignore_tables: true,\n images_as_markdown: true,\n remove_conclusion_phrases: true\n}\n\ncleaned, _request_id = nylas.messages.clean_messages(\n identifier: \"<NYLAS_GRANT_ID>\",\n request_body: request_body\n)\n\ncleaned.each do |message|\n puts message[:conversation]\nend\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.ArrayList;\nimport java.util.Arrays;\nimport java.util.List;\n\npublic class Clean_Message {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n List<String> messagesId = List.of(\"<MESSAGE_ID>\");\n\n CleanMessagesRequest requestBody = \n new CleanMessagesRequest.Builder(messagesId).\n ignoreImages(true).\n ignoreLinks(true).\n ignoreTables(true).\n imagesAsMarkdown(true).\n removeConclusionPhrases(true)\n .build();\n\n ListResponse<CleanMessagesResponse> clean = \n nylas.messages().cleanMessages(\"<NYLAS_GRANT_ID>\", requestBody);\n\n System.out.println(clean.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.CleanMessagesRequest\nimport com.nylas.models.Message\nimport com.nylas.resources.Messages\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val messageId = listOf(\"<MESSAGE_ID>\")\n\n val requestBody = CleanMessagesRequest.\n Builder(messageId).\n ignoreImages(true).\n ignoreLinks(true).\n ignoreTables(true).\n imagesAsMarkdown(true).\n removeConclusionPhrases(true).build()\n\n var result = nylas.messages().cleanMessages(\"<NYLAS_GRANT_ID>\", \n requestBody)\n print(result.data[0].body)\n}\n"
}
]
}
},
"/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\n`/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\nwithout sending duplicate emails. Nylas caches the response (success or error) for 1 hour, scoped\nper grant. A retry with the same key and payload returns the cached response with the\n`Idempotent-Response: true` header set. See\n[Idempotent send requests](/docs/v3/email/idempotent-send/) for the full retry behavior and\nerror 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\nfrom your request. If you want to schedule it to be sent later, set `send_at` to the time you want\nto send the message, in seconds using the Unix timestamp format.\n\nFor more information about scheduling messages, see\n[Schedule messages to send in the future](/docs/v3/email/scheduled-send/).\n\nTo use a custom hostname for link click or message open tracking, provide\n`tracking_options.domain_name`. Nylas validates that the authenticated organization owns an\nactive certificate for the hostname. If you omit the field, Nylas uses its regional tracking\nhostname. Scheduled sends validate an explicit custom hostname when you create the schedule and\nrevalidate it immediately before delivery. If the hostname is no longer eligible, the scheduled\nsend fails without falling back to a Nylas hostname.\n\n(Google and Microsoft Graph only) When scheduling a message, you can set `use_draft` to `true` to\nsave the message in the user's Drafts folder until it's sent.\n\nNylas 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).\n\n### Limitations\n\nMicrosoft 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\nformat as [Get Message](/docs/reference/api/messages/get-messages-id/) responses.\n\n- `standard`: Returns the standard send response (no `headers` array).\n- `include_headers`: Returns the full set of headers on the response.\n- `include_basic_headers`: Returns only the three RFC threading headers (`Message-ID`,\n `In-Reply-To`, `References`). Use this option when you only need to track message identity\n and thread relationships — payload size is significantly smaller than `include_headers`.\n\nSupported on **synchronous** send only. The parameter has no effect when you set the `send_at`\nfield on the request (scheduled send is asynchronous and doesn't return headers).\n\nFor provider support details, see\n[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\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function sendEmail() {\n try {\n const sentMessage = await nylas.messages.send({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n to: [{ name: \"Name\", email: \"<EMAIL>\" }],\n replyTo: [{ name: \"Name\", email: \"<EMAIL>\" }],\n replyToMessageId: \"<MESSAGE_ID>\",\n subject: \"Your Subject Here\",\n body: \"Your email body here.\",\n },\n });\n\n console.log(\"Sent message:\", sentMessage);\n } catch (error) {\n console.error(\"Error sending email:\", error);\n }\n}\n\nsendEmail();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import os\nimport sys\nfrom nylas import Client\nfrom nylas import utils\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nemail = \"<EMAIL>\"\n\nattachment = utils.file_utils.attach_file_request_builder(\"Nylas_Logo.png\")\n\nmessage = nylas.messages.send(\n grant_id,\n request_body={\n \"to\": [{ \"name\": \"Name\", \"email\": email }],\n \"reply_to\": [{ \"name\": \"Name\", \"email\": email }],\n \"reply_to_message_id\": \"<MESSAGE_ID>\",\n \"subject\": \"Your Subject Here\",\n \"body\": \"Your email body here.\",\n \"attachments\": [attachment]\n }\n)\n\nprint(message)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\n# Initialize the Nylas client\nnylas = Nylas::Client.new(\n api_key: '<NYLAS_API_KEY>',\n api_uri: '<NYLAS_API_URI>'\n)\n\ngrant_id = '<NYLAS_GRANT_ID>'\nemail = '<EMAIL>'\n\n# Prepare the attachment\nattachment = Nylas::FileUtils.attach_file_request_builder('Nylas_Logo.png')\n\n# Send the message\nmessage, _request_id = nylas.messages.send(\n identifier: grant_id,\n request_body: {\n to: [{ name: 'Name', email: email }],\n reply_to: [{ name: 'Name', email: email }],\n reply_to_message_id: '<MESSAGE_ID>',\n subject: 'Your Subject Here',\n body: 'Your email body here.',\n attachments: [attachment]\n }\n)\n\nputs message"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.ArrayList;\nimport java.util.List;\nimport com.nylas.util.FileUtils;\n\npublic class SendEmails {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CreateAttachmentRequest attachment = FileUtils.attachFileRequestBuilder(\"src/main/java/Nylas_Logo.png\");\n List<CreateAttachmentRequest> request = new ArrayList<>();\n request.add(attachment);\n\n List<EmailName> emailNames = new ArrayList<>();\n emailNames.add(new EmailName(\"john.doe@example.com\", \n \"John Doe\"));\n\n TrackingOptions options = \n new TrackingOptions(\"hey just testing\", true, true, true);\n\n SendMessageRequest requestBody = \n new SendMessageRequest.Builder(emailNames).\n trackingOptions(options).\n subject(\"Hey Reaching Out with Nylas\").\n body(\"Hey I would like to track this link <a href='https://espn.com'>My Example Link</a>.\").\n attachments(request).\n build();\n\n Response<Message> email = \n nylas.messages().send(\"<NYLAS_GRANT_ID>\", requestBody);\n System.out.println(email.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\nimport com.nylas.util.FileUtils\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val attachment: CreateAttachmentRequest = FileUtils.attachFileRequestBuilder(\"src/main/kotlin/Nylas_Logo.png\")\n\n val options = TrackingOptions(\"hey just testing\", true, true, true)\n\n val emailNames : List<EmailName> = listOf(EmailName(\"john.doe@example.com\", \n \"John Doe\"))\n val requestBody : SendMessageRequest = \n SendMessageRequest.Builder(emailNames).\n subject(\"Hey Reaching Out with Nylas\").\n body(\"Hey I would like to track this link <a href='https://espn.com'>My Example Link</a>\").\n trackingOptions(options).\n attachments(listOf(attachment)).\n build()\n val email = nylas.messages().send(\"<NYLAS_GRANT_ID>\", \n requestBody)\n print(email.data)\n}\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/schedules' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchMessageSchedules() {\n try {\n const identifier = \"<NYLAS_GRANT_ID>\";\n const messageSchedules = await nylas.messages.listScheduledMessages({\n identifier,\n });\n\n console.log(\"Message Schedules:\", messageSchedules);\n } catch (error) {\n console.error(\"Error fetching message schedules:\", error);\n }\n}\n\nfetchMessageSchedules();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nmessages = nylas.messages.list_scheduled_messages(\n grant_id\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class ReturnMessage {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<ScheduledMessage> message = nylas.messages().listScheduledMessages(\"<NYLAS_GRANT_ID>\");\n \n System.out.println(message.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val messages = nylas.messages().listScheduledMessages(\"<NYLAS_GRANT_ID>\").data\n \n print(messages)\n}\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/schedules/<SCHEDULE_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst NylasConfig = {\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\nasync function fetchScheduledMessageById() {\n try {\n const events = await nylas.messages.findScheduledMessage({\n identifier: \"<NYLAS_GRANT_ID>\",\n scheduleId: \"<SCHEDULE_ID>\",\n });\n\n console.log(\"Events:\", events);\n } catch (error) {\n console.error(\"Error fetching calendars:\", error);\n }\n}\n\nfetchScheduledMessageById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nschedule_id = \"<SCHEDULE_ID>\"\n\nevent = nylas.messages.find_scheduled_message(\n grant_id,\n schedule_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class ReturnMessage {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<ScheduledMessage> message = nylas.messages().findScheduledMessage(\n \"<NYLAS_GRANT_ID>\", \n \"<SCHEDULED_MESSAGE_ID>\");\n \n System.out.println(message.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val messages = nylas.messages().findScheduledMessage(\n \"<NYLAS_GRANT_ID>\", \n \"<SCHEDULED_MESSAGE_ID\").data\n\n print(messages)\n}"
}
]
},
"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\nthe message has reached its `send_at` time. If you make a `DELETE` request less than 10 seconds\nbefore 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/schedules/<SCHEDULE_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst NylasConfig = {\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n};\n\nconst nylas = new Nylas(NylasConfig);\n\nasync function deleteMessageSchedule() {\n try {\n const result = await nylas.messages.stopScheduledMessage({\n identifier: \"<NYLAS_GRANT_ID>\",\n scheduleId: \"<SCHEDULE_ID>\",\n });\n\n console.log(\"Result:\", result);\n } catch (error) {\n console.error(\"Error deleting message:\", error);\n }\n}\n\ndeleteMessageSchedule();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "import sys\nfrom nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nschedule_id = \"<SCHEDULE_ID>\"\n\nresult = nylas.messages.stop_scheduled_message(\n grant_id,\n schedule_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class ReturnMessage {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<StopScheduledMessageResponse> message = nylas.messages().stopScheduledMessage(\n \"<NYLAS_GRANT_ID>\",\n \"SCHEDULED_MESSAGE_ID\",\n null);\n \n System.out.println(message.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val messages = nylas.messages().stopScheduledMessage(\n \"<NYLAS_GRANT_ID>\", \n \"SCHEDULED_MESSAGE_ID\").data\n \n print(messages)\n}\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function composeEmail() {\n try {\n const message = await nylas.messages.smartCompose.composeMessage({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n prompt: \"Tell my colleague how we can use Nylas APIs\",\n },\n });\n\n console.log(\"Message created:\", message);\n } catch (error) {\n console.error(\"Error creating message:\", error);\n }\n}\n\ncomposeEmail();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nemail = \"<EMAIL>\"\n\nmessage = nylas.messages.smart_compose.compose_message(\n grant_id,\n request_body={\n \"prompt\": \"Tell my colleague how we can use Nylas APIs\",\n }\n)\n\nprint(message)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n prompt: \"Let's talk about Nylas\"\n}\n\nmessage, _ = nylas.messages.smart_compose.compose_message(\n identifier: \"<NYLAS_GRANT_ID>\",\n request_body: request_body\n)\n\nputs message[:suggestion]\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class SmartCompose {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n ComposeMessageRequest requestBody = new ComposeMessageRequest(\"Let's talk about Nylas\");\n Response<ComposeMessageResponse> message = nylas.messages().smartCompose().composeMessage(\"<NYLAS_GRANT_ID>\", requestBody);\n \n System.out.println(message.getData().getSuggestion());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ComposeMessageRequest\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val requestBody : ComposeMessageRequest = ComposeMessageRequest(\"Let's talk about Nylas\")\n val message = nylas.messages().smartCompose().composeMessage(\"<NYLAS_GRANT_ID>\", requestBody)\n \n print(message.data.suggestion)\n}\n"
}
]
}
},
"/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\na [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function composeEmailReply() {\n try {\n const message = await nylas.messages.smartCompose.composeMessageReply({\n identifier: \"<NYLAS_GRANT_ID>\",\n messageId: \"<MESSAGE_ID>\",\n requestBody: {\n prompt: \"Respond to the email\",\n },\n });\n\n console.log(\"Message created:\", message);\n } catch (error) {\n console.error(\"Error creating message:\", error);\n }\n}\n\ncomposeEmailReply();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nmessage_id = \"<MESSAGE_ID>\"\n\nmessage = nylas.messages.smart_compose.compose_message_reply(\n grant_id,\n message_id,\n request_body={\n \"prompt\": \"Respond to the email\",\n }\n)\n\nprint(message)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n prompt: 'reply'\n}\n\nmessage, _ = nylas.messages.smart_compose.compose_message_reply(\n identifier: \"<NYLAS_GRANT_ID>\",\n message_id: \"<MESSAGE_ID>\",\n request_body: request_body\n)\n\nputs message[:suggestion]\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class SmartCompose {\n public static void main(String[] args) throws\n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ComposeMessageRequest requestBody = new ComposeMessageRequest(\"Reply\");\n\n Response<ComposeMessageResponse> message = \n nylas.messages().smartCompose().composeMessageReply(\"<NYLAS_GRANT_ID>\", \n \"<MESSAGE_ID>\", requestBody);\n System.out.println(message.getData().getSuggestion());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ComposeMessageRequest\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val requestBody : ComposeMessageRequest = \n ComposeMessageRequest(\"Reply\")\n val message = nylas.messages().smartCompose().composeMessageReply(\"<NYLAS_GRANT_ID>\", \n \"<MESSAGE_ID>\", requestBody)\n print(message.data.suggestion)\n\n}\n"
}
]
}
},
"/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\n`tracking_options.domain_name`, which selects the hostname for link click and message open\ntracking.",
"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\nwithout sending duplicate emails. Nylas caches the response (success or error) for 1 hour, scoped\nper Nylas application (not per domain -- a key collides across all verified domains under the same\napplication). A retry with the same key and payload returns the cached response with the\n`Idempotent-Response: true` header set. See\n[Idempotent send requests](/docs/v3/email/idempotent-send/) for the full retry behavior and\nerror 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).\n\nThe route's `domain_name` value is the verified sender domain. To use a different custom hostname\nfor link click or message open tracking, provide `tracking_options.domain_name` in the request\nbody. For example, you can send from `sender.example.com` and track through\n`tracking.example.com`. Nylas validates scheduled custom tracking hostnames when you create the\nschedule and revalidates them immediately before delivery. If an explicit hostname is no longer\neligible, the send fails without falling back to a Nylas hostname.\n\n<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\n[Working with email attachments](/docs/v3/email/attachments/#attachment-schemas-and-size-limits)\nfor more information.",
"example": "YXR0YWNoDQoNCi0tLS0tLS0tLS0gRm9yd2FyZGVkIG1lc3NhZ2UgL="
},
"content_disposition": {
"type": "string",
"description": "(Not supported for Microsoft and EWS) The content disposition of the file. Usually,\nthis 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\nmessage body. To avoid unexpected behavior in threads, make sure to use unique CIDs\nacross messages of a thread.",
"example": "ce9b9547-9eeb-43b2-ac4e-58768bdf04e4"
},
"content_type": {
"type": "string",
"description": "The\n[MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)\nof the file. This is used by the email client to determine how to display the\nattachment.",
"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\nwith 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\ninclude an HTML version of the message. When `false`, Nylas sends the message body as\nHTML.",
"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'\nTransactional Send, you may use the ID that was returned in the Nylas response. For all other\nmessages, this is the [RFC822](https://datatracker.ietf.org/doc/html/rfc822#section-4.6.1)\n`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.\nMust be at least one minute in the future from the time you make your request. You can\nschedule a message to be sent up to 30 days in the future. If the request includes\n`tracking_options.domain_name`, Nylas validates the hostname when it creates the schedule\nand 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\ndefined 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\ntemplate.",
"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\n[message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the\nmessage. Nylas generates a\n[`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications)\nwhen a participant first opens the message.",
"default": false
},
"links": {
"type": "boolean",
"description": "When `true`, enables\n[link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the\nmessage. Nylas generates a\n[`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications)\nwhen 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\nenabled.",
"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\nwith 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\ninclude an HTML version of the message. When `false`, Nylas sends the message body as\nHTML.",
"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'\nTransactional Send, you may use the ID that was returned in the Nylas response. For all other\nmessages, this is the [RFC822](https://datatracker.ietf.org/doc/html/rfc822#section-4.6.1)\n`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.\nMust be at least one minute in the future from the time you make your request. You can\nschedule a message to be sent up to 30 days in the future. If the request includes\n`tracking_options.domain_name`, Nylas validates the hostname when it creates the schedule\nand 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\ndefined 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\ntemplate.",
"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\n[message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the\nmessage. Nylas generates a\n[`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications)\nwhen a participant first opens the message.",
"default": false
},
"links": {
"type": "boolean",
"description": "When `true`, enables\n[link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the\nmessage. Nylas generates a\n[`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications)\nwhen 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\nenabled.",
"maxLength": 2048
},
"domain_name": {
"$ref": "#/components/schemas/tracking_domain_name"
}
}
}
}
}
}
}
}
}
},
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://api.us.nylas.com/v3/domains/<DOMAIN_NAME>/messages/send' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"to\": [{\n \"name\": \"Jane Doe\",\n \"email\": \"jane.doe@example.com\"\n }],\n \"from\": {\n \"name\": \"ACME Support\",\n \"email\": \"support@acme.com\"\n },\n \"subject\": \"Welcome to ACME\",\n \"body\": \"Welcome to ACME! We'\\''re here to help you.\"\n}'"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nmessage = nylas.transactional_send.send(\n domain_name=\"<DOMAIN_NAME>\",\n request_body={\n \"to\": [{\"name\": \"Jane Doe\", \"email\": \"jane.doe@example.com\"}],\n \"from_\": {\"name\": \"ACME Support\", \"email\": \"support@acme.com\"},\n \"subject\": \"Welcome to ACME\",\n \"body\": \"Welcome to ACME! We're here to help you.\",\n },\n)\n\nprint(message)\n"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
}
]
},
"post": {
"summary": "Create a signature",
"operationId": "post-signature",
"description": "Create a signature for a grant. Each grant can have up to 10 signatures.\n\nNylas sanitizes the HTML content on input to prevent malicious content. Images must use\nexternally 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"name\": \"Work Signature\",\n \"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>\"\n }'\n"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
}
]
},
"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\ndoes 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"name\": \"Updated Work Signature\",\n \"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>\"\n }'\n"
}
]
},
"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\nis deleted.",
"security": [
{
"NYLAS_API_KEY": []
},
{
"ACCESS_TOKEN": []
}
],
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request DELETE \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
}
]
}
},
"/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\naddresses (for example, `mail1@example.com,mail2@example.com`). You can specify a maximum of\n25 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\nExchange 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchDrafts() {\n try {\n const identifier = \"<NYLAS_GRANT_ID>\";\n const threads = await nylas.drafts.list({\n identifier,\n });\n\n console.log(\"Recent Drafts:\", threads);\n } catch (error) {\n console.error(\"Error fetching drafts:\", error);\n }\n}\n\nfetchDrafts();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ndrafts = nylas.drafts.list(\n grant_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\nimport java.text.SimpleDateFormat;\n\npublic class ListDraft {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<Draft> drafts = nylas.drafts().list(\"<NYLAS_GRANT_ID>\");\n\n for (Draft draft : drafts.getData()){\n String date = new SimpleDateFormat(\"yyyy-MM-dd HH:mm:ss\").\n format(new java.util.Date((draft.getDate() * 1000L)));\n System.out.printf(\"[ %s] | %s | %s | %s\",\n date, draft.getId(), draft.getSubject(), draft.getFolders());\n }\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\nimport java.text.SimpleDateFormat\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val simpleDateFormat = SimpleDateFormat(\"dd MMMM yyyy, HH:mm:ss\")\n\n val drafts = nylas.drafts().list(\"<NYLAS_GRANT_ID>\")\n\n for(draft in drafts.data){\n println(\"[${simpleDateFormat.format(draft.date * 1000L)}] | \" +\n \"${draft.id} | ${draft.subject} | ${draft.folders}\")\n }\n}\n"
}
]
},
"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.\n\nIf you provide `tracking_options.domain_name`, Nylas validates the custom hostname and stores its\ncanonical value with the draft's link click and message open tracking settings. If you omit the\nfield, 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"subject\": \"With Love, From Nylas\",\n \"to\": [{\n \"email\": \"leyah@example.com\",\n \"name\": \"Leyah Miller\"\n }],\n \"cc\": [{\n \"email\": \"nyla@example.com\",\n \"name\": \"Nyla\"\n }],\n \"bcc\": [{\n \"email\": \"nylas-devrel@example.com\",\n \"name\": \"Nylas DevRel\"\n }],\n \"reply_to\": [{\n \"email\": \"nylas@example.com\",\n \"name\": \"Nylas\"\n }],\n \"body\": \"This email was sent using the Nylas Email API. Visit https://nylas.com for details.\",\n \"tracking_options\": {\n \"opens\": true,\n \"links\": true,\n \"thread_replies\": true,\n \"label\": \"Just testing\"\n }\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\nconst identifier = \"<NYLAS_GRANT_ID>\";\n\nconst createDraft = async () => {\n try {\n const draft = {\n subject: \"Your Subject Here\",\n to: [{ name: \"Recipient Name\", email: \"recipient@example.com\" }],\n body: \"Your email body here.\",\n };\n\n const createdDraft = await nylas.drafts.create({\n identifier,\n requestBody: draft,\n });\n\n console.log(\"Draft created:\", createdDraft);\n } catch (error) {\n console.error(\"Error creating draft:\", error);\n }\n};\n\ncreateDraft();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas import utils\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nemail = \"<EMAIL>\"\n\nattachment = utils.file_utils.attach_file_request_builder(\"Nylas_Logo.png\")\n\ndraft = nylas.drafts.create(\n grant_id,\n request_body={\n \"to\": [{ \"name\": \"Name\", \"email\": email }],\n \"reply_to\": [{ \"name\": \"Name\", \"email\": email }],\n \"subject\": \"Your Subject Here\",\n \"body\": \"Your email body here.\",\n \"attachments\": [attachment]\n }\n)\n\nprint(draft)\n"
},
{
"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;\nimport com.nylas.models.*;\nimport com.nylas.util.FileUtils;\nimport java.util.ArrayList;\nimport java.util.Collections;\nimport java.util.List;\n\npublic class CreateDraft {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CreateAttachmentRequest attachment = FileUtils.attachFileRequestBuilder(\"src/main/java/Nylas_Logo.png\");\n List<CreateAttachmentRequest> request = new ArrayList<>();\n request.add(attachment);\n\n CreateDraftRequest requestBody = new CreateDraftRequest.Builder().\n to(Collections.singletonList(new EmailName(\"swag@example.com\", \"Nylas\"))).\n cc(Collections.singletonList(new EmailName(\"dorothy@example.com\", \"Dorothy Vaughan\"))).\n bcc(Collections.singletonList(new EmailName(\"Lamarr@example.com\", \"Hedy Lamarr\"))).\n subject(\"With Love, from Nylas\").\n body(\"This email was sent using the Nylas email API. Visit https://nylas.com for details.\").\n attachments(request).\n build();\n\n Response<Draft> drafts = nylas.drafts().create(\"<NYLAS_GRANT_ID>\", requestBody);\n\n System.out.println(\"Draft \" + drafts.getData().getSubject() + \n \" was created with ID \" + drafts.getData().getId());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\nimport com.nylas.util.FileUtils\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n \n val attachment: CreateAttachmentRequest = FileUtils.attachFileRequestBuilder(\"src/main/kotlin/Nylas_Logo.png\")\n\n val requestBody = CreateDraftRequest(\n to = listOf(EmailName(\"swag@example.com\", \"Nylas\")),\n cc = listOf(EmailName(\"dorothy@example.com\", \"Dorothy Vaughan\")),\n bcc = listOf(EmailName(\"Lamarr@example.com\", \"Hedy Lamarr\")),\n subject = \"With Love, from Nylas\",\n body = \"This email was sent using the Nylas Email API. Visit https://nylas.com for details.\",\n attachments = listOf(attachment)\n )\n\n val draft = nylas.drafts().create(\"<NYLAS_GRANT_ID>\", requestBody).data\n \n print(\"Draft \" + draft.subject + \" was created with ID: \" + draft.id)\n}\n"
}
]
}
},
"/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\n[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchDraftById() {\n try {\n const events = await nylas.drafts.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n draftId: \"<DRAFT_ID>\",\n });\n\n console.log(\"Events:\", events);\n } catch (error) {\n console.error(\"Error fetching calendars:\", error);\n }\n}\n\nfetchDraftById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\ndraft_id = \"<DRAFT_ID>\"\n\ndraft = nylas.drafts.find(\n grant_id,\n draft_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class ListDraft {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n Response<Draft> draft = nylas.drafts().find(\"<NYLAS_GRANT_ID>\", \"<DRAFT_ID>\");\n\n assert draft.getData().getTo() != null;\n\n System.out.printf(\" %s | %s | %s\",\n draft.getData().getId(),\n draft.getData().getTo().get(0).getEmail(),\n draft.getData().getSubject());\n }\n}"
},
{
"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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[Updating objects](/docs/reference/api/#updating-objects).\n\nFor tracking settings, an explicit `tracking_options.domain_name` replaces the draft's previous\ncustom tracking hostname after validation. If you omit `domain_name` while updating other tracking\noptions, the draft inherits its existing custom hostname. Disabling both `links` and `opens` clears\nthe stored hostname. If you enable either option again without a hostname, Nylas uses its regional\ntracking 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"starred\": true\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateDraft() {\n try {\n const calendar = await nylas.drafts.update({\n identifier: \"<NYLAS_GRANT_ID>\",\n draftId: \"<DRAFT_ID>\",\n requestBody: {\n starred: true,\n },\n });\n\n console.log(\"Updated Draft:\", calendar);\n } catch (error) {\n console.error(\"Error to update draft:\", error);\n }\n}\n\nupdateDraft();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\nfrom nylas.utils.file_utils import attach_file_request_builder\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\nattachment = attach_file_request_builder(\"Nylas_Logo.png\")\n\ndraft = nylas.drafts.update(\n \"<NYLAS_GRANT_ID>\",\n draft_id=\"<DRAFT_ID>\",\n request_body={\n \"subject\": \"Updated Subject\",\n \"attachments\": [attachment]\n }\n)\n\nprint(draft)\n"
},
{
"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;\nimport com.nylas.models.*;\n\npublic class UpdateDraft {\n public static void main(String[] args) throws\n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateDraftRequest requestBody =\n new UpdateDraftRequest.\n Builder().\n starred(true).\n build();\n\n Response<Draft> draft = nylas.drafts().update(\"<NYLAS_GRANT_ID>\",\n \"<DRAFT_ID>\", requestBody);\n System.out.printf(\"%s%s%s%n\",\n draft.getData().getId(),\n draft.getData().getStarred());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\nimport com.nylas.util.FileUtils\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val attachment: CreateAttachmentRequest = FileUtils.attachFileRequestBuilder(\"src/main/kotlin/Nylas_Logo.png\")\n\n val requestBody = UpdateDraftRequest(\n attachments = listOf(attachment)\n )\n\n val draft = nylas.drafts().update(identifier = \"<NYLAS_GRANT_ID>\", draftId = \"<NYLAS_DRAFT_ID>\", requestBody = requestBody)\n\n println(draft)\n}\n"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\nconst identifier = \"<NYLAS_GRANT_ID>\";\nconst draftId = \"<DRAFT_ID>\";\n\nconst deleteDraft = async () => {\n try {\n await nylas.drafts.destroy({ identifier, draftId });\n console.log(`Draft with ID ${draftId} deleted successfully.`);\n } catch (error) {\n console.error(`Error deleting contact with ID ${draftId}:`, error);\n }\n};\n\ndeleteDraft();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n api_key = \"<NYLAS_API_KEY>\"\n)\n\ndrafts = nylas.drafts.destroy(\"<NYLAS_GRANT_ID>\", \"<DRAFT_ID>\")\nprint(drafts)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas' \n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nstatus, _ = nylas.drafts.destroy(identifier: \"<NYLAS_GRANT_ID>\", draft_id: \"<DRAFT_ID>\")\n\nif status\n puts \"Draft successfully deleted\"\nend\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class SendDraft {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse draft = \n nylas.drafts().destroy(\"<NYLAS_GRANT_ID>\", \"<DRAFT_ID>\");\n System.out.println(draft.getRequestId());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val draft = nylas.drafts().destroy(\"<NYLAS_GRANT_ID>\", \"<DRAFT_ID>\")\n print(draft.requestId)\n}\n"
}
]
},
"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\n[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\nsending. Nylas inserts the signature after a line break at the end of the body, including\nafter any quoted text. Only use this if the draft was created without a signature, or if\nyou 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\nconst identifier = \"<NYLAS_GRANT_ID>\";\nconst draftId = \"<DRAFT_ID>\";\n\nconst sendDraft = async () => {\n try {\n const sentMessage = await nylas.drafts.send({ identifier, draftId });\n console.log(\"Draft sent:\", sentMessage);\n } catch (error) {\n console.error(\"Error sending draft:\", error);\n }\n};\n\nsendDraft();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\ndraft_id = \"<DRAFT_ID>\"\n\ndraft = nylas.drafts.send(\n grant_id,\n draft_id\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class SendDraft {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Message> draft = \n nylas.drafts().send(\"<NYLAS_GRANT_ID>\", \"<DRAFT_ID>\");\n System.out.println(draft.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val draft = nylas.drafts().send(\"<NYLAS_GRANT_ID>\", \"<DRAFT_ID>\")\n print(draft.data)\n}\n"
}
]
}
},
"/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\n`/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.\n\nFor Microsoft, IMAP, iCloud, Yahoo, and EWS, threads are ordered reverse chronologically by the latest message received.\n\nFor Google, thread ordering is not guaranteed to be reverse chronological due to a Gmail API limitation.\nHowever, setting the `in` query parameter improves the likelihood of reverse chronological ordering significantly (approximately 40%).\nWhile reverse chronological ordering remains unguaranteed even with the `in` parameter, we recommend using it to increase the chance of this ordering pattern.\n\n<div id=\"admonition-warning\">\n⚠️ <b>Your users might receive a large number of threaded messages</b>. If you encounter\n<a href=\"/docs/api/errors/400-response/\"><code>429</code> errors</a> or provider\n<a href=\"/docs/dev-guide/platform/rate-limits/\">rate limits</a> when listing all threads, Nylas\nrecommends you set the <code>limit</code> parameter to 20 and add\n<a href=\"#query-parameters\">query parameters</a> to your request to\nlimit 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\ncomma-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\nSMTP gateways remove BCC information from sent messages, any messages that Nylas returns are\nlikely sent from the parent account.\n\nFor Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of\nthis query parameter. This is because of a limitation on the provider. Instead, you can use\nthe `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.\n\nFor Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of\nthis query parameter. This is because of a limitation on the provider. Instead, you can use\nthe `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\nto filter for threads that include messages sent from the current grant, use the `in` query\nparameter and specify the Sent folder instead.\n\nFor Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of\nthis query parameter. This is because of a limitation on the provider. Instead, you can use\nthe `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.\nRequired 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 \ntimestamp 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\ntimestamp 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\ntimestamp 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)\nfor 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,\nwhile Nylas Agent Accounts use Nylas full-text search syntax. The query parameters that you can\nuse alongside `search_query_native` depend on the provider:\n\n- **Google**: `in`, `limit`, and `page_token`\n- **Microsoft**: `in`, `limit`, and `page_token`\n- **IMAP/Yahoo/iCloud**: Any parameter\n- **EWS**: Any parameter _except_ `thread_id`\n- **Nylas Agent Accounts**: Any other parameter supported for Agent Accounts by this endpoint\n\nFor an overview of searching messages and threads with `search_query_native` across providers,\nsee [Searching with Nylas](/docs/dev-guide/best-practices/search/#search-messages-and-threads-using-search_query_native).\nIf you're using a Nylas Agent Account, see\n[Email search for Agent Accounts](/docs/v3/agent-accounts/email-search/) for the complete Nylas\nsearch 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\nand returns partial matches."
},
{
"name": "to",
"schema": {
"type": "string"
},
"in": "query",
"description": "Filter for threads that contain messages sent to the specified email address.\n\nFor Microsoft grants, Nylas sometimes doesn't return messages that satisfy the conditions of\nthis query parameter. This is because of a limitation on the provider. Instead, you can use\nthe `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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads?limit=5\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchRecentThreads() {\n try {\n const identifier = \"<NYLAS_GRANT_ID>\";\n const threads = await nylas.threads.list({\n identifier: identifier,\n queryParams: {\n limit: 5,\n },\n });\n\n console.log(\"Recent Threads:\", threads);\n } catch (error) {\n console.error(\"Error fetching threads:\", error);\n }\n}\n\nfetchRecentThreads();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nthreads = nylas.threads.list(\n grant_id,\n query_params={\n \"limit\": 5\n }\n)\n\nprint(threads)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\nquery_params = { limit: 5 }\nthreads, _ = nylas.threads.list(identifier: \"<NYLAS_GRANT_ID>\", query_params: query_params)\n\nthreads.map.with_index { |thread, i|\n puts(\"Thread #{i}\")\n participants = thread[:participants]\n\n participants.each{ |participant|\n puts(\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;\nimport com.nylas.models.*;\nimport com.nylas.models.Thread;\nimport java.util.List;\n\npublic class ReadThreadParameters {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListThreadsQueryParams queryParams = new ListThreadsQueryParams.Builder().limit(5).build();\n ListResponse<Thread> threads = nylas.threads().list(\"<NYLAS_GRANT_ID>\", queryParams);\n int index = 0;\n\n for(Thread thread : threads.getData()){\n System.out.printf(\"%s \", index);\n\n List<EmailName> participants = thread.getParticipants();\n assert participants != null;\n\n for(EmailName participant : participants){\n System.out.printf(\" Subject: %s | Participant: %s | Email: %s%n\",\n thread.getSubject(),\n participant.getName(),\n participant.getEmail());\n }\n \n index++;\n }\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\nimport java.util.*\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val queryParams = ListThreadsQueryParams(limit = 5)\n val threads : List<Thread> = nylas.threads().list(\"<CALENDAR_ID>\", queryParams).data\n\n for(i in threads.indices){\n print(\"$i \")\n\n val participants = threads[i].participants\n\n if (participants != null) {\n for(participant in participants){\n println(\" Subject: ${threads[i].subject} + \" +\n \"Name: ${participant.name} + \" +\n \"Email: ${participant.email}\")\n }\n }\n }\n}"
}
],
"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\n[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads/<THREAD_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchThreadById() {\n try {\n const thread = await nylas.threads.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n threadId: \"<THREAD_ID>\",\n });\n\n console.log(\"Thread:\", thread);\n } catch (error) {\n console.error(\"Error fetching thread:\", error);\n }\n}\n\nfetchThreadById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nthread_id = \"<THREAD_ID>\"\n\nthread = nylas.threads.find(\n grant_id,\n thread_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\nimport com.nylas.models.Thread;\n\npublic class ReturnThread {\n public static void main(String[] args) throws\n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Thread> thread = nylas.threads().find(\"<NYLAS_GRANT_ID>\",\n \"<THREAD_ID>\");\n System.out.println(thread);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val thread = nylas.threads().find(\"<NYLAS_GRANT_ID>\", \"<THREAD_ID>\").data\n \n print(thread)\n}\n"
}
]
},
"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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads/<THREAD_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"unread\": true,\n \"starred\": false,\n \"folders\": [\"<FOLDER_ID>\"]\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateThread() {\n try {\n const calendar = await nylas.threads.update({\n identifier: \"<NYLAS_GRANT_ID>\",\n threadId: \"<THREAD_ID>\",\n requestBody: {\n starred: true,\n },\n });\n\n console.log(\"Updated Thread:\", calendar);\n } catch (error) {\n console.error(\"Error to update thread:\", error);\n }\n}\n\nupdateThread();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nthread = nylas.threads.update(\n grant_id,\n thread_id=\"<THREAD_ID>\",\n request_body={\n \"starred\": True\n }\n)\n\nprint(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\nimport com.nylas.models.UpdateThreadRequest\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val requestBody: UpdateThreadRequest =\n UpdateThreadRequest.\n Builder().\n unread(true).\n starred(true).\n build()\n\n val thread = nylas.threads().update(\"<NYLAS_GRANT_ID>\", \"<THREAD_ID>\", requestBody)\n \n print(\"${thread.data.id} ${thread.data.unread} ${thread.data.starred} \")\n}"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads/<THREAD_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\nconst identifier = \"<NYLAS_GRANT_ID>\";\nconst threadId = \"<THREAD_ID>\";\n\nconst deleteThread = async () => {\n try {\n await nylas.threads.destroy({ identifier, threadId });\n console.log(`Thread with ID ${threadId} deleted successfully.`);\n } catch (error) {\n console.error(`Error deleting thread with ID ${threadId}:`, error);\n }\n};\n\ndeleteThread();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nthread_id = \"<THREAD_ID>\"\n\nrequest = nylas.threads.destroy(\n grant_id,\n thread_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\nimport com.nylas.models.Thread;\n\npublic class ReturnThread {\n public static void main(String[] args) throws\n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse thread = nylas.threads().destroy(\"<NYLAS_GRANT_ID>\",\n \"<THREAD_ID>\");\n System.out.println(thread);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val thread = nylas.threads().destroy(\"<NYLAS_GRANT_ID>\", \"<THREAD_ID>\")\n\n print(thread)\n}"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchFolders() {\n try {\n const folders = await nylas.folders.list({\n identifier: \"<NYLAS_GRANT_ID>\",\n });\n\n console.log(\"folders:\", folders);\n } catch (error) {\n console.error(\"Error fetching folders:\", error);\n }\n}\n\nfetchFolders();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nfolder_id = \"<FOLDER_ID>\"\n\nfolder = nylas.folders.list(\n grant_id\n)\n\nprint(folder)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nfolders, _ = nylas.folders.list(identifier: \"<NYLAS_GRANT_ID>\")\n\nfolders.each { |folder|\n puts \"#{folder[:id]} | #{folder[:name]}\"\n}\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class ReturnFolders {\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<Folder> folders = \n nylas.folders().list(\"<NYLAS_GRANT_ID>\");\n for(Folder folder : folders.getData()){\n System.out.println(folder.getId() + \" | \" + folder.getName());\n }\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val labels = nylas.folders().list(\"<NYLAS_GRANT_ID>\")\n for (label in labels.data){\n println(label.id + \" | \" + label.name)\n }\n}\n"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"text_color\": \"#000000\",\n \"name\": \"new folder\",\n \"background_color\": \"#73AFFF\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\nconst identifier = \"<NYLAS_GRANT_ID>\";\n\nconst createFolder = async () => {\n try {\n const folder = await nylas.folders.create({\n identifier,\n requestBody: {\n name: \"New Folder\",\n },\n });\n\n console.log(\"Folder created:\", folder);\n } catch (error) {\n console.error(\"Error creating folder:\", error);\n }\n};\n\ncreateFolder();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nfolder = nylas.folders.create(\n grant_id,\n request_body={\n \"name\": 'New Folder',\n }\n)\n\nprint(folder)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n name: \"My Custom label\"\n}\n\nfolder = nylas.folders.create(identifier: \"<NYLAS_GRANT_ID>\", \n request_body: request_body)"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class CreateFolder {\n\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CreateFolderRequest request = \n new CreateFolderRequest(\"My Custom folder\", \"\", \"\", \"\");\n\n Response<Folder> label = \n nylas.folders().create(\"<NYLAS_GRANT_ID>\", request);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.CreateFolderRequest\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val request = CreateFolderRequest(\"My Custom folder\")\n val folder = nylas.folders().create(\"<NYLAS_GRANT_ID>\", request).data\n println(folder.name)\n}\n"
}
]
}
},
"/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\na [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchFolderById() {\n try {\n const folder = await nylas.folders.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n folderId: \"<FOLDER_ID>\",\n });\n\n console.log(\"Folder:\", folder);\n } catch (error) {\n console.error(\"Error fetching folder:\", error);\n }\n}\n\nfetchFolderById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nfolder_id = \"<FOLDER_ID>\"\n\nmessage = nylas.folders.find(\n grant_id,\n folder_id,\n)\n\nprint(message)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nfolder, _ = nylas.folders.find(identifier: \"<NYLAS_GRANT_ID>\", folder_id: \"<FOLDER_ID>\")\n\nputs folder"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class GetLabel {\n\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Folder> folder = nylas.folders().find(\"<NYLAS_GRANT_ID>\", \n \"<FOLDER_ID>\");\n System.out.println(folder);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val folder = nylas.folders().find(\"<NYLAS_GRANT_ID>\", \n \"<FOLDER_ID>\")\n print(folder)\n}\n"
}
]
},
"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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Renamed folder\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateFolder() {\n try {\n const folder = await nylas.folders.update({\n identifier: \"<NYLAS_GRANT_ID>\",\n folderId: \"<FOLDER_ID>\",\n requestBody: {\n name: \"Updated Folder Name\",\n textColor: \"#000000\",\n backgroundColor: \"#434343\",\n },\n });\n\n console.log(\"Updated Folder:\", folder);\n } catch (error) {\n console.error(\"Error to update folder:\", error);\n }\n}\n\nupdateFolder();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nfolder = nylas.folders.update(\n grant_id,\n folder_id=\"<FOLDER_ID>\",\n request_body={\n \"name\": \"Updated Folder Name\",\n \"text_color\": \"#000000\",\n }\n)\n\nprint(folder)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n name: \"Renamed folder\"\n}\n\nfolder, _ = nylas.folders.update(identifier: \"<NYLAS_GRANT_ID>\", \n folder_id: \"Label_19\", request_body: request_body)\n\nputs folder"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class UpdateLabel {\n\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateFolderRequest updateRequest = new UpdateFolderRequest.Builder().\n name(\"Renamed \").build();\n\n Response<Folder> folder = nylas.folders().update(\"<NYLAS_GRANT_ID>\", \n \"<FOLDER_ID>\", updateRequest);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.UpdateFolderRequest\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val requestBody = UpdateFolderRequest.Builder().\n name(\"Renamed Folder\").build();\n\n val folder = nylas.folders().update(\"<NYLAS_GRANT_ID>\", \n \"<FOLDER_ID>\", requestBody)\n\n print(folder.data)\n}\n"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\nconst identifier = \"<NYLAS_GRANT_ID>\";\nconst folderId = \"<FOLDER_ID>\";\n\nconst deleteFolder = async () => {\n try {\n await nylas.folders.destroy({ identifier, folderId });\n console.log(`Folder with ID ${folderId} deleted successfully.`);\n } catch (error) {\n console.error(`Error deleting folder with ID ${folderId}:`, error);\n }\n};\n\ndeleteFolder();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nfolder_id = \"<FOLDER_ID>\"\n\nrequest = nylas.folders.destroy(\n grant_id,\n folder_id,\n)\n\nprint(request)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nfolder, _ = nylas.folders.destroy(identifier: \"<NYLAS_GRANT_ID>\", \nfolder_id: \"<FOLDER_ID>\")\n\nputs folder\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class DestroyLabel {\n\n public static void main(String[] args) throws \n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse folder = nylas.folders().destroy(\"<NYLAS_GRANT_ID>\", \n \"<FOLDER_ID>\");\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val folder = nylas.folders().destroy(\"<NYLAS_GRANT_ID>\", \n \"<FOLDER_ID>\")\n\n print(folder)\n}\n"
}
]
}
},
"/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\na [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
},
{
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>?message_id=<MESSAGE_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchAttachmentById() {\n try {\n const attachment = await nylas.attachments.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n attachmentId: \"<ATTACHMENT_ID>\",\n queryParams: {\n messageId: \"<MESSAGE_ID>\",\n },\n });\n\n console.log(\"Attachment:\", attachment);\n } catch (error) {\n console.error(\"Error fetching attachment:\", error);\n }\n}\n\nfetchAttachmentById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nfolder_id = \"<FOLDER_ID>\"\nattachment_id = \"<ATTACHMENT_ID>\"\n\nattachment = nylas.attachments.find(\n grant_id,\n attachment_id,\n query_params= {\n \"message_id\": \"<MESSAGE_ID>\",\n }\n)\n\nprint(attachment)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nquery_params = {\n message_id: \"<MESSAGE_ID>\"\n}\n\nattachment = nylas.attachments.find(identifier: \"<NYLAS_GRANT_ID>\", \nattachment_id: \"<ATTACHMENT_ID>\", query_params: query_params)\n\nputs attachment"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class attachment {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError, NylasOAuthError {\n NylasClient nylas = new NylasClient.Builder(\"NYLAS_API_KEY\").build();\n FindAttachmentQueryParams queryParams = new FindAttachmentQueryParams(\"<MESSAGE_ID>\");\n Attachment attachment = nylas.attachments().find(\"<NYLAS_GRANT_ID>\", \"<ATTACHMENT_ID>\", queryParams).getData();\n\n System.out.println(attachment);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.FindAttachmentQueryParams\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val queryParams = FindAttachmentQueryParams(\"<MESSAGE_ID>\")\n val attachment = nylas.attachments().find(\"<NYLAS_GRANT_ID>\", \"<ATTACHMENT_ID>\", queryParams)\n \n print(attachment)\n}"
}
],
"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\na [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
},
{
"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\nIMAP 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID>' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import fs from \"fs\";\nimport Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function downloadAttachment() {\n try {\n const attachmentBytes = await nylas.attachments.downloadBytes({\n identifier: \"<NYLAS_GRANT_ID>\",\n attachmentId: \"<ATTACHMENT_ID>\",\n queryParams: {\n messageId: \"<MESSAGE_ID>\",\n },\n });\n\n const fileName = \"attachment\";\n await fs.promises.writeFile(fileName, attachmentBytes);\n console.log(`File saved as ${fileName}`);\n } catch (error) {\n console.error(\"Error fetching attachment:\", error);\n }\n}\n\ndownloadAttachment();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nattachment_id = \"<ATTACHMENT_ID>\"\n\nattachment = nylas.attachments.download(\n grant_id,\n attachment_id,\n query_params= {\n \"message_id\": \"<MESSAGE_ID>\",\n }\n)\n\nwith open(\"attachment\", 'wb') as f:\n f.write(attachment.content)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\n\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nquery_params = {\n message_id: \"<MESSAGE_ID>\"\n}\n\nattachment = nylas.attachments.download(identifier: \"<NYLAS_GRANT_ID>\", \n attachment_id: \"<ATTACHMENT_ID>\", query_params: query_params)\n\nFile.open(\"./image.png\", \"wb\") do |file|\n file.write(attachment)\nend"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport okhttp3.ResponseBody;\nimport java.io.FileNotFoundException;\nimport java.io.FileOutputStream;\nimport java.io.IOException;\n\npublic class attachment_download {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasOAuthError, IOException {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n FindAttachmentQueryParams queryParams = new FindAttachmentQueryParams(\"<MESSAGE_ID>\");\n ResponseBody attachment = nylas.attachments().download(\"<NYLAS_GRANT_ID>\", \"<ATTACHMENT_ID>\", queryParams);\n\n try {\n FileOutputStream out = new FileOutputStream(\"src/main/resources/image.png\");\n \n out.write(attachment.bytes());\n out.close();\n } catch (FileNotFoundException e) {\n System.out.println(\"File not found\");\n }\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.FindAttachmentQueryParams\nimport java.io.File\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val queryParams = FindAttachmentQueryParams(\"<MESSAGE_ID>\")\n val attachment = nylas.attachments().download(\"<NYLAS_GRANT_ID>\", \"<ATTACHMENT_ID>\", queryParams)\n \n File(\"src/main/resources/Image.png\").writeBytes(attachment.bytes())\n}"
}
],
"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\nwhere you upload the file bytes directly using `PUT`.\n\nUpload sessions expire **one hour** after creation. Once you upload the file to the returned URL,\ncall the [complete endpoint](/docs/reference/api/attachments/complete-attachment-upload-session/)\nto finalize the upload. After completion, reference the `attachment_id` in a send or draft request.\n\n**Supported providers:** Microsoft (Outlook / Exchange via Graph) only. Grants for Google, IMAP,\nYahoo, iCloud, and EWS are rejected with a `401 Unauthorized` error.\n\n**Required Microsoft scopes** (at least one): `Mail.Send`, `Mail.ReadWrite`, or `Mail.ReadWrite.Shared`.\n\nFor the full flow, prerequisites, and error handling, see\n[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\nuploaded object matches this size at completion. If omitted, the size-match check\nis 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachment-uploads' \\\n --header 'Content-Type: application/json' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \\\n --data-raw '{\n \"filename\": \"document.pdf\",\n \"content_type\": \"application/pdf\",\n \"size\": 1048576\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createUploadSession() {\n try {\n const session = await nylas.attachments.createUploadSession({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n filename: \"quarterly-report.pdf\",\n contentType: \"application/pdf\",\n size: 5242880,\n },\n });\n\n console.log(\"Upload session:\", session);\n } catch (error) {\n console.error(\"Error creating upload session:\", error);\n }\n}\n\ncreateUploadSession();\n"
}
],
"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\nnegative 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,\nor 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.\nNylas verifies that the upload succeeded in storage and, if `size` was declared on session\ncreation, that the uploaded byte count matches the declared size.\n\nAfter completion, reference the attachment in a [send](/docs/reference/api/messages/send-message/)\nor [draft](/docs/reference/api/drafts/put-drafts-id/) request by passing\n`{ \"id\": \"<attachment_id>\" }` in the `attachments` array.\n\n**Retention note:** By default, the uploaded file is deleted from storage when `expires_at`\npasses (one hour after session creation). Plan your send to occur inside this window. The\nattachment metadata row is retained for 60 days for observability.\n\nFor the full upload flow, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachment-uploads/<ATTACHMENT_ID>/complete' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function completeUploadSession() {\n try {\n const result = await nylas.attachments.completeUploadSession({\n identifier: \"<NYLAS_GRANT_ID>\",\n attachmentId: \"<ATTACHMENT_ID>\",\n });\n\n console.log(\"Completed:\", result);\n } catch (error) {\n console.error(\"Error completing upload session:\", error);\n }\n}\n\ncompleteUploadSession();\n"
}
],
"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`\nby 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,\nwhen the uploaded size does not match the `size` declared on session creation, or\nwhen 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchFiveAvailableCalendars() {\n try {\n const calendars = await nylas.calendars.list({\n identifier: \"<NYLAS_GRANT_ID>\",\n queryParams: {\n limit: 5,\n },\n });\n\n console.log(\"Available Calendars:\", calendars);\n } catch (error) {\n console.error(\"Error fetching calendars:\", error);\n }\n}\n\nfetchFiveAvailableCalendars();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\ncalendars = nylas.calendars.list(grant_id)\n\nprint(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\nimport com.nylas.NylasClient\nimport com.nylas.models.*\nimport com.nylas.resources.Calendars\n\nfun main(args: Array<String>) {\n\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n // Build the query without parameters\n val calendarQueryParams: ListCalendersQueryParams = ListCalendersQueryParams()\n // Build the query with parameters\n val returnFiveCalendars: ListCalendersQueryParams = ListCalendersQueryParams(5)\n // Get all calendars\n val calendars: List<Calendar> = nylas.calendars().\n list(\"<NYLAS_GRANT_ID>\",\n calendarQueryParams).data\n \n for(calendar in calendars){\n println(\"Id: \" + calendar.id +\n \" | Name: \" + calendar.name +\n \" | Description: \" + calendar.description +\n \" | Is Read Only?: \" + calendar.readOnly +\n \" | Metadata: \" + calendar.metadata)\n }\n\n // Build the event parameters with metadata\n val calendarsMetadata: ListCalendersQueryParams = ListCalendersQueryParams(\n metadataPair = mapOf(\"key1\" to \"This is my metadata\"))\n val calendarsMeta: List<Calendar> = nylas.calendars().\n list(\"<NYLAS_GRANT_ID>\",\n calendarsMetadata).data\n println()\n println(calendarsMeta)\n}\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "// Import packages\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.List;\nimport java.util.Map;\n\npublic class ReturnCalendars {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n // Initialize the Nylas client\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Build the query without parameters\n ListCalendersQueryParams listCalendersQueryParams = \n new ListCalendersQueryParams();\n // Build the query with parameters\n ListCalendersQueryParams returnFiveCalendars = new ListCalendersQueryParams.\n Builder().limit(5).build();\n\n // Get all calendars\n List<Calendar> calendars = nylas.calendars().\n list(\"<NYLAS_GRANT_ID>\", listCalendersQueryParams).getData();\n\n // Loop the calendars\n for (Calendar calendar : calendars){\n // Print out the response\n System.out.println(\"Id: \" + calendar.getId() +\n \" | Name: \" + calendar.getName() +\n \" | Description: \" + calendar.getDescription() +\n \" | Is Read Only?: \" + calendar.getReadOnly() +\n \" | Metadata: \" + calendar.getMetadata());\n }\n\n // Build the event parameters with metadata\n ListCalendersQueryParams CalendarsMetadata = new ListCalendersQueryParams.\n Builder().\n metadataPair(\n Map.of(\"key1\", \n \"This is my metadata\")\n ).\n build();\n \n // Get all calendars that correspond to the metadata\n List<Calendar> metaCalendars = nylas.calendars().\n list(\"<NYLAS_GRANT_ID>\", CalendarsMetadata).\n getData();\n // Print out the response\n System.out.println();\n System.out.println(metaCalendars);\n }\n}\n"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"My New Calendar\",\n \"description\": \"Description of my new calendar\",\n \"location\": \"Location description\",\n \"timezone\": \"America/Los_Angeles\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createCalendar() {\n try {\n const calendar = await nylas.calendars.create({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n name: \"Nylas DevRel\",\n description: \"Nylas Developer Relations\",\n },\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to create calendar:\", error);\n }\n}\n\ncreateCalendar();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ncalendar = nylas.calendars.create(\n grant_id,\n request_body={\n \"name\": 'Nylas DevRel',\n \"description\": 'Nylas Developer Relations'\n }\n)\n\nprint(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\nimport com.nylas.models.*\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n\n val requestBody = CreateCalendarRequest(\n \"My New Calendar\",\n \"Description of my new calendar\",\n \"Location description\",\n \"America/Toronto\",\n mapOf(\"key1\" to \"This is my metadata\")\n )\n\n val calendar: Response<Calendar> = nylas.calendars().\n create(\"<NYLAS_GRANT_ID>\", requestBody)\n\n print(calendar.data)\n}\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.Map;\n\npublic class CreateCalendar {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CreateCalendarRequest requestBody = new CreateCalendarRequest.Builder(\"My New Calendar\")\n .description(\"Description of my new calendar\")\n .location(\"Location description\")\n .timezone(\"America/Toronto\")\n .metadata(Map.of(\"key1\", \"This is my metadata\"))\n .build();\n\n Response<Calendar> calendar = nylas.calendars().\n create(\"<NYLAS_GRANT_ID>\", requestBody);\n\n System.out.println(calendar.getData());\n }\n}\n"
}
],
"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\nwith a grant. Nylas recommends you URL-encode this field, or you might receive a\n[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for example,\n`#`)."
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchCalendar() {\n try {\n const calendar = await nylas.calendars.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n calendarId: \"<CALENDAR_ID>\",\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error fetching calendars:\", error);\n }\n}\n\nfetchCalendar();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ncalendar = nylas.calendars.find(\n grant_id,\n \"<CALENDAR_ID>\"\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class GetCalendar {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n Response<Calendar> calendar = nylas.calendars().find(\"<NYLAS_GRANT_ID>\", \"<CALENDAR_ID>\");\n\n System.out.println(\"Id: \" + calendar.getData().getId() +\n \" | Name: \" + calendar.getData().getName() +\n \" | Description: \" + calendar.getData().getDescription());\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n val calendar: Response<Calendar> = nylas.calendars().find(\"<NYLAS_GRANT_ID>\", \"<CALENDAR_ID>\")\n\n println(\"Id: \" + calendar.data.id +\n \" | Name: \" + calendar.data.name +\n \" | Description: \" + calendar.data.description)\n}"
}
],
"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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[Updating objects](/docs/reference/api/#updating-objects).",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --compressed --request PUT \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"My New Calendar\",\n \"description\": \"Description of my new calendar\",\n \"location\": \"Location description\",\n \"timezone\": \"America/Los_Angeles\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateCalendar() {\n try {\n const calendar = await nylas.calendars.update({\n identifier: \"<NYLAS_GRANT_ID>\",\n calendarId: \"<CALENDAR_ID>\",\n requestBody: {\n name: \"Nylas DevRel Calendar\",\n description: \"Nylas Developer Relations\",\n },\n });\n\n console.log(\"Updated Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to update calendar:\", error);\n }\n}\n\nupdateCalendar();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ncalendar = nylas.calendars.update(\n grant_id,\n calendar_id=\"<CALENDAR_ID>\",\n request_body={\n \"name\": 'Nylas DevRel Calendar',\n \"description\": 'Nylas Developer Relations'\n }\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class UpdateCalendar {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n \n UpdateCalendarRequest requestBody = new UpdateCalendarRequest.Builder().\n name(\"My New Calendar\").\n description(\"Description of my new calendar\").\n location(\"Location description\").\n timezone(\"America/Los_Angeles\").\n build();\n \n Response<Calendar> calendar = nylas.calendars().update(\n \"<CALENDAR_ID>\",\n \"<CALENDAR_ID>\", \n requestBody);\n\n System.out.println(calendar.getData()); \n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\nimport com.nylas.resources.Calendars\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n\n val requestBody = UpdateCalendarRequest.Builder().\n name(\"\\\"New Test Calendar (changed)\\\"\").\n description(\"\\\"this calendar has been updated!\\\"\").\n location(\"Location description\").\n timezone(\"America/Los_Angeles\").\n build()\n\n val calendar: Response<Calendar> = nylas.calendars().update(\n \"<CALENDAR_ID>\",\n \"<CALENDAR_ID>\",\n requestBody)\n \n print(calendar.data)\n}"
}
],
"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\naccount (`\"is_primary\": true`).",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --compressed --request DELETE \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteCalendar() {\n try {\n const calendar = await nylas.calendars.destroy({\n identifier: \"<NYLAS_GRANT_ID>\",\n calendarId: \"<CALENDAR_ID>\",\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to create calendar:\", error);\n }\n}\n\ndeleteCalendar();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\ncalendar_id = \"<CALENDAR_ID>\"\n\nrequest = nylas.calendars.destroy(\n grant_id,\n calendar_id,\n)\n\nprint(request)"
},
{
"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# Create new calendar\ncalendar, = nylas.calendars.destroy(identifier: \"<NYLAS_GRANT_ID>\",\ncalendar_id: \"<CALENDAR_ID>\")\n\n# Print calendar information\nputs calendar"
},
{
"lang": "java",
"label": "Java SDK",
"source": "// Import packages\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class DeleteCalendar {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Delete the requested calendar\n try {\n nylas.calendars().destroy(\"<NYLAS_GRANT_ID>\", \"<CALENDAR_ID>\", null);\n\n System.out.println(\"Deleted successfully\");\n }\n catch(Exception e) {\n System.out.println(\"There was an error \" + e);\n }\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "// Import Nylas packages\nimport com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>) {\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n try {\n val calendar: DeleteResponse = nylas.calendars().destroy(\"<NYLAS_GRANT_ID>\", \"<CALENDAR_ID>\")\n\n println(\"Deleted successfully\")\n }catch (e: NylasApiError){\n println(\"There was an error $e\")\n }\n}"
}
],
"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\naddresses 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\nminutes.",
"example": 30
},
"end_time": {
"type": "integer",
"description": "The end of the time slot that Nylas checks availability for, in seconds using the Unix\ntimestamp 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)\nand returns only slots when all participants are free. The interval must be a multiple\nof 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\ndefined, 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\nNylas 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\nwithin 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\n`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\n`only_specific_time_availability` set to `true` to restrict availability\nto 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\nslot starts at 9:05a.m. and `round_to` is set to `15`, Nylas rounds it to 9:15a.m. The\nround 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\nthe 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\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst email = \"<EMAIL>\";\n\nasync function getCalendarAvailability() {\n try {\n const calendar = await nylas.calendars.getAvailability({\n requestBody: {\n startTime: 1630435200,\n endTime: 1630521600,\n durationMinutes: 15,\n participants: [{ email }],\n },\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to create calendar:\", error);\n }\n}\n\ngetCalendarAvailability();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nemail = \"<EMAIL>\"\n\navailability = nylas.calendars.get_availability(\n request_body={\n \"start_time\": 1630435200,\n \"end_time\": 1630521600,\n \"duration_minutes\": 15,\n \"participants\": [{\"email\": email}]\n }\n)\n\nprint(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\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\n\nimport java.time.Instant;\nimport java.time.LocalDate;\nimport java.time.ZoneOffset;\nimport java.time.temporal.ChronoUnit;\nimport java.util.ArrayList;\nimport java.util.List;\nimport java.text.SimpleDateFormat;\n\npublic class get_availability {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n \n // Get today's date\n LocalDate today = LocalDate.now();\n // Our day starts at 8:00am\n Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);\n // Get time as a Unix timestamp\n long startTime = sixPmUtc.getEpochSecond();\n // Add 9 hours, so our day ends at 5:00pm\n Instant sixPmUtcPlus = sixPmUtc.plus(9, ChronoUnit.HOURS);\n long endTime = sixPmUtcPlus.getEpochSecond();\n\n List<String> calendars = new ArrayList<>();\n calendars.add(\"<CALENDAR_ID>\");\n\n AvailabilityParticipant participant = new AvailabilityParticipant.Builder(\"<PARTICIPANT_EMAIL>\")\n .calendarIds(calendars)\n .build();\n List<AvailabilityParticipant> participants = new ArrayList<>();\n participants.add(participant);\n\n GetAvailabilityRequest availability = new GetAvailabilityRequest.Builder(\n Math.toIntExact(startTime),\n Math.toIntExact(endTime),\n participants,\n 60).build();\n\n Response<GetAvailabilityResponse> available = nylas.calendars().getAvailability(availability);\n\n assert available.getData().getTimeSlots() != null;\n\n for(TimeSlot times : available.getData().getTimeSlots()){\n String initDate = new SimpleDateFormat(\"HH:mm:ss\").\n format(new java.util.Date((times.getStartTime() * 1000L)));\n String endDate = new SimpleDateFormat(\"HH:mm:ss\").\n format(new java.util.Date((times.getEndTime() * 1000L)));\n \n System.out.println(\"From \" + initDate + \" To: \" + endDate);\n }\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "// Import Nylas packages\nimport com.nylas.NylasClient\nimport com.nylas.models.*\n\n// Import Java Packages\nimport java.text.SimpleDateFormat\nimport java.time.LocalDateTime\nimport java.time.ZoneOffset\n\nfun main(args: Array<String>) {\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n // Get today's day\n var startDate = LocalDateTime.now()\n\n // Set time. As we're using UTC we need to add the hours in difference\n // from our own Timezone\n startDate = startDate.withHour(12);\n startDate = startDate.withMinute(0);\n startDate = startDate.withSecond(0);\n val endDate = startDate.withHour(21);\n\n val calendars : List<String> = listOf(\"<CALENDAR_ID>\")\n val participant = AvailabilityParticipant(\"<NYLAS_GRANT_ID>\", calendars, null)\n val participants : List<AvailabilityParticipant> = listOf(participant)\n\n val request = GetAvailabilityRequest(startDate.toEpochSecond(ZoneOffset.UTC).toInt(),\n endDate.toEpochSecond(ZoneOffset.UTC).toInt(), participants, 60)\n\n val available : Response<GetAvailabilityResponse> = nylas.calendars().\n getAvailability(request)\n\n for(slot in available.data.timeSlots!!){\n println(\"From: \" + SimpleDateFormat(\"HH:mm:ss\").format((slot.startTime * 1000L)) +\n \" to: \" + SimpleDateFormat(\"HH:mm:ss\").format((slot.endTime * 1000L)))\n }\n}"
}
],
"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\nlist of email addresses.\n\n### Keep in mind\n\n- The grant ID included in the request _must_ have access to view the provided email addresses'\nfree/busy data. This is usually configured by the provider.\n- All specified email addresses must use the same provider.\n- This endpoint always returns `200 OK`, even if one of the responses returns an error. Be sure\nto check for any errors in the list of responses.\n- Microsoft's availability calculation is limited to a maximum of 1,000 entries per time slot for\neach email address included in the request.\n- The free/busy response does not include all-day room resource bookings on Google or Microsoft.\n- 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\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst email = \"<EMAIL>\";\n\nasync function getFreeBusyCalendarInfo() {\n try {\n const calendar = await nylas.calendars.getFreeBusy({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n startTime: 1630435200,\n endTime: 1630521600,\n emails: [email],\n },\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to create calendar:\", error);\n }\n}\n\ngetFreeBusyCalendarInfo();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nemail = \"<EMAIL>\"\n\nfree_busy = nylas.calendars.get_free_busy(\n grant_id,\n request_body={\n \"start_time\":1630435200,\n \"end_time\":1630521600,\n \"emails\":[email]\n }\n)\n\nprint(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\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\n\n// Import Java packages\nimport java.text.SimpleDateFormat;\nimport java.time.Instant;\nimport java.time.LocalDate;\nimport java.time.ZoneOffset;\nimport java.time.temporal.ChronoUnit;\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class FreeBusy {\n public static void main(String[] args) throws Exception {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n LocalDate today = LocalDate.now();\n // Our day starts at 8:00am\n Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);\n int startTime = (int) sixPmUtc.getEpochSecond();\n // Add 10 hours, so our day ends at 6:00pm\n Instant sixPmUtcPlus = sixPmUtc.plus(10, ChronoUnit.HOURS);\n int endTime = (int) sixPmUtcPlus.getEpochSecond();\n\n // Add emails to check Free/Busy\n List<String> emails = new ArrayList<>();\n emails.add(\"<EMAIL>\");\n\n GetFreeBusyRequest request = new GetFreeBusyRequest(startTime, endTime, emails);\n\n Response<List<GetFreeBusyResponse>> response = nylas.calendars().\n getFreeBusy(\"<NYLAS_GRANT_ID>\", request);\n\n for(GetFreeBusyResponse freeBusy : response.getData()) {\n if (freeBusy.getObject() == FreeBusyType.FREE_BUSY) {\n GetFreeBusyResponse.FreeBusy freeBusyData = (GetFreeBusyResponse.FreeBusy) freeBusy;\n List<FreeBusyTimeSlot> times = freeBusyData.getTimeSlots();\n \n for(FreeBusyTimeSlot time : times){\n // Format dates in a readable way\n String startDate = new SimpleDateFormat(\"HH:mm:ss\").\n format(new java.util.Date((time.getStartTime() * 1000L)));\n \n String endDate = new SimpleDateFormat(\"HH:mm:ss\").\n format(new java.util.Date((time.getEndTime() * 1000L)));\n \n // Print out the time slots\n System.out.println(\"From: \" + startDate + \" to: \" + endDate);\n }\n } else if (freeBusy.getObject() == FreeBusyType.ERROR) {\n GetFreeBusyResponse.FreeBusyError freeBusyError = (GetFreeBusyResponse.FreeBusyError) freeBusy;\n } else {\n throw new Exception(\"Unknown free busy type\");\n }\n }\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "// Import Nylas packages\nimport com.nylas.NylasClient\nimport com.nylas.models.*\n\n// Import Kotlin/Java Packages\nimport java.lang.Exception\nimport java.time.LocalDateTime\nimport java.time.ZoneOffset\nimport java.util.*\n\nfun main(args: Array<String>) {\n\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n // Get today's day\n var startDate = LocalDateTime.now()\n // Set time. As we're using UTC we need to add the hours in difference\n // from our own Timezone\n startDate = startDate.withHour(13);\n startDate = startDate.withMinute(0);\n startDate = startDate.withSecond(0);\n val endDate = startDate.withHour(23);\n val emails : List<String> = listOf(\"<USER_EMAIL>\")\n\n // Make the request for Free/Busy\n val request : GetFreeBusyRequest = GetFreeBusyRequest(\n startDate.toEpochSecond(ZoneOffset.UTC).toInt(),\n endDate.toEpochSecond(ZoneOffset.UTC).toInt(), emails)\n\n // Call the Free/Busy endpoint\n val response : Response<List<GetFreeBusyResponse>> = nylas.calendars().\n getFreeBusy(\"<NYLAS_GRANT_ID>\", request)\n // Loop the list of Free/Busy objects\n for(freeBusy in response.data){\n if(freeBusy.getObject() == FreeBusyType.FREE_BUSY){\n // Get the free/busy data\n val freeBusyData: GetFreeBusyResponse.FreeBusy = freeBusy as\n GetFreeBusyResponse.FreeBusy\n // Get the busy time slots\n val times : List<FreeBusyTimeSlot> = freeBusyData.timeSlots\n // Loop the busy times\n for(time : FreeBusyTimeSlot in times){\n // Format dates in a readable way\n val startTime = Date(time.startTime.toLong() * 1000)\n val endTime = Date(time.endTime.toLong() * 1000)\n // Print out the time slots\n println(\"From: $startTime to $endTime\")\n }\n }else if(freeBusy.getObject() == FreeBusyType.ERROR){\n val freeBusyData: GetFreeBusyResponse.FreeBusyError = freeBusy as\n GetFreeBusyResponse.FreeBusyError\n }else{\n throw Exception(\"Unknown free busy type\")\n }\n }\n}\n"
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>&start=<TIMESTAMP>&end=<TIMESTAMP>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchAllEventsFromCalendar() {\n try {\n const events = await nylas.events.list({\n identifier: \"<NYLAS_GRANT_ID>\",\n queryParams: {\n calendarId: \"<CALENDAR_ID>\",\n },\n });\n\n console.log(\"Events:\", events);\n } catch (error) {\n console.error(\"Error fetching calendars:\", error);\n }\n}\n\nfetchAllEventsFromCalendar();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nevents = nylas.events.list(\n grant_id,\n query_params={\n \"calendar_id\": \"<CALENDAR_ID>\"\n }\n)\n\nprint(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\nimport com.nylas.models.*\n\nimport java.util.*\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n\n val eventquery: ListEventQueryParams = ListEventQueryParams(calendarId = \"<CALENDAR_ID>\")\n\n // Get a list of events\n val myevents: List<Event> = nylas.events().list(\n \"<NYLAS_GRANT_ID>\", \n queryParams = eventquery).data\n\n // Loop through the events\n for(event in myevents){\n print(\"Id: \" + event.id + \" | \");\n print(\"Title: \" + event.title);\n\n // Get the details of Date and Time of each event.\n when(event.getWhen().getObject().toString()) {\n \"DATE\" -> {\n val datespan = event.getWhen() as When.Date\n\n print(\" | The date of the event is: \" + datespan.date);\n }\n \"DATESPAN\" -> {\n val datespan = event.getWhen() as When.Datespan\n\n print(\" | The date of the event is: \" + datespan.startDate);\n }\n \"TIMESPAN\" -> {\n val timespan = event.getWhen() as When.Timespan\n val startDate = Date(timespan.startTime.toLong() * 1000)\n val endDate = Date(timespan.endTime.toLong() * 1000)\n\n print(\" | The time of the event is from: $startDate to $endDate\");\n }\n }\n\n print(\" | Participants: \");\n\n // Get a list of the event participants\n val participants = event.participants\n\n // Loop through and print their email, name and status\n for(participant in participants) {\n print(\" Email: \" + participant.email + \" Name: \" + participant.name +\n \" Status: \" + participant.status)\n }\n \n println(\"\\n\")\n }\n}"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.When;\n\nimport com.nylas.models.*;\nimport java.text.SimpleDateFormat;\nimport java.util.List;\nimport java.util.Objects;\n\npublic class read_calendar_events {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Build the query parameters to filter our the results\n ListEventQueryParams listEventQueryParams = new ListEventQueryParams.Builder(\"<CALENDAR_ID>\").build();\n\n // Read the events from our main calendar\n List<Event> events = nylas.events().list(\"<NYLAS_GRANT_ID>\", listEventQueryParams).getData();\n\n for (Event event : events) {\n System.out.print(\"Id: \" + event.getId() + \" | \");\n System.out.print(\"Title: \" + event.getTitle());\n\n // Dates are handled differently depending on the event type\n switch (Objects.requireNonNull(event.getWhen().getObject()).getValue()) {\n case \"datespan\" -> {\n When.Datespan date = (When.Datespan) event.getWhen();\n\n System.out.print(\" | The date of the event is from: \" + \n date.getStartDate() + \" to \" + \n date.getEndDate());\n }\n case \"date\" -> {\n When.Date date = (When.Date) event.getWhen();\n \n System.out.print(\" | The date of the event is: \" +date.getDate());\n }\n case \"timespan\" -> {\n When.Timespan timespan = (When.Timespan) event.getWhen();\n\n String initDate = new SimpleDateFormat(\"yyyy-MM-dd HH:mm:ss\").\n format(new java.util.Date((timespan.getStartTime() * 1000L)));\n\n String endDate = new SimpleDateFormat(\"yyyy-MM-dd HH:mm:ss\").\n format(new java.util.Date((timespan.getEndTime() * 1000L)));\n\n System.out.print(\" | The time of the event is from: \" + \n initDate + \" to \" + endDate);\n }\n }\n\n System.out.print(\" | Participants: \");\n\n for(Participant participant : event.getParticipants()){\n System.out.print(\" Email: \" + participant.getEmail() +\n \" Name: \" + participant.getName() +\n \" Status: \" + participant.getStatus());\n }\n\n System.out.println(\"\\n\");\n }\n }\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.\n\n### Microsoft limitations\n\nMicrosoft ignores the `notify_participants` field and always sends email notifications about\nchanges to events.\n\n### iCloud limitations\n\n- iCloud ignores the `notify_participants` field and always sends email notifications about changes\nto events.\n- Email addresses that are registered with iCloud will not receive `notify_participants`\nnotifications containing the event. These events are automatically added to the iCloud calendar.\n- Participants' information might be replaced by their iCloud alias. For example, if the organizer's\nemail address is `example@icloud.com` and their iCloud account was registered with\n`example@gmail.com`, you might encounter cases where `example@icloud.com` is replaced with\n`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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"title\": \"Annual Philosophy Club Meeting\",\n \"busy\": true,\n \"conferencing\": {\n \"provider\": \"Zoom Meeting\",\n \"autocreate\": {\n \"conf_grant_id\": \"<NYLAS_GRANT_ID>\",\n \"conf_settings\": {\n \"settings\": {\n \"join_before_host\": true,\n \"waiting_room\": false,\n \"mute_upon_entry\": false,\n \"auto_recording\": \"none\"\n }\n }\n }\n },\n \"participants\": [\n {\n \"name\": \"Leyah Miller\",\n \"email\": \"leyah@example.com\"\n },\n {\n \"name\": \"Nyla\",\n \"email\": \"nyla@example.com\"\n }\n ],\n \"resources\": [{\n \"name\": \"Conference room\",\n \"email\": \"conference-room@example.com\"\n }],\n \"description\": \"Come ready to talk philosophy!\",\n \"when\": {\n \"start_time\": 1674604800,\n \"end_time\": 1722382420,\n \"start_timezone\": \"America/New_York\",\n \"end_timezone\": \"America/New_York\"\n },\n \"location\": \"New York Public Library, Cave room\",\n \"recurrence\": [\n \"RRULE:FREQ=WEEKLY;BYDAY=MO\",\n \"EXDATE:20211011T000000Z\"\n ],\n}'"
},
{
"lang": "bash",
"label": "cURL (manual conferencing)",
"source": "curl --compressed --request POST \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"title\": \"Annual Philosophy Club Meeting\",\n \"busy\": true,\n \"conferencing\": {\n \"provider\": \"Google Meet\",\n \"details\": {\n \"url\": \"https://meet.google.com/***-****-***\",\n \"pin\": \"xyz\",\n \"phone\": [\"+1 234 555 6789\"]\n }\n },\n \"participants\": [\n {\n \"name\": \"Leyah Miller\",\n \"email\": \"leyah@example.com\"\n },\n {\n \"name\": \"Nyla\",\n \"email\": \"nyla@example.com\"\n }\n ],\n \"description\": \"Come ready to talk philosophy!\",\n \"when\": {\n \"start_time\": 1674604800,\n \"end_time\": 1722382420,\n \"start_timezone\": \"America/New_York\",\n \"end_timezone\": \"America/New_York\"\n },\n \"location\": \"New York Public Library, Cave room\",\n \"recurrence\": [\n \"RRULE:FREQ=WEEKLY;BYDAY=MO\",\n \"EXDATE:20211011T000000Z\"\n ],\n}'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nconst now = Math.floor(Date.now() / 1000); // Time in Unix timestamp format (in seconds)\n\nasync function createAnEvent() {\n try {\n const event = await nylas.events.create({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n title: \"Build With Nylas\",\n when: {\n startTime: now,\n endTime: now + 3600,\n },\n },\n queryParams: {\n calendarId: \"<CALENDAR_ID>\",\n },\n });\n\n console.log(\"Event:\", event);\n } catch (error) {\n console.error(\"Error creating event:\", error);\n }\n}\n\ncreateAnEvent();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\nevents = nylas.events.create(\n grant_id,\n request_body={\n \"title\": 'Build With Nylas',\n \"when\": {\n \"start_time\": 1609372800,\n \"end_time\": 1609376400\n },\n },\n query_params={\n \"calendar_id\": \"<CALENDAR_ID>\"\n }\n)\n\nprint(events)"
},
{
"lang": "ruby",
"label": "Ruby SDK",
"source": "require 'nylas'\nrequire 'date'\n\nnylas = Nylas::Client.new(api_key: \"<NYLAS_API_KEY>\")\n\nquery_params = {\n calendar_id: \"<CALENDAR_ID>\"\n}\n\ntoday = Date.today\nstart_time = Time.local(today.year, today.month, today.day, 13, 0, 0).to_i\nend_time = Time.local(today.year, today.month, today.day, 13, 30, 0).to_i\n\nrequest_body = {\n when: {\n start_time: start_time,\n end_time: end_time\n },\n title: \"Let's learn some Nylas Ruby SDK!\",\n location: \"Nylas' Headquarters\",\n description: \"Using the Nylas API with the Ruby SDK is easy.\",\n participants: [{\n name: \"Blag\",\n email: \"atejada@gmail.com\",\n status: 'noreply'\n }]\n}\n\nevent, _request_id = nylas.events.create(\n identifier: \"<NYLAS_GRANT_ID>\",\n query_params: query_params,\n request_body: request_body\n)\n\nputs event\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nimport java.time.LocalDateTime\nimport java.time.ZoneOffset\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n var startDate = LocalDateTime.now()\n\n // Set the time. Because we're using UTC, we need to add the difference in hours from our own timezone.\n startDate = startDate.withHour(13);\n startDate = startDate.withMinute(0);\n startDate = startDate.withSecond(0);\n val endDate = startDate.withMinute(30);\n\n // Convert the dates from Unix timestamp format to integer.\n val iStartDate: Int = startDate.toEpochSecond(ZoneOffset.UTC).toInt()\n val iEndDate: Int = endDate.toEpochSecond(ZoneOffset.UTC).toInt()\n\n // Create the timespan for the event.\n val eventWhenObj: CreateEventRequest.When = CreateEventRequest.When.\n Timespan(iStartDate, iEndDate);\n\n // Define the title, location, and description of the event.\n val title: String = \"Let's learn about the Nylas Kotlin/Java SDK!\"\n val location: String = \"Blag's Den!\"\n val description: String = \"Using the Nylas API with the Kotlin/Java SDK is easy.\"\n\n // Create the list of participants.\n val participants: List<CreateEventRequest.Participant> = listOf(CreateEventRequest.\n Participant(\"<PARTICIPANT_EMAIL>\", ParticipantStatus.NOREPLY, \"<PARTICIPANT_NAME>\"))\n\n // Create the event request. This adds date/time, title, location, description, and participants.\n val eventRequest: CreateEventRequest = CreateEventRequest(eventWhenObj, title, location, description, participants)\n\n // Set the event parameters.\n val eventQueryParams: CreateEventQueryParams = CreateEventQueryParams(\"<CALENDAR_ID>\")\n\n val event: Response<Event> = nylas.events().create(\"<NYLAS_GRANT_ID>\",\n eventRequest, eventQueryParams)\n}"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\nimport java.time.Instant;\nimport java.time.LocalDate;\nimport java.time.ZoneOffset;\nimport java.time.temporal.ChronoUnit;\nimport java.util.*;\n\npublic class create_calendar_events {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Get today's date\n LocalDate today = LocalDate.now();\n\n // Set time. Because we're using UTC we need to add the hours in difference from our own timezone.\n Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);\n\n // Set the date and time for the event. We add 30 minutes to the starting time.\n Instant sixPmUtcPlus = sixPmUtc.plus(30, ChronoUnit.MINUTES);\n\n // Get the Date and Time as a Unix timestamp\n long startTime = sixPmUtc.getEpochSecond();\n long endTime = sixPmUtcPlus.getEpochSecond();\n\n // Define title, location, and description of the event\n String title = \"Let's learn some about the Nylas Java SDK!\";\n String location = \"Nylas Headquarters\";\n String description = \"Using the Nylas API with the Java SDK is easy.\";\n\n // Create the timespan for the event\n CreateEventRequest.When.Timespan timespan = new CreateEventRequest.\n When.Timespan.\n Builder(Math.toIntExact(startTime), Math.toIntExact(endTime)).\n build();\n\n // Create the list of participants.\n List<CreateEventRequest.Participant> participants_list = new ArrayList<>();\n\n participants_list.add(new CreateEventRequest.\n Participant(\"johndoe@example.com\", ParticipantStatus.NOREPLY,\n \"John Doe\", \"\", \"\"));\n\n // Build the event details.\n CreateEventRequest createEventRequest = new CreateEventRequest.Builder(timespan)\n .participants(participants_list)\n .title(title)\n .location(location)\n .description(description)\n .build();\n\n // Build the event parameters. In this case, the Calendar ID.\n CreateEventQueryParams createEventQueryParams = new CreateEventQueryParams.Builder(\"<CALENDAR_ID>\").build();\n\n // Create the event itself\n Event event = nylas.events().create(\n \"<NYLAS_GRANT_ID>\",\n createEventRequest,\n createEventQueryParams).getData();\n }\n}"
}
],
"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\nspecified calendar within a given time frame. This is useful when you want to import, store, and\nsynchronize events from the time frame to your application (for example, to enrich events with\ncustom data or integrate events into your own calendaring solution).\n\nIf you want to retrieve a list of all events from a calendar, use the\n[Get all Events endpoint](/docs/reference/api/events/get-all-events/) instead.\n\n### Limitations\n\n- Nylas might return multiple instances of a single recurring event if the results are paginated.\n- The number of events Nylas returns might be lower than `max_results`, even if others match your\nquery parameters.\n- Events are not guaranteed to be sorted by their start time.\n- Nylas does not support [metadata](/docs/reference/api/#metadata) for this endpoint.\n- 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/import?calendar_id=<CALENDAR_ID>&start=<TIMESTAMP>&end=<TIMESTAMP>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function importEvents() {\n try {\n const events = await nylas.events.listImportEvents({\n identifier: \"<NYLAS_GRANT_ID>\",\n queryParams: {\n calendarId: \"primary\",\n start: 1748908800,\n end: 1748995200,\n },\n });\n\n console.log(\"Imported events:\", events);\n } catch (error) {\n console.error(\"Error importing events:\", error);\n }\n}\n\nimportEvents();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nevents = nylas.events.list_import_events(\n identifier=\"<NYLAS_GRANT_ID>\",\n query_params={\n \"calendar_id\": \"<CALENDAR_ID>\",\n \"start\": 1763119800,\n \"end\": 1765711800,\n },\n)\n\nprint(\"Imported events:\", events)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Event;\nimport com.nylas.models.ListImportEventQueryParams;\nimport com.nylas.models.ListResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class ImportEvents {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListImportEventQueryParams queryParams = new ListImportEventQueryParams.Builder(\"primary\")\n .start(1748908800)\n .end(1748995200)\n .build();\n\n ListResponse<Event> events = nylas.events().listImportEvents(\"<NYLAS_GRANT_ID>\", queryParams);\n\n System.out.println(\"Imported events: \" + events.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ListImportEventQueryParams\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val queryParams = ListImportEventQueryParams.Builder(\"primary\")\n .start(1748908800)\n .end(1748995200)\n .build()\n\n val events = nylas.events().listImportEvents(\"<NYLAS_GRANT_ID>\", queryParams)\n\n println(\"Imported events: ${events.data}\")\n}\n"
}
]
}
},
"/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\n`/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\n[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchEventById() {\n try {\n const events = await nylas.events.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n eventId: \"<EVENT_ID>\",\n queryParams: {\n calendarId: \"<CALENDAR_ID>\",\n },\n });\n\n console.log(\"Events:\", events);\n } catch (error) {\n console.error(\"Error fetching calendars:\", error);\n }\n}\n\nfetchEventById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nevent_id = \"<EVENT_ID>\"\ncalendar_id = \"<CALENDAR_ID>\"\n\nevent = nylas.events.find(\n grant_id,\n event_id,\n query_params={\n \"calendar_id\": calendar_id\n }\n)\n\nprint(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\nimport com.nylas.NylasClient;\nimport com.nylas.models.When;\nimport com.nylas.models.*;\n\npublic class ReadEvent {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n FindEventQueryParams queryParams = new FindEventQueryParams(\"<CALENDAR_ID>\");\n Response<Event> event = nylas.events().find(\"<NYLAS_GRANT_ID>\", \"<EVENT_ID>\", queryParams);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "// Import Nylas packages\nimport com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>){\n val nylas: NylasClient = NylasClient(\n apiKey = \"<NYLAS_API_KEY>\"\n )\n\n val queryParams = FindEventQueryParams(\"<CALENDAR_ID>\")\n val event : Response<Event> = nylas.events().find(\"<NYLAS_GRANT_ID>\", \"<EVENT_ID>\", queryParams)\n}"
}
]
},
"put": {
"summary": "Update an event",
"tags": [
"Events"
],
"operationId": "put-events-id",
"description": "Updates the specified event, conference, or metadata.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[Updating objects](/docs/reference/api/#updating-objects).\n\n### Limitations\n\nNylas handles updating and deleting events similarly to other endpoints, with the following\nrestrictions:\n\n- You can't update events where `read_only` is `true`.\n- 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"title\": \"Birthday Party\",\n \"busy\": true,\n \"participants\": [{\n \"name\": \"Leyah Miller\",\n \"email\": \"leyah@example.com\",\n \"comment\": \"Might be late.\"\n }],\n \"resources\": [{\n \"name\": \"Conference room\",\n \"email\": \"conference-room@example.com\"\n }],\n \"description\": \"Come ready to skate\",\n \"when\": {\n \"start_time\": 1406887200,\n \"end_time\": 1417435200,\n \"start_timezone\": \"America/New_York\",\n \"end_timezone\": \"America/New_York\"\n },\n \"location\": \"Roller Rink\",\n \"recurrence\": [\n \"RRULE:FREQ=WEEKLY;BYDAY=MO\",\n \"EXDATE:20211011T000000Z\"\n ],\n \"conferencing\": {\n \"provider\": \"Zoom Meeting\",\n \"autocreate\": {\n \"conf_grant_id\": \"<NYLAS_GRANT_ID>\",\n \"conf_settings\": {\n \"settings\": {\n \"join_before_host\": true,\n \"waiting_room\": false,\n \"mute_upon_entry\": false,\n \"auto_recording\": \"none\"\n }\n }\n }\n },\n \"reminder_minutes\": \"[20]\",\n \"reminder_method\": \"popup\"\n}'"
},
{
"lang": "bash",
"label": "cURL (manual conferencing)",
"source": "curl --compressed --request PUT \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"conferencing\": {\n \"provider\": \"Google Meet\",\n \"details\": {\n \"url\": \"https://meet.google.com/***-****-***\",\n \"pin\": \"xyz\",\n \"phone\": [\"+1 234 555 6789\"]\n }\n }\n}'\n"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function addParticipantToAndEvent() {\n try {\n const event = await nylas.events.update({\n identifier: \"<NYLAS_GRANT_ID>\",\n eventId: \"<EVENT_ID>\",\n requestBody: {\n participants: [\n {\n name: \"Nylas DevRel\",\n email: \"devrel-@-nylas.com\",\n },\n ],\n },\n queryParams: {\n calendarId: \"<CALENDAR_ID>\",\n },\n });\n } catch (error) {\n console.error(\"Error adding participant to event:\", error);\n }\n}\n\naddParticipantToAndEvent();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nevent_id = \"<EVENT_ID>\"\n\nevent = nylas.events.update(\n grant_id,\n event_id,\n request_body={\n \"participants\": [{\n \"name\": \"Nylas DevRel\",\n \"email\": \"devrel-@-nylas.com\"\n }]\n },\n query_params={\n \"calendar_id\": \"<CALENDAR_ID>\"\n }\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class update_calendar_events {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n UpdateEventQueryParams params = new UpdateEventQueryParams(\"<CALENDAR_ID>\", Boolean.FALSE);\n UpdateEventRequest requestBody = new UpdateEventRequest.Builder().location(\"Nylas' Theatre'\").build();\n\n Response<Event> event = nylas.events().update(\n \"<NYLAS_GRANT_ID>\",\n \"<EVENT_ID>\",\n requestBody,\n params);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n val queryParams = UpdateEventQueryParams(\"<CALENDAR_ID>\", false)\n\n val requestBody : UpdateEventRequest = UpdateEventRequest.Builder().\n location(\"Nylas' Theatre\").\n build()\n\n val response : Response<Event> = nylas.events().update(\n \"<NYLAS_GRANT_ID>\",\n \"<EVENT_ID>\",\n requestBody,\n queryParams)\n}"
}
]
},
"delete": {
"summary": "Delete an event",
"tags": [
"Events"
],
"operationId": "delete-events-id",
"description": "Delete the specified event.\n\nGoogle sends deleted events to the \"Trash\" folder, and you can read them for a period of time using\nthe `show_cancelled` query parameter.\n\nMicrosoft 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteEvent() {\n try {\n const event = await nylas.events.destroy({\n identifier: \"<NYLAS_GRANT_ID>\",\n eventId: \"<EVENT_ID>\",\n queryParams: {\n calendarId: \"<CALENDAR_ID>\",\n },\n });\n\n console.log(\"Event deleted:\", event);\n } catch (error) {\n console.error(\"Error to delete event:\", error);\n }\n}\n\ndeleteEvent();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\nevent_id = \"<EVENT_ID>\"\n\nevent = nylas.events.destroy(\n grant_id,\n event_id,\n query_params={\n \"calendar_id\": \"<CALENDAR_ID>\"\n }\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class delete_calendar_events {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n DestroyEventQueryParams queryParams = new DestroyEventQueryParams(\"<CALENDAR_ID>\", Boolean.FALSE);\n\n DeleteResponse event = nylas.events().destroy(\n \"<NYLAS_GRANT_ID>\",\n \"<EVENT_ID>\",\n queryParams);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n val queryParams = DestroyEventQueryParams(\"<CALENDAR_ID>\", false)\n\n val event = nylas.events().destroy(\n \"<NYLAS_GRANT_ID>\",\n \"<EVENT_ID>\", \n queryParams)\n}"
}
]
}
},
"/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\n[`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
}
],
"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\ncan't directly update events as a participant.\n\nFor most events on EWS, if you decline the event by sending a \"no\" RSVP response, it's removed from\nyour calendar. If an EWS administrator disabled the option to remove declined events from calendars,\nthe event remains on the calendar with the \"no\" RSVP status.\n\nDue to a provider limitation, Microsoft Graph might not update the event status properly.\n\nGoogle allows the meeting organizer to reply \"yes\", \"maybe\", and \"no\" to event invitations. However,\nother providers do not allow meeting organizers to reply to their own event.\n\nNylas sends calendar RSVPs to the event organizer as email updates.\nThis can duplicate the RSVP email sent by the calendar provider.\nIf you want to stop Nylas from sending the RSVP email, \nyou can set the `skip_nylas_email` field to `true` in the query parameters.\n\nIf your application does not implement the\n[scopes that allow you to send messages](/docs/dev-guide/scopes/#email-api-scopes), Nylas updates\nthe RSVP for the event and returns a `200` with an error message. Event participants on the same provider\nwill 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>/send-rsvp?calendar_id=<CALENDAR_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"status\": \"yes\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function sendEventRSVP() {\n try {\n const response = await nylas.events.sendRsvp({\n identifier: \"<NYLAS_GRANT_ID>\",\n eventId: \"<EVENT_ID>\",\n requestBody: {\n status: \"yes\",\n },\n queryParams: {\n calendarId: \"<CALENDAR_ID>\",\n },\n });\n\n console.log(\"Event RSVP:\", response);\n } catch (error) {\n console.error(\"Error sending RSVP:\", error);\n }\n}\n\nsendEventRSVP();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\nresponse = nylas.events.send_rsvp(\n identifier=\"<NYLAS_GRANT_ID>\",\n event_id=\"<EVENT_ID>\",\n request_body={\"status\": \"yes\"},\n query_params={\"calendar_id\": \"<CALENDAR_ID>\"},\n)\n\nprint(response)\n"
},
{
"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;\nimport com.nylas.models.*;\n\npublic class rsvp {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n SendRsvpRequest requestBody = new SendRsvpRequest(RsvpStatus.YES);\n SendRsvpQueryParams queryParams = new SendRsvpQueryParams(\"<CALENDAR_ID>\");\n\n DeleteResponse rsvp = nylas.events().sendRsvp(\n \"<NYLAS_GRANT_ID>\",\n \"<EVENT_ID>\", \n requestBody,\n queryParams);\n \n System.out.println(rsvp);\n }\n}"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.RsvpStatus\nimport com.nylas.models.SendRsvpQueryParams\nimport com.nylas.models.SendRsvpRequest\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n val requestBody : SendRsvpRequest = SendRsvpRequest(RsvpStatus.YES)\n val queryParams : SendRsvpQueryParams = SendRsvpQueryParams(\"<CALENDAR_ID>\")\n\n val rsvp = nylas.events().sendRsvp(\n \"<NYLAS_GRANT_ID>\",\n \"<EVENT_ID>\", \n requestBody,\n queryParams)\n\n print(rsvp)\n}"
}
]
}
},
"/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\n`/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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/resources' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"birthday\": \"1960-12-31\",\n \"company_name\": \"Nylas\",\n \"emails\": [\n {\n \"email\": \"leyah.miller@example.com\",\n \"type\": \"work\"\n },\n {\n \"email\": \"leyah@example.com\",\n \"type\": \"home\"\n }\n ],\n \"given_name\": \"Leyah\",\n \"groups\": [\n {\n \"id\": \"starred\"\n },\n {\n \"id\": \"friends\"\n }\n ],\n \"im_addresses\": [\n {\n \"type\": \"jabber\",\n \"im_address\": \"leyah_jabber\"\n },\n {\n \"type\": \"msn\",\n \"im_address\": \"leyah_msn\"\n }\n ],\n \"job_title\": \"Software Engineer\",\n \"manager_name\": \"Bill\",\n \"middle_name\": \"Allison\",\n \"nickname\": \"Allie\",\n \"notes\": \"Loves Ramen\",\n \"office_location\": \"123 Main Street\",\n \"phone_numbers\": [\n {\n \"number\": \"+1-555-555-5555\",\n \"type\": \"work\"\n },\n {\n \"number\": \"+1-555-555-5556\",\n \"type\": \"home\"\n }\n ],\n \"physical_addresses\": [\n {\n \"type\": \"work\",\n \"street_address\": \"123 Main Street\",\n \"postal_code\": \"94107\",\n \"state\": \"CA\",\n \"country\": \"USA\",\n \"city\": \"San Francisco\"\n },\n {\n \"type\": \"home\",\n \"street_address\": \"456 Main Street\",\n \"postal_code\": \"94107\",\n \"state\": \"CA\",\n \"country\": \"USA\",\n \"city\": \"San Francisco\"\n }\n ],\n \"source\": \"address_book\",\n \"surname\": \"Miller\",\n \"web_pages\": [\n {\n \"type\": \"work\",\n \"url\": \"<WEBPAGE_URL>\"\n },\n {\n \"type\": \"home\",\n \"url\": \"<WEBPAGE_URL>\"\n }\n ]\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createContact() {\n try {\n const contact = await nylas.contacts.create({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n givenName: \"My\",\n middleName: \"Nylas\",\n surname: \"Friend\",\n notes: \"Make sure to keep in touch!\",\n emails: [{ type: \"work\", email: \"swag@example.com\" }],\n phoneNumbers: [{ type: \"work\", number: \"(555) 555-5555\" }],\n webPages: [{ type: \"other\", url: \"nylas.com\" }],\n },\n });\n\n console.log(\"Contact:\", JSON.stringify(contact));\n } catch (error) {\n console.error(\"Error to create contact:\", error);\n }\n}\n\ncreateContact();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ncontact = nylas.contacts.create(\n grant_id,\n request_body={\n \"middle_name\": \"Nylas\",\n \"surname\": \"Friend\",\n \"notes\": \"Make sure to keep in touch!\",\n \"emails\": [{\"type\": \"work\", \"email\": \"swag@example.com\"}],\n \"phone_numbers\": [{\"type\": \"work\", \"number\": \"(555) 555-5555\"}],\n \"web_pages\": [{\"type\": \"other\", \"url\": \"nylas.com\"}]\n }\n)\n\nprint(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;\nimport com.nylas.models.*;\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class CreateAContact {\n public static void main(String[] args) throws\n NylasSdkTimeoutError, NylasApiError {\n\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n List<ContactEmail> contactEmails = new ArrayList<>();\n contactEmails.add(new ContactEmail(\"swag@nylas.com\", \"work\"));\n\n List<WebPage> contactWebpages = new ArrayList<>();\n contactWebpages.add(new WebPage(\"https://www.nylas.com\", \"work\"));\n\n CreateContactRequest requestBody = new CreateContactRequest.Builder().\n emails(contactEmails).\n companyName(\"Nylas\").\n givenName(\"Nylas' Swag\").\n notes(\"This is good swag\").\n webPages(contactWebpages).\n build();\n\n Response<Contact> contact = nylas.contacts().create(\"<NYLAS_GRANT_ID>\", requestBody);\n\n System.out.println(contact);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ContactEmail\nimport com.nylas.models.CreateContactRequest\nimport com.nylas.models.WebPage\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n val emails : List<ContactEmail> = listOf(ContactEmail(\"swag@nylas.com\", \"work\"))\n val webpage : List<WebPage> = listOf(WebPage(\"https://www.nylas.com\", \"work\"))\n\n val contactRequest = CreateContactRequest.Builder().\n emails(emails).\n companyName(\"Nylas\").\n givenName(\"Nylas' Swag\").\n notes(\"This is good swag\").\n webPages(webpage).\n build()\n\n val contact = nylas.contacts().create(\"<NYLAS_GRANT_ID>\", contactRequest)\n\n print(contact.data)\n}\n"
}
]
},
"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\ncontacts from messages. If you want to filter for multiple sources, pass a comma-separated list\n(for example, `source=address_book,inbox`).\n\nEWS 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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchContacts() {\n try {\n const identifier = \"<NYLAS_GRANT_ID>\";\n const contacts = await nylas.contacts.list({\n identifier,\n queryParams: {},\n });\n\n console.log(\"Recent Contacts:\", contacts);\n } catch (error) {\n console.error(\"Error fetching drafts:\", error);\n }\n}\n\nfetchContacts();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ncontacts = nylas.contacts.list(\n grant_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class ReadAllContacts {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n ListResponse<Contact> contacts = nylas.contacts().list(\"<NYLAS_GRANT_ID>\");\n\n for(Contact contact : contacts.getData()) {\n System.out.println(contact);\n System.out.println(\"\\n\");\n }\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n val contacts = nylas.contacts().list(\"<NYLAS_GRANT_ID>\")\n\n for(contact in contacts.data){\n println(contact)\n }\n}\n"
}
]
}
},
"/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\na [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for\nexample, `#`)."
}
],
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchContactById() {\n try {\n const contact = await nylas.contacts.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n contactId: \"<CONTACT_ID>\",\n queryParams: {},\n });\n\n console.log(\"contact:\", contact);\n } catch (error) {\n console.error(\"Error fetching contact:\", error);\n }\n}\n\nfetchContactById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\ncontact_id = \"<CONTACT_ID>\"\n\ncontact = nylas.contacts.find(\n grant_id,\n contact_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class ReturnAContact {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n Response<Contact> contact = nylas.contacts().find(\"<NYLAS_GRANT_ID>\", \"<CONTACT_ID>\");\n\n System.out.println(contact);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n var contact = nylas.contacts().find(\"<NYLAS_GRANT_ID>\", \"<CONTACT_ID>\")\n\n print(contact)\n}\n"
}
]
},
"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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"birthday\": \"1960-12-31\",\n \"company_name\": \"Nylas\",\n \"emails\": [\n {\n \"email\": \"leyah.miller@example.com\",\n \"type\": \"work\"\n },\n {\n \"email\": \"leyah@example.com\",\n \"type\": \"home\"\n }\n ],\n \"given_name\": \"Leyah\",\n \"groups\": [\n {\n \"id\": \"starred\"\n },\n {\n \"id\": \"all\"\n }\n ],\n \"im_addresses\": [\n {\n \"type\": \"jabber\",\n \"im_address\": \"leyah_jabber\"\n },\n {\n \"type\": \"msn\",\n \"im_address\": \"leyah_msn\"\n }\n ],\n \"job_title\": \"Software Engineer\",\n \"manager_name\": \"Bill\",\n \"middle_name\": \"Allison\",\n \"nickname\": \"Allie\",\n \"notes\": \"Loves Ramen\",\n \"office_location\": \"123 Main Street\",\n \"phone_numbers\": [\n {\n \"number\": \"+1-555-555-5555\",\n \"type\": \"work\"\n },\n {\n \"number\": \"+1-555-555-5556\",\n \"type\": \"home\"\n }\n ],\n \"physical_addresses\": [\n {\n \"type\": \"work\",\n \"street_address\": \"123 Main Street\",\n \"postal_code\": \"94107\",\n \"state\": \"CA\",\n \"country\": \"USA\",\n \"city\": \"San Francisco\"\n },\n {\n \"type\": \"home\",\n \"street_address\": \"456 Main Street\",\n \"postal_code\": \"94107\",\n \"state\": \"CA\",\n \"country\": \"USA\",\n \"city\": \"San Francisco\"\n }\n ],\n \"source\": \"address_book\",\n \"surname\": \"Miller\",\n \"web_pages\": [\n {\n \"type\": \"work\",\n \"url\": \"<WEBPAGE_URL>\"\n },\n {\n \"type\": \"home\",\n \"url\": \"<WEBPAGE_URL>\"\n }\n ]\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateContact() {\n try {\n const contact = await nylas.contacts.update({\n identifier: \"<NYLAS_GRANT_ID>\",\n contactId: \"<CONTACT_ID>\",\n requestBody: {\n givenName: \"Nyla\",\n },\n });\n\n console.log(\"Contact:\", JSON.stringify(contact));\n } catch (error) {\n console.error(\"Error to create contact:\", error);\n }\n}\n\nupdateContact();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\ncontact_id = \"<CONTACT_ID>\"\n\ncontact = nylas.contacts.update(\n grant_id,\n contact_id,\n request_body={\n \"given_name\": \"Nyla\",\n }\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class UpdateContact {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateContactRequest requestBody = new UpdateContactRequest.\n Builder().\n notes(\"This is *the best* swag\").\n build();\n\n Response<Contact> contact = nylas.contacts().update(\"<NYLAS_GRANT_ID>\", \"<CONTACT_ID>\", requestBody);\n\n System.out.println(contact);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n\n val updateRequest = UpdateContactRequest.Builder().\n notes(\"This is *the best* swag\").\n build()\n\n val contact = nylas.contacts().update(\"<NYLAS_GRANT_ID>\", \"<CONTACT_ID>\", updateRequest)\n\n print(contact.data)\n}\n"
}
]
},
"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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\nconst identifier = \"<NYLAS_GRANT_ID>\";\nconst contactId = \"<CONTACT_ID>\";\n\nconst deleteContact = async () => {\n try {\n await nylas.contacts.destroy({ identifier, contactId });\n console.log(`Contact with ID ${contactId} deleted successfully.`);\n } catch (error) {\n console.error(`Error deleting contact with ID ${contactId}:`, error);\n }\n};\n\ndeleteContact();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\ncontact_id = \"<CONTACT_ID>\"\n\nrequest = nylas.contacts.destroy(\n grant_id,\n contact_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class DeleteAContact {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n DeleteResponse contact = nylas.contacts().destroy(\"<NYLAS_GRANT_ID>\", \"<CONTACT_ID>\");\n\n System.out.println(contact);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n var contact = nylas.contacts().destroy(\"<NYLAS_GRANT_ID>\", \"<CONTACT_ID>\")\n\n print(contact)\n}"
}
]
}
},
"/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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts/groups' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listContactGroups() {\n try {\n const groups = await nylas.contacts.groups({\n identifier: \"<NYLAS_GRANT_ID>\",\n });\n\n console.log(\"Contact groups:\", groups);\n } catch (error) {\n console.error(\"Error listing contact groups:\", error);\n }\n}\n\nlistContactGroups();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\"\n)\n\ngrant_id = \"<NYLAS_GRANT_ID>\"\n\ncontact_groups = nylas.contacts.list_groups(\n grant_id,\n)\n\nprint(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;\nimport com.nylas.models.*;\n\npublic class ReadContactGroups {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n ListResponse<ContactGroup> groups = nylas.contacts().listGroups(\"<NYLAS_GRANT_ID>\");\n \n System.out.println(groups);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main(args: Array<String>) {\n\n val nylas: NylasClient = NylasClient(apiKey = \"<NYLAS_API_KEY>\")\n var groups = nylas.contacts().listGroups(\"<NYLAS_GRANT_ID>\")\n\n print(groups)\n}"
}
]
}
},
"/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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listNotetakers() {\n try {\n const notetakers = await nylas.notetakers.list({\n identifier: \"<NYLAS_GRANT_ID>\",\n queryParams: {\n limit: 50,\n },\n });\n\n console.log(\"Notetakers:\", notetakers);\n } catch (error) {\n console.error(\"Error listing notetakers:\", error);\n }\n}\n\nlistNotetakers();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnotetakers = nylas.notetakers.list(\n identifier=\"<NYLAS_GRANT_ID>\",\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(\"Notetakers:\", notetakers)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.ListNotetakersQueryParams;\nimport com.nylas.models.ListResponse;\nimport com.nylas.models.Notetaker;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class ListNotetakers {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListNotetakersQueryParams queryParams = new ListNotetakersQueryParams.Builder()\n .limit(50)\n .build();\n\n ListResponse<Notetaker> notetakers = nylas.notetakers().list(queryParams, \"<NYLAS_GRANT_ID>\");\n\n System.out.println(\"Notetakers: \" + notetakers.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ListNotetakersQueryParams\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val queryParams = ListNotetakersQueryParams.Builder()\n .limit(50)\n .build()\n\n val notetakers = nylas.notetakers().list(queryParams, \"<NYLAS_GRANT_ID>\")\n\n println(\"Notetakers: ${notetakers.data}\")\n}\n"
}
],
"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.\n\n<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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"join_time\": 1732657774,\n \"meeting_link\": \"https://meet.google.com/xyz-abcd-ijk\",\n \"meeting_settings\": {\n \"action_items\": true,\n \"action_items_settings\": {\n \"custom_instructions\": \"Only return the 5 most important action items.\"\n },\n \"audio_recording\": true,\n \"leave_after_silence_seconds\": 360,\n \"summary\": true,\n \"summary_settings\": {\n \"custom_instructions\": \"Return this summary in the MEDPIC sales methodology.\"\n },\n \"transcription\": true,\n \"transcription_settings\": {\n \"expected_languages\": [\"en\", \"es\"],\n \"fallback_language\": \"en\"\n },\n \"video_recording\": true\n },\n \"name\": \"Nylas Notetaker\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function inviteNotetaker() {\n try {\n const notetaker = await nylas.notetakers.create({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n meetingLink: \"https://meet.google.com/abc-defg-hij\",\n name: \"Nylas Notetaker\",\n meetingSettings: {\n videoRecording: true,\n audioRecording: true,\n transcription: true,\n },\n },\n });\n\n console.log(\"Notetaker:\", notetaker);\n } catch (error) {\n console.error(\"Error inviting notetaker:\", error);\n }\n}\n\ninviteNotetaker();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnotetaker = nylas.notetakers.invite(\n request_body={\n \"meeting_link\": \"https://meet.google.com/abc-defg-hij\",\n \"name\": \"Nylas Notetaker\",\n \"meeting_settings\": {\n \"video_recording\": True,\n \"audio_recording\": True,\n \"transcription\": True,\n },\n },\n identifier=\"<NYLAS_GRANT_ID>\",\n)\n\nprint(\"Invited notetaker:\", notetaker)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.CreateNotetakerRequest;\nimport com.nylas.models.Notetaker;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class InviteNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CreateNotetakerRequest.MeetingSettings meetingSettings =\n new CreateNotetakerRequest.MeetingSettings.Builder()\n .videoRecording(true)\n .audioRecording(true)\n .transcription(true)\n .build();\n\n CreateNotetakerRequest requestBody = new CreateNotetakerRequest.Builder(\n \"https://meet.google.com/abc-defg-hij\")\n .name(\"Nylas Notetaker\")\n .meetingSettings(meetingSettings)\n .build();\n\n Response<Notetaker> notetaker = nylas.notetakers().create(requestBody, \"<NYLAS_GRANT_ID>\");\n\n System.out.println(\"Notetaker: \" + notetaker.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.CreateNotetakerRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val meetingSettings = CreateNotetakerRequest.MeetingSettings.Builder()\n .videoRecording(true)\n .audioRecording(true)\n .transcription(true)\n .build()\n\n val requestBody = CreateNotetakerRequest.Builder(\"https://meet.google.com/abc-defg-hij\")\n .name(\"Nylas Notetaker\")\n .meetingSettings(meetingSettings)\n .build()\n\n val notetaker = nylas.notetakers().create(requestBody, \"<NYLAS_GRANT_ID>\")\n\n println(\"Notetaker: ${notetaker.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function findNotetaker() {\n try {\n const notetaker = await nylas.notetakers.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n notetakerId: \"<NOTETAKER_ID>\",\n });\n\n console.log(\"Notetaker:\", notetaker);\n } catch (error) {\n console.error(\"Error finding notetaker:\", error);\n }\n}\n\nfindNotetaker();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnotetaker = nylas.notetakers.find(\n notetaker_id=\"<NOTETAKER_ID>\",\n identifier=\"<NYLAS_GRANT_ID>\",\n)\n\nprint(\"Notetaker:\", notetaker)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Notetaker;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class FindNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Notetaker> notetaker = nylas.notetakers().find(\"<NOTETAKER_ID>\", \"<NYLAS_GRANT_ID>\");\n\n System.out.println(\"Notetaker: \" + notetaker.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val notetaker = nylas.notetakers().find(\"<NOTETAKER_ID>\", \"<NYLAS_GRANT_ID>\")\n\n println(\"Notetaker: ${notetaker.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"join_time\": 1732657774,\n \"meeting_settings\": {\n \"action_items\": true,\n \"action_items_settings\": {\n \"custom_instructions\": \"Only return the 5 most important action items.\"\n },\n \"audio_recording\": true,\n \"summary\": true,\n \"summary_settings\": {\n \"custom_instructions\": \"Return this summary in the MEDPIC sales methodology.\"\n },\n \"transcription\": true,\n \"transcription_settings\": {\n \"expected_languages\": [\"en\", \"es\"],\n \"fallback_language\": \"en\"\n },\n \"video_recording\": true\n },\n \"name\": \"Nylas Notetaker\",\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateNotetaker() {\n try {\n const notetaker = await nylas.notetakers.update({\n identifier: \"<NYLAS_GRANT_ID>\",\n notetakerId: \"<NOTETAKER_ID>\",\n requestBody: {\n name: \"Updated Notetaker name\",\n meetingSettings: {\n transcription: false,\n },\n },\n });\n\n console.log(\"Updated notetaker:\", notetaker);\n } catch (error) {\n console.error(\"Error updating notetaker:\", error);\n }\n}\n\nupdateNotetaker();\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Notetaker;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\nimport com.nylas.models.UpdateNotetakerRequest;\n\npublic class UpdateNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateNotetakerRequest.MeetingSettings meetingSettings =\n new UpdateNotetakerRequest.MeetingSettings.Builder()\n .transcription(false)\n .build();\n\n UpdateNotetakerRequest requestBody = new UpdateNotetakerRequest.Builder()\n .name(\"Updated Notetaker name\")\n .meetingSettings(meetingSettings)\n .build();\n\n Response<Notetaker> notetaker = nylas.notetakers().update(\n \"<NOTETAKER_ID>\", requestBody, \"<NYLAS_GRANT_ID>\");\n\n System.out.println(\"Updated notetaker: \" + notetaker.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.UpdateNotetakerRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val meetingSettings = UpdateNotetakerRequest.MeetingSettings.Builder()\n .transcription(false)\n .build()\n\n val requestBody = UpdateNotetakerRequest.Builder()\n .name(\"Updated Notetaker name\")\n .meetingSettings(meetingSettings)\n .build()\n\n val notetaker = nylas.notetakers().update(\n \"<NOTETAKER_ID>\", requestBody, \"<NYLAS_GRANT_ID>\")\n\n println(\"Updated notetaker: ${notetaker.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/history\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n\n\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/cancel\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function cancelNotetaker() {\n try {\n const result = await nylas.notetakers.cancel({\n identifier: \"<NYLAS_GRANT_ID>\",\n notetakerId: \"<NOTETAKER_ID>\",\n });\n\n console.log(\"Cancelled notetaker:\", result);\n } catch (error) {\n console.error(\"Error cancelling notetaker:\", error);\n }\n}\n\ncancelNotetaker();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.notetakers.cancel(\n notetaker_id=\"<NOTETAKER_ID>\",\n identifier=\"<NYLAS_GRANT_ID>\",\n)\n\nprint(\"Notetaker cancelled:\", response)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.DeleteResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class CancelNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse result = nylas.notetakers().cancel(\"<NOTETAKER_ID>\", \"<NYLAS_GRANT_ID>\");\n\n System.out.println(\"Cancelled notetaker: \" + result);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val result = nylas.notetakers().cancel(\"<NOTETAKER_ID>\", \"<NYLAS_GRANT_ID>\")\n\n println(\"Cancelled notetaker: $result\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/leave\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function leaveMeeting() {\n try {\n const result = await nylas.notetakers.leave({\n identifier: \"<NYLAS_GRANT_ID>\",\n notetakerId: \"<NOTETAKER_ID>\",\n });\n\n console.log(\"Notetaker left meeting:\", result);\n } catch (error) {\n console.error(\"Error leaving meeting:\", error);\n }\n}\n\nleaveMeeting();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.notetakers.leave(\n notetaker_id=\"<NOTETAKER_ID>\",\n identifier=\"<NYLAS_GRANT_ID>\",\n)\n\nprint(\"Notetaker left meeting:\", response)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.LeaveNotetakerResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class LeaveNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<LeaveNotetakerResponse> result = nylas.notetakers().leave(\n \"<NOTETAKER_ID>\", \"<NYLAS_GRANT_ID>\");\n\n System.out.println(\"Notetaker left meeting: \" + result.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val result = nylas.notetakers().leave(\"<NOTETAKER_ID>\", \"<NYLAS_GRANT_ID>\")\n\n println(\"Notetaker left meeting: ${result.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/media\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function downloadMedia() {\n try {\n const media = await nylas.notetakers.downloadMedia({\n identifier: \"<NYLAS_GRANT_ID>\",\n notetakerId: \"<NOTETAKER_ID>\",\n });\n\n console.log(\"Media:\", media);\n } catch (error) {\n console.error(\"Error downloading media:\", error);\n }\n}\n\ndownloadMedia();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nmedia = nylas.notetakers.get_media(\n notetaker_id=\"<NOTETAKER_ID>\",\n identifier=\"<NYLAS_GRANT_ID>\",\n)\n\nprint(\"Notetaker media:\", media)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.NotetakerMediaResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class DownloadNotetakerMedia {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<NotetakerMediaResponse> media = nylas.notetakers().downloadMedia(\n \"<NOTETAKER_ID>\", \"<NYLAS_GRANT_ID>\");\n\n System.out.println(\"Media: \" + media.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val media = nylas.notetakers().downloadMedia(\"<NOTETAKER_ID>\", \"<NYLAS_GRANT_ID>\")\n\n println(\"Media: ${media.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/notetakers\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listStandaloneNotetakers() {\n try {\n const notetakers = await nylas.notetakers.list({\n queryParams: {\n limit: 50,\n },\n });\n\n console.log(\"Standalone notetakers:\", notetakers);\n } catch (error) {\n console.error(\"Error listing notetakers:\", error);\n }\n}\n\nlistStandaloneNotetakers();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnotetakers = nylas.notetakers.list(\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(\"Standalone notetakers:\", notetakers)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.ListNotetakersQueryParams;\nimport com.nylas.models.ListResponse;\nimport com.nylas.models.Notetaker;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class ListStandaloneNotetakers {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListNotetakersQueryParams queryParams = new ListNotetakersQueryParams.Builder()\n .limit(50)\n .build();\n\n // Omit the grant identifier to query the standalone (account-level) Notetakers.\n ListResponse<Notetaker> notetakers = nylas.notetakers().list(queryParams);\n\n System.out.println(\"Standalone notetakers: \" + notetakers.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ListNotetakersQueryParams\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val queryParams = ListNotetakersQueryParams.Builder()\n .limit(50)\n .build()\n\n // Omit the grant identifier to query the standalone (account-level) Notetakers.\n val notetakers = nylas.notetakers().list(queryParams)\n\n println(\"Standalone notetakers: ${notetakers.data}\")\n}\n"
}
],
"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.\n\n<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 \\\n --url \"https://api.us.nylas.com/v3/notetakers\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"join_time\": 1732657774,\n \"meeting_link\": \"https://meet.google.com/xyz-abcd-ijk\",\n \"meeting_settings\": {\n \"action_items\": true,\n \"action_items_settings\": {\n \"custom_instructions\": \"Only return the 5 most important action items.\"\n },\n \"audio_recording\": true,\n \"leave_after_silence_seconds\": 360,\n \"summary\": true,\n \"summary_settings\": {\n \"custom_instructions\": \"Return this summary in the MEDPIC sales methodology.\"\n },\n \"transcription\": true,\n \"transcription_settings\": {\n \"expected_languages\": [\"en\", \"es\"],\n \"fallback_language\": \"en\"\n },\n \"video_recording\": true\n },\n \"name\": \"Nylas Notetaker\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function inviteStandaloneNotetaker() {\n try {\n const notetaker = await nylas.notetakers.create({\n requestBody: {\n meetingLink: \"https://meet.google.com/abc-defg-hij\",\n name: \"Nylas Notetaker\",\n meetingSettings: {\n videoRecording: true,\n audioRecording: true,\n transcription: true,\n },\n },\n });\n\n console.log(\"Standalone notetaker:\", notetaker);\n } catch (error) {\n console.error(\"Error inviting notetaker:\", error);\n }\n}\n\ninviteStandaloneNotetaker();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnotetaker = nylas.notetakers.invite(\n request_body={\n \"meeting_link\": \"https://meet.google.com/abc-defg-hij\",\n \"name\": \"Nylas Notetaker\",\n \"meeting_settings\": {\n \"video_recording\": True,\n \"audio_recording\": True,\n \"transcription\": True,\n },\n },\n)\n\nprint(\"Invited standalone notetaker:\", notetaker)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.CreateNotetakerRequest;\nimport com.nylas.models.Notetaker;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class InviteStandaloneNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CreateNotetakerRequest.MeetingSettings meetingSettings =\n new CreateNotetakerRequest.MeetingSettings.Builder()\n .videoRecording(true)\n .audioRecording(true)\n .transcription(true)\n .build();\n\n CreateNotetakerRequest requestBody = new CreateNotetakerRequest.Builder(\n \"https://meet.google.com/abc-defg-hij\")\n .name(\"Nylas Notetaker\")\n .meetingSettings(meetingSettings)\n .build();\n\n // Omit the grant identifier to create a standalone (account-level) Notetaker.\n Response<Notetaker> notetaker = nylas.notetakers().create(requestBody);\n\n System.out.println(\"Standalone notetaker: \" + notetaker.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.CreateNotetakerRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val meetingSettings = CreateNotetakerRequest.MeetingSettings.Builder()\n .videoRecording(true)\n .audioRecording(true)\n .transcription(true)\n .build()\n\n val requestBody = CreateNotetakerRequest.Builder(\"https://meet.google.com/abc-defg-hij\")\n .name(\"Nylas Notetaker\")\n .meetingSettings(meetingSettings)\n .build()\n\n // Omit the grant identifier to create a standalone (account-level) Notetaker.\n val notetaker = nylas.notetakers().create(requestBody)\n\n println(\"Standalone notetaker: ${notetaker.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function findStandaloneNotetaker() {\n try {\n const notetaker = await nylas.notetakers.find({\n notetakerId: \"<NOTETAKER_ID>\",\n });\n\n console.log(\"Standalone notetaker:\", notetaker);\n } catch (error) {\n console.error(\"Error finding notetaker:\", error);\n }\n}\n\nfindStandaloneNotetaker();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nnotetaker = nylas.notetakers.find(\n notetaker_id=\"<NOTETAKER_ID>\",\n)\n\nprint(\"Standalone notetaker:\", notetaker)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Notetaker;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class FindStandaloneNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Omit the grant identifier to look up a standalone (account-level) Notetaker.\n Response<Notetaker> notetaker = nylas.notetakers().find(\"<NOTETAKER_ID>\");\n\n System.out.println(\"Standalone notetaker: \" + notetaker.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n // Omit the grant identifier to look up a standalone (account-level) Notetaker.\n val notetaker = nylas.notetakers().find(\"<NOTETAKER_ID>\")\n\n println(\"Standalone notetaker: ${notetaker.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Nylas Notetaker\",\n \"join_time\": 1732657774,\n \"meeting_settings\": {\n \"action_items\": true,\n \"action_items_settings\": {\n \"custom_instructions\": \"Only return the 5 most important action items.\"\n },\n \"audio_recording\": true,\n \"summary\": true,\n \"summary_settings\": {\n \"custom_instructions\": \"Return this summary in the MEDPIC sales methodology.\"\n },\n \"transcription\": true,\n \"transcription_settings\": {\n \"expected_languages\": [\"en\", \"es\"],\n \"fallback_language\": \"en\"\n },\n \"video_recording\": true\n }\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateStandaloneNotetaker() {\n try {\n const notetaker = await nylas.notetakers.update({\n notetakerId: \"<NOTETAKER_ID>\",\n requestBody: {\n name: \"Updated Notetaker name\",\n meetingSettings: {\n transcription: false,\n },\n },\n });\n\n console.log(\"Updated notetaker:\", notetaker);\n } catch (error) {\n console.error(\"Error updating notetaker:\", error);\n }\n}\n\nupdateStandaloneNotetaker();\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Notetaker;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\nimport com.nylas.models.UpdateNotetakerRequest;\n\npublic class UpdateStandaloneNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n UpdateNotetakerRequest.MeetingSettings meetingSettings =\n new UpdateNotetakerRequest.MeetingSettings.Builder()\n .transcription(false)\n .build();\n\n UpdateNotetakerRequest requestBody = new UpdateNotetakerRequest.Builder()\n .name(\"Updated Notetaker name\")\n .meetingSettings(meetingSettings)\n .build();\n\n // Omit the grant identifier to update a standalone (account-level) Notetaker.\n Response<Notetaker> notetaker = nylas.notetakers().update(\"<NOTETAKER_ID>\", requestBody);\n\n System.out.println(\"Updated standalone notetaker: \" + notetaker.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.UpdateNotetakerRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val meetingSettings = UpdateNotetakerRequest.MeetingSettings.Builder()\n .transcription(false)\n .build()\n\n val requestBody = UpdateNotetakerRequest.Builder()\n .name(\"Updated Notetaker name\")\n .meetingSettings(meetingSettings)\n .build()\n\n // Omit the grant identifier to update a standalone (account-level) Notetaker.\n val notetaker = nylas.notetakers().update(\"<NOTETAKER_ID>\", requestBody)\n\n println(\"Updated standalone notetaker: ${notetaker.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>/history\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'\n\n\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>/cancel\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function cancelStandaloneNotetaker() {\n try {\n const result = await nylas.notetakers.cancel({\n notetakerId: \"<NOTETAKER_ID>\",\n });\n\n console.log(\"Cancelled notetaker:\", result);\n } catch (error) {\n console.error(\"Error cancelling notetaker:\", error);\n }\n}\n\ncancelStandaloneNotetaker();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.notetakers.cancel(\n notetaker_id=\"<NOTETAKER_ID>\",\n)\n\nprint(\"Standalone notetaker cancelled:\", response)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.DeleteResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class CancelStandaloneNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Omit the grant identifier to cancel a standalone (account-level) Notetaker.\n DeleteResponse result = nylas.notetakers().cancel(\"<NOTETAKER_ID>\");\n\n System.out.println(\"Cancelled standalone notetaker: \" + result);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n // Omit the grant identifier to cancel a standalone (account-level) Notetaker.\n val result = nylas.notetakers().cancel(\"<NOTETAKER_ID>\")\n\n println(\"Cancelled standalone notetaker: $result\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>/leave\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function leaveStandaloneMeeting() {\n try {\n const result = await nylas.notetakers.leave({\n notetakerId: \"<NOTETAKER_ID>\",\n });\n\n console.log(\"Notetaker left meeting:\", result);\n } catch (error) {\n console.error(\"Error leaving meeting:\", error);\n }\n}\n\nleaveStandaloneMeeting();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.notetakers.leave(\n notetaker_id=\"<NOTETAKER_ID>\",\n)\n\nprint(\"Standalone notetaker left meeting:\", response)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.LeaveNotetakerResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class LeaveStandaloneNotetaker {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Omit the grant identifier to remove a standalone (account-level) Notetaker.\n Response<LeaveNotetakerResponse> result = nylas.notetakers().leave(\"<NOTETAKER_ID>\");\n\n System.out.println(\"Standalone notetaker left meeting: \" + result.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n // Omit the grant identifier to remove a standalone (account-level) Notetaker.\n val result = nylas.notetakers().leave(\"<NOTETAKER_ID>\")\n\n println(\"Standalone notetaker left meeting: ${result.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/notetakers/<NOTETAKER_ID>/media\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function downloadStandaloneMedia() {\n try {\n const media = await nylas.notetakers.downloadMedia({\n notetakerId: \"<NOTETAKER_ID>\",\n });\n\n console.log(\"Media:\", media);\n } catch (error) {\n console.error(\"Error downloading media:\", error);\n }\n}\n\ndownloadStandaloneMedia();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nmedia = nylas.notetakers.get_media(\n notetaker_id=\"<NOTETAKER_ID>\",\n)\n\nprint(\"Standalone notetaker media:\", media)\n"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.NotetakerMediaResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class DownloadStandaloneNotetakerMedia {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n // Omit the grant identifier for standalone (account-level) Notetaker media.\n Response<NotetakerMediaResponse> media = nylas.notetakers().downloadMedia(\"<NOTETAKER_ID>\");\n\n System.out.println(\"Media: \" + media.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n // Omit the grant identifier for standalone (account-level) Notetaker media.\n val media = nylas.notetakers().downloadMedia(\"<NOTETAKER_ID>\")\n\n println(\"Media: ${media.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/templates\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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 \\\n --url \"https://api.us.nylas.com/v3/templates\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"body\": \"<p>Hello from {{user}}</p>\",\n \"name\": \"Nylas Alias\",\n \"subject\": \"New notification for {{user}}\",\n \"engine\": \"mustache\"\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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 \\\n --url \"https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"body\": \"<p>Test from {{user.name}}</p>\",\n \"name\": \"Update Template\",\n \"subject\": \"Test from {{user.name}}\",\n \"engine\": \"mustache\"\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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\ntemplating 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 \\\n --url \"https://api.us.nylas.com/v3/templates/render\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"body\": \"<p>Hello from {{user.name}}, test {{ foo }}</p>\",\n \"variables\": {\n \"user\": {\n \"name\": \"Nylas\",\n \"surname\": \"Tester\"\n },\n \"foo\": \"hi\"\n },\n \"engine\": \"mustache\"\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/templates/<TEMPLATE_ID>/render\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"variables\": {\n \"user\": {\n \"name\": \"Nylas\",\n \"surname\": \"Tester\"\n }\n }\n }'"
}
],
"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\n`/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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"body\": \"<p>Hello from {{user}}</p>\",\n \"name\": \"Nylas Alias\",\n \"subject\": \"New notification for {{user}}\",\n \"engine\": \"mustache\"\n }'"
}
],
"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\n`/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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/<TEMPLATE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/<TEMPLATE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"body\": \"<p>Test from {{user.name}}</p>\",\n \"name\": \"Update Template\",\n \"subject\": \"Test from {{user.name}}\",\n \"engine\": \"mustache\"\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/<TEMPLATE_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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\n`/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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/<TEMPLATE_ID>/render\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"variables\": {\n \"user\": {\n \"name\": \"Nylas\",\n \"surname\": \"Tester\"\n }\n }\n }'"
}
],
"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\n`/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\ntemplating 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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/templates/render\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"body\": \"<p>Hello from {{user.name}}, test {{ foo }}</p>\",\n \"variables\": {\n \"user\": {\n \"name\": \"Nylas\",\n \"surname\": \"Tester\"\n },\n \"foo\": \"hi\"\n },\n \"engine\": \"mustache\"\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/workflows?limit=10\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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.\n\n<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 \\\n --url \"https://api.us.nylas.com/v3/workflows\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Confirmation Workflow\",\n \"trigger_event\": \"booking.created\",\n \"template_id\": \"<TEMPLATE_ID>\",\n \"delay\": 1,\n \"is_enabled\": true\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/workflows/<WORKFLOW_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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 \\\n --url \"https://api.us.nylas.com/v3/workflows/<WORKFLOW_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Updated Workflow\",\n \"is_enabled\": false\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/workflows/<WORKFLOW_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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\n`/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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows?limit=10\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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.\n\n<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 \\\n --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Confirmation Workflow\",\n \"trigger_event\": \"booking.created\",\n \"template_id\": \"<TEMPLATE_ID>\",\n \"delay\": 1,\n \"is_enabled\": true\n }'"
}
],
"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\n`/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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows/<WORKFLOW_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows/<WORKFLOW_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"Updated Workflow\",\n \"is_enabled\": false\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/workflows/<WORKFLOW_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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\n`/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\nsession.\n\n### Duplicate email notifications\n\nIf the organizer in a scheduling session is a Microsoft account user, both the organizer and all\nattendees might receive duplicate email notifications, including booking confirmations, rescheduling\nand cancellation notifications, and reminders. This is because of the way Microsoft handles email\nnotifications. If you set notifications in Scheduler, Microsoft also sends its own notifications\nto the event organizer and attendees. Microsoft doesn't provide a way to disable these\nnotifications.\n\n### Metadata as additional fields\n\nYou can add metadata fields (`type: metadata`) to your Configuration to store custom information\nabout a booking. For example, you can add campaign tags or keywords to track specific bookings.\n\nBooking webhook notifications (`booking.created`, `booking.rescheduled`, `booking.cancelled`,\n`booking.pending`, and `booking.reminder`) include your metadata fields in\n`booking_info.additional_fields`. Calendar event webhooks (for example, `event.updated`) do _not_\ninclude them, and email notifications and booking forms don't display them.\n\nTo identify Scheduler-related changes in event webhooks instead, use the metadata that Scheduler\nstamps on the calendar events it creates. For more information, see the\n[`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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"requires_session_auth\": false,\n \"participants\": [{\n \"name\": \"Nyla\",\n \"email\": \"nyla@example.com\",\n \"is_organizer\": true,\n \"availability\": {\n \"calendar_ids\": [\"primary\"]\n },\n \"booking\": {\n \"calendar_id\": \"primary\"\n }\n }],\n \"availability\": {\n \"duration_minutes\": 30\n },\n \"event_booking\": {\n \"title\": \"Testing Scheduler\",\n \"hide_participants\": false,\n \"conferencing\": {\n \"provider\": \"Zoom Meeting\",\n \"autocreate\": {\n \"conf_grant_id\": \"<NYLAS_GRANT_ID>\",\n \"conf_settings\": {\n \"settings\": {\n \"join_before_host\": true,\n \"waiting_room\": false,\n \"mute_upon_entry\": false,\n \"auto_recording\": \"none\"\n }\n }\n }\n }\n }\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createConfiguration() {\n try {\n const configuration = await nylas.scheduler.configurations.create({\n identifier: \"<NYLAS_GRANT_ID>\",\n requestBody: {\n participants: [\n {\n email: \"host@example.com\",\n isOrganizer: true,\n availability: {\n calendarIds: [\"primary\"],\n },\n booking: {\n calendarId: \"primary\",\n },\n },\n ],\n availability: {\n durationMinutes: 30,\n },\n eventBooking: {\n title: \"30-minute meeting\",\n },\n },\n });\n\n console.log(\"Configuration:\", configuration);\n } catch (error) {\n console.error(\"Error creating configuration:\", error);\n }\n}\n\ncreateConfiguration();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nconfiguration = nylas.scheduler.configurations.create(\n identifier=\"<NYLAS_GRANT_ID>\",\n request_body={\n \"participants\": [\n {\n \"name\": \"<HOST_NAME>\",\n \"email\": \"<HOST_EMAIL>\",\n \"is_organizer\": True,\n \"availability\": {\n \"calendar_ids\": [\"<CALENDAR_ID>\"],\n },\n \"booking\": {\n \"calendar_id\": \"<CALENDAR_ID>\",\n },\n }\n ],\n \"availability\": {\n \"duration_minutes\": 30,\n },\n \"event_booking\": {\n \"title\": \"30-minute meeting\",\n },\n },\n)\n\nprint(\"Configuration:\", configuration)\n"
},
{
"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\nrequest_body = {\n \"requires_session_auth\": false,\n \"participants\": [\n {\n \"name\": \"Test\",\n \"email\": \"nylas_test_8@nylas.com\",\n \"is_organizer\": true,\n \"availability\": {\n \"calendar_ids\": [\n \"primary\"\n ]\n },\n \"booking\": {\n \"calendar_id\": \"primary\"\n }\n }\n ],\n \"availability\": {\n \"duration_minutes\": 30\n },\n \"event_booking\": {\n \"title\": \"My test event\",\n \"hide_participants\": false\n }\n}\n\n# Create a configuration\nconfiguration, _request_ids = nylas.scheduler.configurations.create(identifier: \"<NYLAS_GRANT_ID>\", request_body: request_body)\n\nputs configuration"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Configuration;\nimport com.nylas.models.ConfigurationAvailability;\nimport com.nylas.models.ConfigurationAvailabilityParticipant;\nimport com.nylas.models.ConfigurationBookingParticipant;\nimport com.nylas.models.ConfigurationEventBooking;\nimport com.nylas.models.ConfigurationParticipant;\nimport com.nylas.models.CreateConfigurationRequest;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\nimport java.util.Collections;\nimport java.util.List;\n\npublic class CreateConfiguration {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ConfigurationParticipant participant = new ConfigurationParticipant.Builder(\"host@example.com\")\n .isOrganizer(true)\n .availability(new ConfigurationAvailabilityParticipant.Builder()\n .calendarIds(Collections.singletonList(\"primary\"))\n .build())\n .booking(new ConfigurationBookingParticipant.Builder()\n .calendarId(\"primary\")\n .build())\n .build();\n\n ConfigurationAvailability availability = new ConfigurationAvailability.Builder()\n .durationMinutes(30)\n .build();\n\n ConfigurationEventBooking eventBooking = new ConfigurationEventBooking.Builder()\n .title(\"30-minute meeting\")\n .build();\n\n CreateConfigurationRequest requestBody = new CreateConfigurationRequest.Builder(\n Collections.singletonList(participant), availability, eventBooking)\n .build();\n\n Response<Configuration> configuration = nylas.scheduler().configurations()\n .create(\"<NYLAS_GRANT_ID>\", requestBody);\n\n System.out.println(\"Configuration: \" + configuration.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ConfigurationAvailability\nimport com.nylas.models.ConfigurationAvailabilityParticipant\nimport com.nylas.models.ConfigurationBookingParticipant\nimport com.nylas.models.ConfigurationEventBooking\nimport com.nylas.models.ConfigurationParticipant\nimport com.nylas.models.CreateConfigurationRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val participant = ConfigurationParticipant.Builder(\"host@example.com\")\n .isOrganizer(true)\n .availability(ConfigurationAvailabilityParticipant.Builder()\n .calendarIds(listOf(\"primary\"))\n .build())\n .booking(ConfigurationBookingParticipant.Builder()\n .calendarId(\"primary\")\n .build())\n .build()\n\n val availability = ConfigurationAvailability.Builder()\n .durationMinutes(30)\n .build()\n\n val eventBooking = ConfigurationEventBooking.Builder()\n .title(\"30-minute meeting\")\n .build()\n\n val requestBody = CreateConfigurationRequest.Builder(\n listOf(participant), availability, eventBooking)\n .build()\n\n val configuration = nylas.scheduler().configurations()\n .create(\"<NYLAS_GRANT_ID>\", requestBody)\n\n println(\"Configuration: ${configuration.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function listConfigurations() {\n try {\n const configurations = await nylas.scheduler.configurations.list({\n identifier: \"<NYLAS_GRANT_ID>\",\n });\n\n console.log(\"Configurations:\", configurations);\n } catch (error) {\n console.error(\"Error listing configurations:\", error);\n }\n}\n\nlistConfigurations();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nconfigurations = nylas.scheduler.configurations.list(\n identifier=\"<NYLAS_GRANT_ID>\",\n query_params={\n \"limit\": 50,\n },\n)\n\nprint(\"Configurations:\", configurations)\n"
},
{
"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;\nimport com.nylas.models.Configuration;\nimport com.nylas.models.ListResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class ListConfigurations {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ListResponse<Configuration> configurations = nylas.scheduler().configurations()\n .list(\"<NYLAS_GRANT_ID>\");\n\n System.out.println(\"Configurations: \" + configurations.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val configurations = nylas.scheduler().configurations().list(\"<NYLAS_GRANT_ID>\")\n\n println(\"Configurations: ${configurations.data}\")\n}\n"
}
],
"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\n`/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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function findConfiguration() {\n try {\n const configuration = await nylas.scheduler.configurations.find({\n identifier: \"<NYLAS_GRANT_ID>\",\n configurationId: \"<CONFIGURATION_ID>\",\n });\n\n console.log(\"Configuration:\", configuration);\n } catch (error) {\n console.error(\"Error finding configuration:\", error);\n }\n}\n\nfindConfiguration();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nconfiguration = nylas.scheduler.configurations.find(\n identifier=\"<NYLAS_GRANT_ID>\",\n config_id=\"<SCHEDULER_CONFIG_ID>\",\n)\n\nprint(\"Configuration:\", configuration)\n"
},
{
"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\nconfiguration, _request_ids = nylas.scheduler.configurations.find(identifier: \"<NYLAS_GRANT_ID>\", configuration_id: \"<SCHEDULER_CONFIG_ID>\")\n\nputs configuration"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Configuration;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class FindConfiguration {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n Response<Configuration> configuration = nylas.scheduler().configurations()\n .find(\"<NYLAS_GRANT_ID>\", \"<CONFIGURATION_ID>\");\n\n System.out.println(\"Configuration: \" + configuration.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val configuration = nylas.scheduler().configurations()\n .find(\"<NYLAS_GRANT_ID>\", \"<CONFIGURATION_ID>\")\n\n println(\"Configuration: ${configuration.data}\")\n}\n"
}
],
"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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"event_booking\": {\n \"title\": \"Testing Scheduler\",\n \"hide_participants\": false,\n \"conferencing\": {\n \"provider\": \"Zoom Meeting\",\n \"autocreate\": {\n \"conf_grant_id\": \"<NYLAS_GRANT_ID>\",\n \"conf_settings\": {\n \"settings\": {\n \"join_before_host\": true,\n \"waiting_room\": false,\n \"mute_upon_entry\": false,\n \"auto_recording\": \"none\"\n }\n }\n }\n }\n }\n \"scheduler\": {\n \"rescheduling_url\": \"https://www.example.com/reschdule/:booking_ref\",\n \"cancellation_url\": \"https://www.example.com/cancel/:booking_ref\" \n }\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function updateConfiguration() {\n try {\n const configuration = await nylas.scheduler.configurations.update({\n identifier: \"<NYLAS_GRANT_ID>\",\n configurationId: \"<CONFIGURATION_ID>\",\n requestBody: {\n availability: {\n durationMinutes: 45,\n },\n },\n });\n\n console.log(\"Updated configuration:\", configuration);\n } catch (error) {\n console.error(\"Error updating configuration:\", error);\n }\n}\n\nupdateConfiguration();\n"
},
{
"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\nrequest_body = {\n \"availability\": {\n \"duration_minutes\": 60\n }\n}\n\nconfiguration, _request_ids = nylas.scheduler.configurations.update(identifier: \"<NYLAS_GRANT_ID>\", configuration_id: \"<SCHEDULER_CONFIG_ID>\", request_body: request_body)\n\nputs configuration"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Configuration;\nimport com.nylas.models.ConfigurationAvailability;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\nimport com.nylas.models.UpdateConfigurationRequest;\n\npublic class UpdateConfiguration {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ConfigurationAvailability availability = new ConfigurationAvailability.Builder()\n .durationMinutes(45)\n .build();\n\n UpdateConfigurationRequest requestBody = new UpdateConfigurationRequest.Builder()\n .availability(availability)\n .build();\n\n Response<Configuration> configuration = nylas.scheduler().configurations()\n .update(\"<NYLAS_GRANT_ID>\", \"<CONFIGURATION_ID>\", requestBody);\n\n System.out.println(\"Updated configuration: \" + configuration.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ConfigurationAvailability\nimport com.nylas.models.UpdateConfigurationRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val availability = ConfigurationAvailability.Builder()\n .durationMinutes(45)\n .build()\n\n val requestBody = UpdateConfigurationRequest.Builder()\n .availability(availability)\n .build()\n\n val configuration = nylas.scheduler().configurations()\n .update(\"<NYLAS_GRANT_ID>\", \"<CONFIGURATION_ID>\", requestBody)\n\n println(\"Updated configuration: ${configuration.data}\")\n}\n"
}
],
"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\nsessions.",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --compressed --request DELETE \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteConfiguration() {\n try {\n const result = await nylas.scheduler.configurations.destroy({\n identifier: \"<NYLAS_GRANT_ID>\",\n configurationId: \"<CONFIGURATION_ID>\",\n });\n\n console.log(\"Deleted configuration:\", result);\n } catch (error) {\n console.error(\"Error deleting configuration:\", error);\n }\n}\n\ndeleteConfiguration();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.scheduler.configurations.destroy(\n identifier=\"<NYLAS_GRANT_ID>\",\n config_id=\"<SCHEDULER_CONFIG_ID>\",\n)\n\nprint(\"Configuration deleted:\", response)\n"
},
{
"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_, request_ids = nylas.scheduler.configurations.destroy(identifier: \"<NYLAS_GRANT_ID>\", configuration_id: \"<SCHEDULER_CONFIG_ID>\")\n\nputs request_ids"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.DeleteResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class DeleteConfiguration {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse result = nylas.scheduler().configurations()\n .destroy(\"<NYLAS_GRANT_ID>\", \"<CONFIGURATION_ID>\", null);\n\n System.out.println(\"Deleted configuration: \" + result);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val result = nylas.scheduler().configurations()\n .destroy(\"<NYLAS_GRANT_ID>\", \"<CONFIGURATION_ID>\")\n\n println(\"Deleted configuration: $result\")\n}\n"
}
],
"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 \\\n --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>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>/group-events\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"title\": \"Annual Philosophy Club Meeting\",\n \"busy\": true,\n \"participants\": [\n {\n \"name\": \"Leyah Miller\",\n \"email\": \"leyah@example.com\",\n \"is_organizer\": true\n },\n {\n \"name\": \"Nyla\",\n \"email\": \"nyla@example.com\",\n \"is_organizer\": false\n }\n ],\n \"description\": \"Come ready to talk philosophy!\",\n \"when\": {\n \"start_time\": 1674604800,\n \"end_time\": 1722382420,\n \"start_timezone\": \"America/New_York\",\n \"end_timezone\": \"America/New_York\"\n },\n \"location\": \"New York Public Library, Cave room\",\n \"recurrence\": [\n \"RRULE:FREQ=WEEKLY;BYDAY=MO\",\n \"EXDATE:20211011T000000Z\"\n ],\n \"capacity\": 100\n }'"
}
],
"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.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>/group-events/<EVENT_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"scheduler\": {\n \"rescheduling_url\": \"<RESCHEDULING_PAGE_URL>\",\n \"cancellation_url\": \"<CANCELLATION_PAGE_URL>\" \n }\n }'"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>/group-events/<EVENT_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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\nrequest.",
"requestBody": {
"$ref": "#/components/requestBodies/import_group_event"
},
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --compressed --request POST \\\n --url \"https://api.us.nylas.com/v3/scheduling/configurations/<SCHEDULER_CONFIG_ID>/import-group-events\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"calendar_id\": \"<CALENDAR_ID>\",\n \"event_id\": \"<EVENT_ID>\",\n \"capacity\": 10,\n \"exceptions\": [{\n \"event_id\": \"<EVENT_ID>\",\n \"capacity\": 5\n }],\n \"participants\": [{\n \"name\": \"Leyah Miller\",\n \"email\": \"leyah@example.com\"\n }]\n }'"
}
],
"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\nbecause...\n\n- The group event was deleted.\n- The group event was updated (for example, the start time was changed).\n- 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 \\\n --url \"https://api.us.nylas.com/v3/scheduling/configurations/<SCHEDULER_CONFIG_ID>/group-events/validate-timeslot\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"calendar_id\": \"<CALENDAR_ID>\",\n \"event_id\": \"<EVENT_ID>\",\n \"capacity\": 10,\n \"end_time\": 1738156200,\n \"start_time\": 1738155600,\n \"emails\": [\n \"email\": \"leyah@example.com\"\n ]\n }'"
}
],
"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\nauthentication. Your request must include the ID of an existing Configuration object.",
"x-code-samples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --compressed --request POST \\\n --url \"https://api.us.nylas.com/v3/scheduling/sessions\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"configuration_id\": \"<SCHEDULER_CONFIGURATION_ID>\",\n \"time_to_live\": 10\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createSession() {\n try {\n const session = await nylas.scheduler.sessions.create({\n requestBody: {\n configurationId: \"<CONFIGURATION_ID>\",\n timeToLive: 30,\n },\n });\n\n console.log(\"Session:\", session);\n } catch (error) {\n console.error(\"Error creating session:\", error);\n }\n}\n\ncreateSession();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nsession = nylas.scheduler.sessions.create(\n request_body={\n \"configuration_id\": \"<SCHEDULER_CONFIG_ID>\",\n \"time_to_live\": 30,\n },\n)\n\nprint(\"Created session:\", session)\n"
},
{
"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\nrequest_body = {\n \"configuration_id\": \"<SCHEDULER_CONFIG_ID>\",\n \"time_to_live\": 30\n}\n\nsession, _request_ids = nylas.scheduler.sessions.create(request_body: request_body)\n\nputs session"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.CreateSessionRequest;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\nimport com.nylas.models.Session;\n\npublic class CreateSession {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n CreateSessionRequest requestBody = new CreateSessionRequest.Builder()\n .configurationId(\"<CONFIGURATION_ID>\")\n .timeToLive(30)\n .build();\n\n Response<Session> session = nylas.scheduler().sessions().create(requestBody);\n\n System.out.println(\"Session: \" + session.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.CreateSessionRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val requestBody = CreateSessionRequest.Builder()\n .configurationId(\"<CONFIGURATION_ID>\")\n .timeToLive(30)\n .build()\n\n val session = nylas.scheduler().sessions().create(requestBody)\n\n println(\"Session: ${session.data}\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/scheduling/sessions/<SCHEDULER_SESSION_ID>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' "
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteSession() {\n try {\n const result = await nylas.scheduler.sessions.destroy({\n sessionId: \"<SESSION_ID>\",\n });\n\n console.log(\"Deleted session:\", result);\n } catch (error) {\n console.error(\"Error deleting session:\", error);\n }\n}\n\ndeleteSession();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.scheduler.sessions.destroy(\n session_id=\"<SESSION_ID>\",\n)\n\nprint(\"Session deleted:\", response)\n"
},
{
"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_, request_ids = nylas.scheduler.sessions.destroy(session_id: \"<SCHEDULER_SESSION_ID>\")"
},
{
"lang": "java",
"label": "Java SDK",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.DeleteResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class DeleteSession {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DeleteResponse result = nylas.scheduler().sessions().destroy(\"<SESSION_ID>\");\n\n System.out.println(\"Deleted session: \" + result);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val result = nylas.scheduler().sessions().destroy(\"<SESSION_ID>\")\n\n println(\"Deleted session: $result\")\n}\n"
}
],
"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\nauthentication (`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\n`configuration_id`. If you're using session authentication (`requires_session_auth: true`) or\nusing 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\n`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\nbooking. Required only if `availability_method` is `max-fairness` or `max-availability`. See\n[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\nConfiguration object. If the Configuration `type` is `group`, Nylas returns only valid group events\nwithin the time range, including recurring events.\n\nNylas validates the provided session ID and uses it to retrieve the related\n[Configuration object](/docs/reference/api/configurations/). If you created a public\nConfiguration, you don't need to include the `Authorization` request header with a session ID, but\nyou 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 \\\n --url 'https://api.us.nylas.com/v3/scheduling/availability?start_time=1709643600&end_time=1709665200&configuration_id=<SCHEDULER_CONFIG_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "bash",
"label": "cURL (Private)",
"source": "curl --compressed --request GET \\\n --url 'https://api.us.nylas.com/v3/scheduling/availability?start_time=1709643600&end_time=1709665200' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \\\n --header 'Content-Type: application/json' "
},
{
"lang": "javascript",
"label": "Node.js SDK",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function getAvailability() {\n try {\n const availability = await nylas.scheduler.availability.get({\n queryParams: {\n configurationId: \"<CONFIGURATION_ID>\",\n startTime: 1748908800,\n endTime: 1748995200,\n },\n });\n\n console.log(\"Availability:\", availability);\n } catch (error) {\n console.error(\"Error getting availability:\", error);\n }\n}\n\ngetAvailability();\n"
}
],
"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\n[Configuration object](/docs/reference/api/configurations/), using the details from the\nConfiguration. The `start_time` and `end_time` must correspond to a valid time slot returned by\nthe\n[Scheduling Availability endpoint](/docs/reference/api/availability/get-availability/)\nusing the same Configuration.\n\nNylas validates the session ID and uses it to retrieve the related Configuration object. If you\ncreated a public Configuration, you don't need to include the `Authorization` request header with\na 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 \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings?configuration_id=<SCHEDULER_CONFIG_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"start_time\": 1709643600,\n \"end_time\": 1709645400,\n \"participants\": [],\n \"guest\": {\n \"name\": \"Jane Doe\",\n \"email\": \"jane.doe@example.com\"\n }\n }'"
},
{
"lang": "bash",
"label": "cURL (Private)",
"source": "curl --compressed --request POST \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"start_time\": 1709643600,\n \"end_time\": 1709645400,\n \"participants\": [],\n \"guest\": {\n \"name\": \"Jane Doe\",\n \"email\": \"jane.doe@example.com\"\n }\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK (Public)",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createBooking() {\n try {\n const booking = await nylas.scheduler.bookings.create({\n queryParams: {\n configurationId: \"<SCHEDULER_CONFIG_ID>\",\n },\n requestBody: {\n startTime: 1763119800,\n endTime: 1763121600,\n guest: {\n name: \"Jane Doe\",\n email: \"jane.doe@example.com\",\n },\n },\n });\n console.log(\"Created Booking\", booking);\n } catch (error) {\n console.error(\"Error creating booking\", error);\n }\n}\ncreateBooking();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nbooking = nylas.scheduler.bookings.create(\n request_body={\n \"start_time\": 1763119800,\n \"end_time\": 1763121600,\n \"guest\": {\n \"name\": \"Jane Doe\",\n \"email\": \"jane.doe@example.com\",\n },\n },\n query_params={\n \"configuration_id\": \"<SCHEDULER_CONFIG_ID>\",\n },\n)\n\nprint(\"Created booking:\", booking)\n"
},
{
"lang": "javascript",
"label": "Node.js SDK (Private)",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createBooking() {\n try {\n const booking = await nylas.scheduler.bookings.create({\n requestBody: {\n startTime: 1763119800,\n endTime: 1763121600,\n guest: {\n name: \"Jane Doe\",\n email: \"jane.doe@example.com\",\n },\n },\n });\n console.log(\"Created Booking\", booking);\n } catch (error) {\n console.error(\"Error creating booking\", error);\n }\n}\ncreateBooking();\n"
},
{
"lang": "ruby",
"label": "Ruby SDK (Public)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n \"start_time\": 1709643600,\n \"end_time\": 1709645400,\n \"participants\": [],\n \"guest\": {\n \"name\": \"Jane Doe\",\n \"email\": \"jane.doe@example.com\"\n }\n}\n\nbooking, _request_ids = nylas.scheduler.bookings.create(request_body: request_body, query_params: { configuration_id: \"<SCHEDULER_CONFIG_ID>\" })\n\nputs booking"
},
{
"lang": "ruby",
"label": "Ruby SDK (Private)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<SCHEDULER_SESSION_ID>\"\n)\n\nrequest_body = {\n \"start_time\": 1709643600,\n \"end_time\": 1709645400,\n \"participants\": [],\n \"guest\": {\n \"name\": \"Jane Doe\",\n \"email\": \"jane.doe@example.com\"\n }\n}\n\nbooking, _request_ids = nylas.scheduler.bookings.create(request_body: request_body)\n\nputs booking"
},
{
"lang": "java",
"label": "Java SDK (Public)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Booking;\nimport com.nylas.models.BookingGuest;\nimport com.nylas.models.CreateBookingQueryParams;\nimport com.nylas.models.CreateBookingRequest;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class CreateBookingPublic {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n BookingGuest guest = new BookingGuest(\"jane.doe@example.com\", \"Jane Doe\");\n\n CreateBookingRequest requestBody = new CreateBookingRequest.Builder()\n .startTime(\"1763119800\")\n .endTime(\"1763121600\")\n .guest(guest)\n .build();\n\n // Public Configuration objects need the configuration ID as a query parameter.\n CreateBookingQueryParams queryParams = new CreateBookingQueryParams.Builder()\n .configurationId(\"<SCHEDULER_CONFIG_ID>\")\n .build();\n\n Response<Booking> booking = nylas.scheduler().bookings().create(requestBody, queryParams);\n\n System.out.println(\"Created booking: \" + booking.getData());\n }\n}\n"
},
{
"lang": "java",
"label": "Java SDK (Private)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Booking;\nimport com.nylas.models.BookingGuest;\nimport com.nylas.models.CreateBookingRequest;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class CreateBooking {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n // Use a Scheduler session ID as the API key for session-authenticated bookings.\n NylasClient nylas = new NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build();\n\n BookingGuest guest = new BookingGuest(\"jane.doe@example.com\", \"Jane Doe\");\n\n CreateBookingRequest requestBody = new CreateBookingRequest.Builder()\n .startTime(\"1763119800\")\n .endTime(\"1763121600\")\n .guest(guest)\n .build();\n\n Response<Booking> booking = nylas.scheduler().bookings().create(requestBody);\n\n System.out.println(\"Created booking: \" + booking.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Public)",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.BookingGuest\nimport com.nylas.models.CreateBookingQueryParams\nimport com.nylas.models.CreateBookingRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val guest = BookingGuest(email = \"jane.doe@example.com\", name = \"Jane Doe\")\n\n val requestBody = CreateBookingRequest.Builder()\n .startTime(\"1763119800\")\n .endTime(\"1763121600\")\n .guest(guest)\n .build()\n\n // Public Configuration objects need the configuration ID as a query parameter.\n val queryParams = CreateBookingQueryParams.Builder()\n .configurationId(\"<SCHEDULER_CONFIG_ID>\")\n .build()\n\n val booking = nylas.scheduler().bookings().create(requestBody, queryParams)\n\n println(\"Created booking: ${booking.data}\")\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Private)",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.BookingGuest\nimport com.nylas.models.CreateBookingRequest\n\nfun main() {\n // Use a Scheduler session ID as the API key for session-authenticated bookings.\n val nylas = NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build()\n\n val guest = BookingGuest(email = \"jane.doe@example.com\", name = \"Jane Doe\")\n\n val requestBody = CreateBookingRequest.Builder()\n .startTime(\"1763119800\")\n .endTime(\"1763121600\")\n .guest(guest)\n .build()\n\n val booking = nylas.scheduler().bookings().create(requestBody)\n\n println(\"Created booking: ${booking.data}\")\n}\n"
}
],
"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\nauthentication (`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\n`configuration_id`. If you're using session authentication (`requires_session_auth: true`) or\nusing 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\n`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.\n\nNylas validates the provided session ID and uses it to retrieve the related\n[Configuration object](/docs/reference/api/configurations/). If you created a public\nConfiguration, you don't need to include the `Authorization` request header with a session ID, but\nyou 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 \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "bash",
"label": "cURL (Private)",
"source": "curl --compressed --request GET \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "javascript",
"label": "Node.js SDK (Public)",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchBookingById() {\n try {\n const booking = await nylas.scheduler.bookings.find({\n queryParams: {\n configurationId: \"<SCHEDULER_CONFIG_ID>\",\n },\n bookingId: \"<BOOKING_ID>\",\n });\n console.log(\"Booking\", booking);\n } catch (error) {\n console.error(\"Error fetching booking\", error);\n }\n}\n\nfetchBookingById();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nbooking = nylas.scheduler.bookings.find(\n booking_id=\"<BOOKING_ID>\",\n query_params={\n \"configuration_id\": \"<SCHEDULER_CONFIG_ID>\",\n },\n)\n\nprint(\"Booking:\", booking)\n"
},
{
"lang": "javascript",
"label": "Node.js SDK (Private)",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<SCHEDULER_SESSION_ID>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function fetchBookingById() {\n try {\n const booking = await nylas.scheduler.bookings.find({\n bookingId: \"<BOOKING_ID>\",\n });\n console.log(\"Booking\", booking);\n } catch (error) {\n console.error(\"Error fetching booking\", error);\n }\n}\n\nfetchBookingById();\n"
},
{
"lang": "ruby",
"label": "Ruby SDK (Public)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nbooking, _request_ids = nylas.scheduler.bookings.find(booking_id: \"<SCHEDULER_BOOKING_ID>\", query_params: { configuration_id: \"<SCHEDULER_CONFIG_ID>\" })\n\nputs booking"
},
{
"lang": "ruby",
"label": "Ruby SDK (Private)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<SCHEDULER_SESSION_ID>\"\n)\n\nbooking, _request_ids = nylas.scheduler.bookings.find(booking_id: \"<SCHEDULER_BOOKING_ID>\")\n\nputs booking"
},
{
"lang": "java",
"label": "Java SDK (Public)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Booking;\nimport com.nylas.models.FindBookingQueryParams;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class FindBookingPublic {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n FindBookingQueryParams queryParams = new FindBookingQueryParams.Builder()\n .configurationId(\"<SCHEDULER_CONFIG_ID>\")\n .build();\n\n Response<Booking> booking = nylas.scheduler().bookings().find(\"<BOOKING_ID>\", queryParams);\n\n System.out.println(\"Booking: \" + booking.getData());\n }\n}\n"
},
{
"lang": "java",
"label": "Java SDK (Private)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Booking;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class FindBooking {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build();\n\n Response<Booking> booking = nylas.scheduler().bookings().find(\"<BOOKING_ID>\");\n\n System.out.println(\"Booking: \" + booking.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Public)",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.FindBookingQueryParams\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val queryParams = FindBookingQueryParams.Builder()\n .configurationId(\"<SCHEDULER_CONFIG_ID>\")\n .build()\n\n val booking = nylas.scheduler().bookings().find(\"<BOOKING_ID>\", queryParams)\n\n println(\"Booking: ${booking.data}\")\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Private)",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build()\n\n val booking = nylas.scheduler().bookings().find(\"<BOOKING_ID>\")\n\n println(\"Booking: ${booking.data}\")\n}\n"
}
],
"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.\n\nNylas recommends against changing participants' email addresses while updating a booking, to avoid\nconfusion.\n\nNylas validates the provided session ID and uses it to retrieve the related\n[Configuration object](/docs/reference/api/configurations/). If you created a public\nConfiguration, you don't need to include the `Authorization` request header with a session ID, but\nyou do need to pass the Configuration object ID as a query parameter.\n\nWhen you make a `PATCH` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"start_time\": 1708714800,\n \"end_time\": 1708722000\n }'"
},
{
"lang": "bash",
"label": "cURL (Private)",
"source": "curl --compressed --request PATCH \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \\\n --header 'Content-Type: application/json' \\ \n --data '{\n \"start_time\": 1708714800,\n \"end_time\": 1708722000\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK (Public)",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function rescheduleBooking() {\n try {\n const booking = await nylas.scheduler.bookings.reschedule({\n queryParams: {\n configurationId: \"<SCHEDULER_CONFIG_ID>\",\n },\n bookingId: \"booking-id\",\n requestBody: {\n startTime: 1763292600,\n endTime: 1763294400,\n },\n });\n console.log(\"Rescheduled Booking\", booking);\n } catch (error) {\n console.error(\"Error rescheduling booking\", error);\n }\n}\n\nrescheduleBooking();\n"
},
{
"lang": "python",
"label": "Python SDK",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nbooking = nylas.scheduler.bookings.confirm(\n booking_id=\"<BOOKING_ID>\",\n request_body={\n \"salt\": \"<SALT>\",\n \"status\": \"confirmed\",\n },\n query_params={\n \"configuration_id\": \"<SCHEDULER_CONFIG_ID>\",\n },\n)\n\nprint(\"Confirmed booking:\", booking)\n"
},
{
"lang": "javascript",
"label": "Node.js SDK (Private)",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<SCHEDULER_SESSION_ID>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function rescheduleBooking() {\n try {\n const booking = await nylas.scheduler.bookings.reschedule({\n bookingId: \"booking-id\",\n requestBody: {\n startTime: 1763292600,\n endTime: 1763294400,\n },\n });\n console.log(\"Rescheduled Booking\", booking);\n } catch (error) {\n console.error(\"Error rescheduling booking\", error);\n }\n}\n\nrescheduleBooking();\n"
},
{
"lang": "ruby",
"label": "Ruby SDK (Public)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n \"start_time\": 1794828600,\n \"end_time\": 1794830400,\n}\nbooking, _request_ids = nylas.scheduler.bookings.update(booking_id: \"<BOOKING_ID>\", request_body: request_body, query_params: {\"configuration_id\": \"<CONFIGURATION_ID>\"})\n\nputs booking"
},
{
"lang": "ruby",
"label": "Ruby SDK (Private)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<SCHEDULER_SESSION_ID>\"\n)\n \nrequest_body = {\n \"start_time\": 1794828600,\n \"end_time\": 1794830400,\n}\nbooking, _request_ids = nylas.scheduler.bookings.update(booking_id: \"<BOOKING_ID>\", request_body: request_body)\n\nputs booking"
},
{
"lang": "java",
"label": "Java SDK (Public)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Booking;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.RescheduleBookingQueryParams;\nimport com.nylas.models.RescheduleBookingRequest;\nimport com.nylas.models.Response;\n\npublic class RescheduleBookingPublic {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n RescheduleBookingRequest requestBody = new RescheduleBookingRequest.Builder()\n .startTime(1763292600)\n .endTime(1763294400)\n .build();\n\n RescheduleBookingQueryParams queryParams = new RescheduleBookingQueryParams(\n \"<SCHEDULER_CONFIG_ID>\", \"<SCHEDULER_CONFIG_SLUG>\", \"<NYLAS_CLIENT_ID>\");\n\n Response<Booking> booking = nylas.scheduler().bookings().reschedule(\n \"<BOOKING_ID>\", requestBody, queryParams);\n\n System.out.println(\"Rescheduled booking: \" + booking.getData());\n }\n}\n"
},
{
"lang": "java",
"label": "Java SDK (Private)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Booking;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.RescheduleBookingRequest;\nimport com.nylas.models.Response;\n\npublic class RescheduleBooking {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build();\n\n RescheduleBookingRequest requestBody = new RescheduleBookingRequest.Builder()\n .startTime(1763292600)\n .endTime(1763294400)\n .build();\n\n Response<Booking> booking = nylas.scheduler().bookings().reschedule(\"<BOOKING_ID>\", requestBody);\n\n System.out.println(\"Rescheduled booking: \" + booking.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Public)",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.RescheduleBookingQueryParams\nimport com.nylas.models.RescheduleBookingRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val requestBody = RescheduleBookingRequest.Builder()\n .startTime(1763292600)\n .endTime(1763294400)\n .build()\n\n val queryParams = RescheduleBookingQueryParams(\n configurationId = \"<SCHEDULER_CONFIG_ID>\",\n slug = \"<SCHEDULER_CONFIG_SLUG>\",\n clientId = \"<NYLAS_CLIENT_ID>\")\n\n val booking = nylas.scheduler().bookings().reschedule(\"<BOOKING_ID>\", requestBody, queryParams)\n\n println(\"Rescheduled booking: ${booking.data}\")\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Private)",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.RescheduleBookingRequest\n\nfun main() {\n val nylas = NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build()\n\n val requestBody = RescheduleBookingRequest.Builder()\n .startTime(1763292600)\n .endTime(1763294400)\n .build()\n\n val booking = nylas.scheduler().bookings().reschedule(\"<BOOKING_ID>\", requestBody)\n\n println(\"Rescheduled booking: ${booking.data}\")\n}\n"
}
],
"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\nprovider.\n\nNylas validates the provided session ID and uses it to retrieve the related\n[Configuration object](/docs/reference/api/configurations/). If you created a public\nConfiguration, you don't need to include the `Authorization` request header with a session ID, but\nyou do need to pass the Configuration object ID as a query parameter.\n\nWhen you make a `PUT` request, Nylas replaces all data in the nested object with the information\nincluded in your request. For more information, see\n[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 \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"salt\": -zgLLAuk_qtcsw,\n \"status\": \"cancelled\",\n \"cancellation_reason\": \"I am no longer available at this time.\"\n }'"
},
{
"lang": "bash",
"label": "cURL (Private)",
"source": "curl --compressed --request PUT \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \\\n --header 'Content-Type: application/json' \\ \n --data '{\n \"salt\": -zgLLAuk_qtcsw,\n \"status\": \"cancelled\",\n \"cancellation_reason\": \"I am no longer available at this time.\"\n }'"
},
{
"lang": "javascript",
"label": "Node.js SDK (Public)",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<NYLAS_API_KEY>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function confirmBooking() {\n try {\n const booking = await nylas.scheduler.bookings.confirm({\n queryParams: {\n configurationId: \"<SCHEDULER_CONFIG_ID>\",\n },\n bookingId: \"booking-id\",\n requestBody: {\n salt: \"-zgLLAuk_qtcsw\",\n status: \"cancelled\",\n cancellationReason: \"I am no longer available at this time.\",\n },\n });\n console.log(\"Confirmed Booking\", booking);\n } catch (error) {\n console.error(\"Error confirming booking\", error);\n }\n}\n\nconfirmBooking();\n"
},
{
"lang": "javascript",
"label": "Node.js SDK (Private)",
"source": "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"<SCHEDULER_SESSION_ID>\",\n apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function confirmBooking() {\n try {\n const booking = await nylas.scheduler.bookings.confirm({\n bookingId: \"booking-id\",\n requestBody: {\n salt: \"-zgLLAuk_qtcsw\",\n status: \"cancelled\",\n cancellationReason: \"I am no longer available at this time.\",\n },\n });\n console.log(\"Confirmed Booking\", booking);\n } catch (error) {\n console.error(\"Error confirming booking\", error);\n }\n}\n\nconfirmBooking();\n"
},
{
"lang": "ruby",
"label": "Ruby SDK (Public)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n \"salt\": \"-zgLLAuk_qtcsw\",\n \"status\": \"cancelled\",\n \"cancellation_reason\": \"I am no longer available at this time.\"\n}\nbooking, _request_ids = nylas.scheduler.bookings.confirm(booking_id: \"<BOOKING_ID>\", request_body: request_body, query_params: {\"configuration_id\": \"<CONFIGURATION_ID>\"})\n\nputs booking"
},
{
"lang": "ruby",
"label": "Ruby SDK (Private)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<SCHEDULER_SESSION_ID>\"\n)\n\nrequest_body = {\n \"salt\": \"-zgLLAuk_qtcsw\",\n \"status\": \"cancelled\",\n \"cancellation_reason\": \"I am no longer available at this time.\"\n}\nbooking, _request_ids = nylas.scheduler.bookings.confirm(booking_id: \"<BOOKING_ID>\", request_body: request_body)\n\nputs booking"
},
{
"lang": "java",
"label": "Java SDK (Public)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Booking;\nimport com.nylas.models.ConfirmBookingQueryParams;\nimport com.nylas.models.ConfirmBookingRequest;\nimport com.nylas.models.ConfirmBookingStatus;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class ConfirmBookingPublic {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n ConfirmBookingRequest requestBody = new ConfirmBookingRequest.Builder()\n .salt(\"-zgLLAuk_qtcsw\")\n .status(ConfirmBookingStatus.CANCELLED)\n .cancellationReason(\"I am no longer available at this time.\")\n .build();\n\n ConfirmBookingQueryParams queryParams = new ConfirmBookingQueryParams.Builder()\n .configurationId(\"<SCHEDULER_CONFIG_ID>\")\n .build();\n\n Response<Booking> booking = nylas.scheduler().bookings().confirm(\n \"<BOOKING_ID>\", requestBody, queryParams);\n\n System.out.println(\"Confirmed booking: \" + booking.getData());\n }\n}\n"
},
{
"lang": "java",
"label": "Java SDK (Private)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.Booking;\nimport com.nylas.models.ConfirmBookingRequest;\nimport com.nylas.models.ConfirmBookingStatus;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\n\npublic class ConfirmBooking {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build();\n\n ConfirmBookingRequest requestBody = new ConfirmBookingRequest.Builder()\n .salt(\"-zgLLAuk_qtcsw\")\n .status(ConfirmBookingStatus.CANCELLED)\n .cancellationReason(\"I am no longer available at this time.\")\n .build();\n\n Response<Booking> booking = nylas.scheduler().bookings().confirm(\"<BOOKING_ID>\", requestBody);\n\n System.out.println(\"Confirmed booking: \" + booking.getData());\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Public)",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ConfirmBookingQueryParams\nimport com.nylas.models.ConfirmBookingRequest\nimport com.nylas.models.ConfirmBookingStatus\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val requestBody = ConfirmBookingRequest.Builder()\n .salt(\"-zgLLAuk_qtcsw\")\n .status(ConfirmBookingStatus.CANCELLED)\n .cancellationReason(\"I am no longer available at this time.\")\n .build()\n\n val queryParams = ConfirmBookingQueryParams.Builder()\n .configurationId(\"<SCHEDULER_CONFIG_ID>\")\n .build()\n\n val booking = nylas.scheduler().bookings().confirm(\"<BOOKING_ID>\", requestBody, queryParams)\n\n println(\"Confirmed booking: ${booking.data}\")\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Private)",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.ConfirmBookingRequest\nimport com.nylas.models.ConfirmBookingStatus\n\nfun main() {\n val nylas = NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build()\n\n val requestBody = ConfirmBookingRequest.Builder()\n .salt(\"-zgLLAuk_qtcsw\")\n .status(ConfirmBookingStatus.CANCELLED)\n .cancellationReason(\"I am no longer available at this time.\")\n .build()\n\n val booking = nylas.scheduler().bookings().confirm(\"<BOOKING_ID>\", requestBody)\n\n println(\"Confirmed booking: ${booking.data}\")\n}\n"
}
],
"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.\n\nNylas validates the provided session ID and uses it to retrieve the related\n[Configuration object](/docs/reference/api/configurations/). If you created a public\nConfiguration, you don't need to include the `Authorization` request header with a session ID, but\nyou 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 \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>?configuration_id=<SCHEDULER_CONFIG_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "bash",
"label": "cURL (Private)",
"source": "curl --compressed --request DELETE \\\n --url 'https://api.us.nylas.com/v3/scheduling/bookings/<BOOKING_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \\\n --header 'Content-Type: application/json'"
},
{
"lang": "python",
"label": "Python SDK (Private)",
"source": "from nylas import Client\n\nnylas = Client(\n \"<NYLAS_API_KEY>\",\n \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.scheduler.bookings.destroy(\n booking_id=\"<BOOKING_ID>\",\n request_body={\n \"cancellation_reason\": \"Plans changed.\",\n },\n query_params={\n \"configuration_id\": \"<SCHEDULER_CONFIG_ID>\",\n },\n)\n\nprint(\"Booking cancelled:\", response)\n"
},
{
"lang": "ruby",
"label": "Ruby SDK (Public)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<NYLAS_API_KEY>\"\n)\n\nbooking, _request_ids = nylas.scheduler.bookings.destroy(booking_id: \"<BOOKING_ID>\", query_params: {\"configuration_id\": \"<CONFIGURATION_ID>\"})\n\nputs booking"
},
{
"lang": "ruby",
"label": "Ruby SDK (Private)",
"source": "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"<SCHEDULER_SESSION_ID>\"\n)\n\nbooking, _request_ids = nylas.scheduler.bookings.destroy(booking_id: \"<BOOKING_ID>\")\n\nputs booking"
},
{
"lang": "java",
"label": "Java SDK (Public)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.DeleteResponse;\nimport com.nylas.models.DestroyBookingQueryParams;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class DeleteBookingPublic {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n DestroyBookingQueryParams queryParams = new DestroyBookingQueryParams.Builder()\n .configurationId(\"<SCHEDULER_CONFIG_ID>\")\n .build();\n\n DeleteResponse result = nylas.scheduler().bookings().destroy(\"<BOOKING_ID>\", queryParams, null);\n\n System.out.println(\"Deleted booking: \" + result);\n }\n}\n"
},
{
"lang": "java",
"label": "Java SDK (Private)",
"source": "import com.nylas.NylasClient;\nimport com.nylas.models.DeleteResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class DeleteBooking {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build();\n\n DeleteResponse result = nylas.scheduler().bookings().destroy(\"<BOOKING_ID>\", null, null);\n\n System.out.println(\"Deleted booking: \" + result);\n }\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Public)",
"source": "import com.nylas.NylasClient\nimport com.nylas.models.DestroyBookingQueryParams\n\nfun main() {\n val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n val queryParams = DestroyBookingQueryParams.Builder()\n .configurationId(\"<SCHEDULER_CONFIG_ID>\")\n .build()\n\n val result = nylas.scheduler().bookings().destroy(\"<BOOKING_ID>\", queryParams)\n\n println(\"Deleted booking: $result\")\n}\n"
},
{
"lang": "kotlin",
"label": "Kotlin SDK (Private)",
"source": "import com.nylas.NylasClient\n\nfun main() {\n val nylas = NylasClient.Builder(\"<SCHEDULER_SESSION_ID>\").build()\n\n val result = nylas.scheduler().bookings().destroy(\"<BOOKING_ID>\")\n\n println(\"Deleted booking: $result\")\n}\n"
}
],
"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 \\\n --url \"https://api.us.nylas.com/v3/scheduling/should-redirect/<V2_SCHEDULER_SLUG>\" \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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.\n\n<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>\n\nThis is the first step of the migration process, and is how you tell Nylas which v2 application you are migrating.\n\nTo 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.\n\nTo 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.\n\n```bash\n--header 'BasicV2: <base64-encoded V2_APP_ID:V2_APP_SECRET> // Use the -n flag when you Base64 encode\n```\n\nNo further request body is required. Nylas detects the v3 application ID from the API key, and the v2 application ID from the BasicV2 header.\n\nThe 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 \\\n --url 'https://api.us.nylas.com/v3/migration-tools/link-v2v3-apps' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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\nendpoint, make sure you\n[link a v2 application to a v3 application](/docs/reference/api/app-migration/migration_link_v2v3_apps/).\n\nThis endpoint imports the following v2 settings, and sets them to the corresponding v3 application\nsettings:\n\n - Your website URL.\n - Your icon URL (used to customize the Hosted OAuth page).\n - Redirect URIs for OAuth.\n - Integrations and their settings.\n - Nylas migrates Google integrations to equivalent v3 connectors.\n - If you have v2 Microsoft integrations, you should create a new Azure auth app and update the\n connector settings. For detailed instructions, see\n [Migrating Microsoft accounts](/docs/v2/upgrade-to-v3/upgrade/migrating-microsoft-accounts/).\n - Nylas migrates IMAP, iCloud, and EWS integrations to v3 connectors with auto-generated default\n values.\n\nNylas automatically detects your application ID from the API key and finds its linked v2\napplication to begin the import process.\n\nThis 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 \\\n --url 'https://api.us.nylas.com/v3/migration-tools/import-v2-app' \\\n --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\nto v3 as a test, then use the\n[Batch Clone endpoint](/docs/reference/api/app-migration/migration_snapshot_batch_clone/)\nto migrate the rest.\n\nBefore you use this endpoint, your v2 Nylas applications need to be linked to their corresponding v3\napplications and you need to have a working equivalent\n[authentication connector](/docs/reference/api/connectors-integrations/) for each provider\nyou use. If you need help with this process, [learn how to get support](/docs/support/).\n\nDuring migration, Nylas maps the v2 provider to its v3 equivalent using the connected account's\nv2 authorization type and provider. All sensitive data (such as tokens and passwords) is encrypted\nand securely transfered only within the Nylas infrastructure. No secrets exit the internal Nylas\nnetwork.\n\nThis endpoint is rate limited to 20 requests per second, per Nylas application ID.\n\n### Create placeholder grants\n\nNylas can migrate existing Microsoft Graph, Office 365, and EWS accounts that use token\nauthentication. It can't fully migrate\n[some types of Microsoft accounts](/docs/v2/upgrade-to-v3/upgrade/migrating-microsoft-accounts/#microsoft-account-import-compatibility-in-v3)\nbecause of provider limitations and scope changes in v3.\n\nBy default, Nylas creates an invalid v3 Grant with fake credentials for accounts that it can't\nautomatically migrate. These grants act as \"placeholders\" that the user can manually authenticate\nto later. You can turn this feature off for Microsoft accounts only by setting the `clone_exchange`\nquery parameter to `false`, or for all providers by setting `allow_invalid_grant_creation` to\n`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\nfor all connected accounts in your request. These grants act as placeholders that users can\nauthenticate 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\nMicrosoft accounts that can't be automatically migrated. These grants act as placeholders that\nusers 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 \\\n --url 'https://api.us.nylas.com/v3/migration-tools/grants/<account_id>/clone' \\\n --header 'Content-Type: application/json' \\\n --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.\n\nBefore you use this endpoint, your v2 Nylas applications need to be linked to their corresponding v3\napplications and you need to have a working equivalent \n[authentication connector](/docs/reference/api/connectors-integrations/) for each provider\nyou use. If you need help with this process, [learn how to get support](/docs/support/).\n\nWhen you make a batch clone request, Nylas starts two background jobs:\n\n - A snapshot job that prepares non-sensitive v2 account data for migration.\n - A batch clone job that migrates the v2 account data to v3 grants.\n\nNylas handles all data and logic for these jobs and runs them in the background to they don't block\nAPI responses.\n\nYou can filter for certain types of accounts by specifying properties in the body of your request.\nUse these options when you want to try migrating certain types of accounts in smaller batches,\nor to retry failed migrations. If you don't specify any filters, Nylas uses the default values.\n\nDuring migration, Nylas maps the v2 provider to its v3 equivalent using the connected account's\nv2 authorization type and provider. All sensitive data (such as tokens and passwords) is encrypted\nand securely transfered only within the Nylas infrastructure. No secrets exit the internal Nylas\nnetwork.\n\nThis endpoint is rate limited to 20 requests per second, per Nylas application ID.\n\n### Create placeholder grants\n\nNylas can migrate existing Microsoft Graph, Office 365, and EWS accounts that use token\nauthentication. It can't fully migrate\n[some types of Microsoft accounts](/docs/v2/upgrade-to-v3/upgrade/migrating-microsoft-accounts/#microsoft-account-import-compatibility-in-v3)\nbecause of provider limitations and scope changes in v3.\n\nBy default, Nylas creates an invalid v3 Grant with fake credentials for accounts that it can't\nautomatically migrate. These grants act as \"placeholders\" that the user can manually authenticate\nto later. You can turn this feature off for Microsoft accounts only by setting the `clone_exchange`\nquery parameter to `false`, or for all providers by setting `allow_invalid_grant_creation` to\n`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\nfor all connected accounts in your request. These grants act as placeholders that users can\nauthenticate 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\nMicrosoft accounts that can't be automatically migrated. These grants act as placeholders that\nusers 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 \\\n --url 'https://api.us.nylas.com/v3/migration-tools/snapshot-batch-clone' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"limit\": 100,\n \"providers\": [\n \"google\",\n \"imap\",\n \"graph\",\n \"ews\",\n \"icloud\"\n ],\n \"mode\": \"all\",\n \"clone_exchange\": false\n }'"
}
]
}
},
"/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.\n\nMigration 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. \n\nThere 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.\n\nJobs have a status, which can be one of the following:\n- A _pending_ job is queued and waiting to start.\n- A _running_ job is currently in progress.\n- A _partial_ job has finished, but was not able to migrate all accounts successfully.\n- A _completed_ job has finished and successfully migrated _all_ accounts.\n- A _failed_ job has finished but did not migrate any accounts.\n\nYou can optionally filter the list of jobs to return only jobs with a specific status or type.\n\nYou 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.\n\nIf you don't include any query parameters to filter the results, Nylas returns all jobs.\n\nThe 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:\n\n - `completed`: The job finished and all accounts were migrated successfully.\n - `failed`: The job finished, but no accounts were migrated.\n - `partial`: The job finished. Some accounts were migrated successfully, and some failed.\n - `pending`: The job is queued.\n - `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:\n\n 1. Jobs with `pending` status.\n 2. Jobs with `running` status.\n 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 \\\n --url 'https://api.us.nylas.com/v3/migration-tools/jobs?status=pending%2Crunning%2Cfailed%2Ccompleted&type=snapshot%2Cmigration&sort_by_completion=true' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --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.\n\nTo 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`.\n\nBy 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.\n\nResults 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. \n\nAlso, 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.\n\nThe API is rate limited to 20 requests per second per Nylas application ID.\n\n### IMAP folder resource ID\n\nWhen 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 \\\n --url 'https://api.us.nylas.com/v3/migration-tools/translate' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n --data '{\n \"resource_type\": \"messages\",\n \"v2_account_id\": \"<NYLAS_ACCOUNT_ID>\",\n \"nylas_ids\": [\n \"<NYLAS_ACCOUNT_ID>\",\n \"<NYLAS_ACCOUNT_ID>\"\n ]\n }'"
}
]
}
}
},
"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\n_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_.\nOtherwise, 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,\n`<package/bundle-name>://<deeplink>`).\n\nNylas 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,\n`<package/bundle-name>://<deeplink>`).\n\nNylas 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.\nNylas 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\nconnected 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\nuser'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\n[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\nspecified, Nylas uses the default scopes from the\n[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\ngrants 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 \n[Get Grant](/docs/reference/api/manage-grants/get_grant_by_id/) is used and set to `true`.\nApplicable only for Google and Microsoft grants.\nFor Microsoft, aliases require a Microsoft 365 / Exchange Online mailbox. Free Outlook.com\n(consumer) accounts have no aliases to expose, so this field is omitted from the response\neven 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\nback to your project without modifying it. You can use this field for verification, or to track\ninformation 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.\nInitially, 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\n[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\nAgent Accounts, Nylas may omit this field when the grant is in the application's default\nworkspace.",
"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\nto 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\nmanages. Nylas includes this field when you retrieve workspaces. For more information, see\nthe [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.\nThe 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\nworkspace. 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\nvalue 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\n[notification schemas](/docs/reference/notifications/) for details about each trigger\ntype.\n\nSee the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/),\n[Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references\nfor 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\n[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\n[notification schemas](/docs/reference/notifications/) for details about each\ntrigger type.\n\nSee the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/),\n[Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references\nfor information on how to trigger each event type.\n\nYou can test `message.created.truncated` and `message.updated.truncated` notifications using this\nendpoint. For more information, see\n[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\n[notification schemas](/docs/reference/notifications/) for details about each\ntrigger type.\n\nSee the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/),\n[Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references\nfor information on how to trigger each event type.\n\nYou can test `message.created.truncated` and `message.updated.truncated` notifications using this\nendpoint. For more information, see\n[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\nto 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\n`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\n`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\n[workspace](/docs/reference/api/workspaces/), not the policy. Set rules on the workspace instead.\nWhether 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\nbefore the message is submitted to the email provider — an `outbound` rule with a `block` action\nrejects the send with HTTP 403 and no message is delivered. Non-blocking actions (`mark_as_spam`,\n`archive`, `mark_as_read`, `mark_as_starred`, `assign_to_folder`, `trash`) on outbound rules apply\nto the stored sent copy. Inbound and outbound rules are isolated: inbound rules never run during sends, and\noutbound 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\nrequire 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\nboth triggers: `from.address` is the full sender email, `from.domain` is the domain\nportion, and `from.tld` is the top-level domain. `recipient.*` fields are valid only on\n`outbound` rules and match against **any** recipient — including To, CC, BCC, and SMTP\nenvelope recipients. For `is_not`, the condition is true only when **no** recipient\nmatches. `outbound.type` is valid only on `outbound` rules and classifies the send as\n`compose` (a fresh message) or `reply` (a reply to an existing thread). The type is\nderived as `reply` when the send includes `reply_to_message_id` or the raw MIME\ncontains `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,\n`contains` for substring matching, or `in_list` to check against one or more List\nresources. String matching is case-insensitive. The `outbound.type` field accepts only\n`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\nstring. For `in_list`, this is an array of List IDs. For `outbound.type`, this is\n`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\ncombined 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\nlevel or rejects an outbound send before provider submission. `mark_as_spam` routes the\nmessage or stored sent copy to the spam folder, `assign_to_folder` files it in the folder\nnamed 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\nname (or its full path for a nested folder, e.g. `Clients/Acme`), or a system folder name\n(`Inbox`, `Sent`, `Drafts`, `Trash`, `Junk`, `Archive`). The name is resolved when the rule\nruns, 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\noutbound send for a grant. Rule evaluations are created automatically during inbound processing and\noutbound send handling and can be listed to trace which rules matched, what input was considered,\nand 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\nevaluation happened before a message record existed, such as `smtp_rcpt`, or when an outbound\nevaluation 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\nduring SMTP RCPT TO processing (before the message was accepted) — `message_id` is `null` in\nthis case. `inbox_processing` means the evaluation ran after the message was accepted and\nduring inbox processing — `message_id` is populated. `outbound_send` means the evaluation ran\nfor an outbound send; `message_id` is populated when a sent copy was stored, and `null` when\nthe 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 —\nfields 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,\nwhen 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\nimmutable after creation. `domain` holds domain names (matched against `from.domain` or `recipient.domain`),\n`tld` holds top-level domains (matched against `from.tld` or `recipient.tld`), and `address` holds full email\naddresses (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`:\na 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.\nThe value of this field is exactly the same as the email attachment's `Content-Type` header.\nThe provider might set additional parameters, such as `name` and `charset`.\n\nNylas 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\nexample, you might see something like `<img src=\\\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\\\">` in\nthe message body.\n\nSometimes, the `content_id` value is contained in angle brackets (for example,\n`<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\n[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\nMicrosoft, 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\nis 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\nand 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\ndifferent 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\nonly. 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,\nbut 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\nset the `fields` query parameter to either `include_headers` or `include_basic_headers`.\n\n- `fields=include_headers`: Returns the full set of headers on the message.\n- `fields=include_basic_headers`: Returns only the three RFC threading headers (`Message-ID`,\n `In-Reply-To`, `References`). Use this option when you only need to track message identity and\n thread relationships — payload size is significantly smaller than `include_headers`.\n\nA single message can sometimes have multiple headers with the same key name. Nylas adds all of\nthe headers to the `headers` array without merging or de-duplicating the data. When the headers\ncontain encoded data, Nylas adds it to the `headers` array without decoding it. If you need the\ndecoded data, you need to build decoding logic into your project.\n\nSome headers might contain raw MIME information (for example,\n`=?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\n`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).\n\nTo get the raw MIME content for a message, set the `fields` query parameter to `raw_mime` in\nyour request. When you request raw MIME data, Nylas returns the `grant_id`, `object`, `id`,\nand `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\nuseful for displaying a preview of the message.",
"example": "You have been invited to the following event. Welcome! WhenThu Oct 28, 2021\n7am - 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\non 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\nthread 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\nregistered to the authenticated organization in the\n[Nylas Dashboard](https://dashboard-v3.nylas.com/organization/domains?tab=hosted-auth) and have an\nactive certificate.\n\nCustom tracking hostnames are available on select plans. Contact your Nylas account representative\nor the [Nylas Sales team](https://www.nylas.com/contact-sales/) to enable this feature for your\norganization.\n\nNylas trims surrounding whitespace, removes one trailing dot, and converts ASCII letters to\nlowercase before looking up the hostname. Provide an ASCII fully qualified hostname without a URL\nscheme, path, port, or wildcard.\n\nYou must enable `links`, `opens`, or both when you provide this field. A custom tracking hostname\ndoes not support `thread_replies` by itself. If you omit this field, Nylas uses its regional\ntracking hostname. Invalid, inactive, blocked, deleted, and unowned hostnames return the same\ngeneric `400` response. If Nylas cannot complete the explicit ownership and certificate lookup, it\nreturns 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\nDrafts folder until it's sent. For more information, see\n[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\nis 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\ndifferent 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.\n\nMicrosoft messages can be in a single folder only. Google allows a single message to appear in\nmultiple 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,\nbut 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\nset the `fields` query parameter on the send request to either `include_headers` or\n`include_basic_headers`. This is supported for **synchronous** send only — the parameter has no\neffect when you set the `send_at` field on the request.\n\n- `fields=include_headers`: Returns the full set of headers on the response.\n- `fields=include_basic_headers`: Returns only the three RFC threading headers (`Message-ID`,\n `In-Reply-To`, `References`). Use this option when you only need to track message identity and\n thread relationships — payload size is significantly smaller than `include_headers`.\n\nA single message can sometimes have multiple headers with the same key name. Nylas adds all of\nthe headers to the `headers` array without merging or de-duplicating the data. When the headers\ncontain encoded data, Nylas adds it to the `headers` array without decoding it. If you need the\ndecoded data, you need to build decoding logic into your project.\n\nSome headers might contain raw MIME information (for example,\n`=?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\nuseful for displaying a preview of the message.",
"example": "You have been invited to the following event. Welcome! WhenThu Oct 28, 2021 7am - 8am Eastern\nTime - 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\nfor 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\nthread contains only one message or many. If this is a new message, Nylas assigns a `thread_id`\nto 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.\nThe value of this field is exactly the same as the email attachment's `Content-Type` header.\nThe provider might set additional parameters, such as `name` and `charset`.\n\nNylas 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\nexample, you might see something like `<img src=\\\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\\\">` in\nthe message body.\n\nSometimes, the `content_id` value is contained in angle brackets (for example,\n`<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\nis 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\nuseful for displaying a preview of the message.",
"example": "You have been invited to the following event. Welcome! WhenThu Oct 28, 2021 7am - 8am Eastern\nTime - 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\nHTML, 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\nis 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\nTime - 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\nfor 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\nformat."
},
"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\nformat."
},
"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\nreceived 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\nExchange 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.\n\nMicrosoft messages can only be in one folder at a time. Google messages can be in multiple\nfolders.",
"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`).\nSee the\n[list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)\nfor 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\nwas 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\nthe\n[list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)\nfor 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\nthat contain sent messages (\"Sent Items\" on Microsoft, or \"SENT\" on other providers) have the\n`[\"\\\\Sent\"]` attribute. For more information, see\n[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.\n\nYou can't query for folders using attributes, but you _can_ manually filter through folders to\nfind 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\n[Google's reference documentation](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)\nfor a list of accepted values."
},
"background_color": {
"type": "string",
"description": "(Google only) The background color of the folder, in hexadecimal format (for example, `#0099EE`).\nSee\n[Google's reference documentation](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)\nfor 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.\nThe value of this field is exactly the same as the email attachment's `Content-Type` header.\nThe provider might set additional parameters, such as `name` and `charset`.\n\nNylas 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\nexample, you might see something like `<img src=\\\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\\\">` in\nthe 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\nexample, `#0099EE`). When empty, Nylas uses the default background color.\n\nYou 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`).\nWhen empty, Nylas uses the default foreground color.\n\nYou 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\ncalendars apart from calendars shared with the grant.\n\nThis 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.\n\nIf the calendar is read-only, all of its events have `read_only` set to `true`. This field _cannot_\nbe 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)\nformatted 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\n`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\nit 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\nthe meeting. This helps end recordings when meetings have concluded but participants\nhaven'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`,\n`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.\n`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`,\n`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\n`true` for these settings to take effect. Provide any combination of the fields below.\n\nThe fields fall into two independent groups:\n\n- **Language hints** (`expected_languages`, `fallback_language`) constrain automatic\n language detection. This declares the languages you expect; it does not translate\n transcripts or force the recording into a specific language.\n- **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward\n domain-specific terms such as names, acronyms, and product names.\n\nSet on individual Notetakers, on calendar sync, or on event sync. When set on a calendar,\nevents inherit the value unless the event's own request overrides it. Send `null` or `{}`\nto clear inherited settings and return to default transcription behavior.\n\nSee [Set transcription languages](/docs/v3/notetaker/#set-transcription-languages) for\nsupported language codes and validation rules.",
"properties": {
"expected_languages": {
"type": "array",
"description": "Language codes the audio is expected to contain. Optional. When provided, it must\ncontain at least one supported code and cannot be `null` or empty. When omitted,\ntranscription 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.\nWhen `expected_languages` is set, the fallback must be one of those codes. When\n`expected_languages` is omitted, transcription considers all supported languages and\nthe fallback may be any supported code. When `fallback_language` is omitted, the\ntranscriber auto-detects the language. The field is not stored, so responses do not\nreturn it.",
"example": "en"
},
"keywords": {
"type": "array",
"description": "Domain-specific terms that bias transcription toward recognizing them correctly, such\nas names, acronyms, and product names. Optional. Up to 200 terms; each term must be\n1 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\ntranscribed 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.\n- \"all\": Join all events with meeting links.\n- \"external\": Join all events where the host's domain differs from any participant's domain.\n- \"internal\": Join all events where the host's domain matches all participants' domains.\n- \"own_events\": Join all events where the user is the host.\n- \"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\nparticipants. If you don't specify any settings, a Notetaker joins meetings regardless of\nparticipants.",
"properties": {
"participants_gte": {
"type": "integer",
"description": "Join all events where the number of participants is greater than or equal to the specified\nvalue.",
"example": 5
},
"participants_lte": {
"type": "integer",
"description": "Join all events where the number of participants is less than or equal to the specified\nvalue.",
"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,\nif an account has a meeting scheduled from 10:00–11:00a.m., and you set a `before` buffer of\n30 minutes, Nylas treats 9:30–11:00a.m. as busy.\n\nThis 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\nan account has a meeting scheduled from 10:00–11:00a.m., and you set an `after` buffer of 15\nminutes, Nylas treats 10:00–11:15a.m. as busy.\n\nThis 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\nSaturday 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.\n\nThe 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\naccount has a meeting scheduled from 10:00–11:00a.m., and you set a buffer of 30 minutes, Nylas\ntreats 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\nindividual 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.\nThis is used for both max-fairness and max-availability calculations.\n\nTo calculate participant order correctly, set the metadata key `key5` to the same value on any\nevents you want to consider for the current set of round-robin participants. You can set this\nkey to any value that helps you identify events used to calculate availability in this group\n(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.\nThis 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\nthe 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\nassess the specified account's free/busy schedule.\n\nFor Google and EWS accounts, Nylas can query a timespan of up to 3 months from the `start_time`.\n\nFor 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\nyour request, Nylas returns the real calendar ID instead of `primary`.\n\nFor Microsoft calendars, there are some cases where the event Nylas returns isn't associated with\na calendar ID. This happens most often when the event is created in a shared calendar.\n\nThis 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\nEvent `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.\n\nAfter the conferencing provider creates the meeting, Nylas returns the concrete meeting\ninformation — such as the URL and meeting code — in the `details` object and appends it to\nthe event `description`. For an autocreated conference, expect the response `conferencing`\nobject 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\n[iCalendar format](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.4.7).\nRecurring events might share the same ID.\n\nCan 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. \n\nFor an event in a Google calendar, Nylas returns the `email` based on the calender type.\n- For a primary calendar, `email` is the same as the `calendar_id`.\n- 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\nincluded 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\nthe connected calendar, and you can't modify it.\n\nIn cases where you _can_ update this field on a cloned event (for example, an event imported to your\ncalendar from an email invitation), `read_only` is `true`.\n\nIf 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\nsettings.",
"properties": {
"use_default": {
"type": [
"boolean",
"null"
],
"description": "When `true`, the event uses the calendar's default reminder settings.\nThis field may be `null` if reminders are not explicitly configured.\n\n- **Google**: Generates a `popup`-style reminder 10 minutes before the event begins.\n- **Microsoft**: Generates a reminder 15 minutes before the event begins.\n- **iCloud**: Does not generate a reminder.\n- **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\nor omitted, and `use_default` is `false`, the event does not send reminders. If `true`, Nylas\ngenerates both the default event reminder and any reminders in the `overrides` list.\n\nYou cannot set reminder overrides if `use_default` is `true`.\n\nFor Microsoft Graph, EWS, and iCloud, you can set only one reminder per event.\n\nThis field may be `null` if no reminder overrides have been set. Treat `null` the same as an\nempty 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\noptions and default settings for each provider.\n\n- **Google**:\n - Default: `popup`\n - Options: `popup`, `email`\n- **iCloud**:\n - Default: `display`\n - 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\n(master) event. See [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5) for more details.\nYou can use [this tool](https://jkbrzt.github.io/rrule/) to learn more about the `RRULE` spec.\n\nEvents inherit their timezone from the `when` object. Nylas recommends that you use the `when`\nobject to specify the event's start and end time.\n\nProvider specifics:\n- On some providers, `EXDATE` might not include exception or cancelled event timestamps. When this\nhappens, Nylas represents those event instances as separate objects in its responses.\n- Virtual calendars don't support `DTSTART` or `TZID`.\n- iCloud accounts do _not_ support changing an event from recurring to non-recurring. You can create,\nupdate, or delete information on recurring events.\n- 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\nan event. If you're the organizer of the event and you want to reply \"maybe\" or \"no\" to the\ninvitation, use the\n[Send RSVP endpoint](/docs/reference/api/events/send-rsvp/)\ninstead.\n\nFor Google events, a `cancelled` status indicates that the event was an occurrence of a recurring\nevent, and that the occurrence has been cancelled by the event organizer.\n\nFor Microsoft and EWS events, a `cancelled` status indicates that the event was organized by someone\nelse, 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\ndefined, Nylas uses the account's default provider settings. For Google and Microsoft, event visibility is `public` by default.\n\nThe `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.\n\nFor 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\n[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.\n\nIf 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\n[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.\n\nIf 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\nor 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\n(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\nsub-objects: `timespan`, `date`, or `datespan`. These sub-objects allow Nylas to capture and represent\nspecific points in time.\n\n`timespan` objects include optional timezone support.\n\nThis field may be `null` when event timing data is unavailable (for example, when using field selection\nthat 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\ncalled \"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\nas an HTML string, depending on how the provider formats it.\nFor 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,\nthis 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\nevent. If the parent event belongs to a different calendar that you don't have access to, or it's\nbeen 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\nformat. 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\ncalled \"transparency\" in some systems. This field may be `null` if not explicitly set. Treat `null`\nthe 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.\n\nYou can't use `autocreate` and `details` in the same request. If you do, Nylas returns an error.\n\nNylas stores conference information in the event description. To remove conference details, set\n`conferencing` to `{}` and remove the corresponding conference information from the description in\nthe 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\nfor the event and appends the conferencing details to the event description.\n\nIf the `provider` is `Zoom Meeting`, your Zoom OAuth app must include the following\n[granular scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-granular/)\nfor Nylas to manage meetings on behalf of the user:\n\n- `meeting:write:meeting` — required to **create** Zoom meetings.\n- `meeting:update:meeting` — required to **update** Zoom meetings (for example, when event time or title changes).\n- `meeting:delete:meeting` — required to **delete** Zoom meetings (when events are removed).\n\nIf any of these scopes are missing, the Zoom API rejects the request. After adding scopes\nto your Zoom app, affected users must re-authenticate their grant so their access tokens\ninclude 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\ngrant acts as the conference host: they join the conference at the scheduled time and\nadmit other participants during the meeting.\n\nInclude `conf_grant_id` when the conferencing `provider` isn't available on the user's\nown account — for example, when the `provider` is `Google Meet` but the user\nauthenticated with a Microsoft account (cross-provider autocreation). When the\n`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\nconference. For `Zoom Meeting`, each key is sent as a top-level parameter to\n[Zoom's Create a Meeting API](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/#operation/meetingCreate)\n— for example, `agenda`, `password`, or Zoom's own `settings` object. Nylas does _not_\nvalidate these values. They can make your Zoom integration more accessible but\npotentially 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\none 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\nan HTML string, depending on how the provider formats it.\n\nFor 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.\nFor 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.\n\n- **Google**: Generates a `popup`-style reminder 10 minutes before the event begins.\n- **Microsoft**: Generates a reminder 15 minutes before the event begins.\n- **iCloud**: Does not generate a reminder.\n- **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\nor omitted, and `use_default` is `false`, the event does not send reminders. If `true`, Nylas\ngenerates both the default event reminder and any reminders in the `overrides` list.\n\nYou cannot set reminder overrides if `use_default` is `true`.\n\nFor 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\noptions and default settings for each provider.\n\n- **Google**:\n - Default: `popup`\n - Options: `popup`, `email`\n- **iCloud**:\n - Default: `display`\n - 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\n[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string. If\npopulated, 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.\n\nYou can format `when` as one of four sub-objects: `time`, `timespan`, `date`, or `datespan`. These\nsub-objects allow you to capture and represent specific points in time.\n\n`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\nnumber of email addresses.\n- IMAP/iCloud/Yahoo: at most one email address per contact.\n- 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\nlimits on the number of IM addresses.\n- IMAP/iCloud/Yahoo: at most one IM address per contact.\n- 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\non the number of phone numbers.\n- IMAP/iCloud/Yahoo: at most one phone number per contact.\n- Microsoft: at most two home phone numbers, two work phone numbers, and one mobile phone number.\n- EWS: at most two home phone numbers, two work phone numbers, one mobile phone number, and one\n other phone number.",
"properties": {
"number": {
"type": "string",
"description": "The contact's phone number, including its\n[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\nsupported 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\nlimits on the number of physical addresses.\n- IMAP/iCloud/Yahoo: at most one physical address per contact.\n- 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 \nparsed from a message. If the contact is created or updated using the Nylas API, its source is \n`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\nyou don't specify a time, Notetaker joins the meeting immediately.\n\nIf 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`\nevents. The value depends on the current `state`:\n\nWhen `state` is `connecting`: `waiting_for_entry`.\nWhen `state` is `attending`: `recording_active`.\nWhen `state` is `disconnected`: `meeting_ended`, `kicked`, `no_activity`, `no_participants`, `api_request`, `network_error`, `cancelled`, `unknown`.\nWhen `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`.\nWhen `state` is `worker_finished`: `worker_finished`.\n",
"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`\nevents. The value depends on the current `state`:\n\nWhen `state` is `connecting`: `waiting_for_entry`.\nWhen `state` is `attending`: `recording_active`.\nWhen `state` is `disconnected`: `meeting_ended`, `kicked`, `no_activity`, `no_participants`, `api_request`, `network_error`, `cancelled`, `unknown`.\nWhen `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`.\nWhen `state` is `worker_finished`: `worker_finished`.\n",
"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\nconfigured 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\nat 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\nworkflow 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\na message.",
"example": 5
},
"grant_id": {
"type": [
"string",
"null"
],
"description": "The ID of the grant associated with the workflow. Returned only if the workflow is\nconfigured 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.\n\nFor 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`.\n\nFor `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\nmeetings, the `availability_method` is always `collective`.\n\nThe round-robin methods, `max-fairness` and `max-availability`, don't support\n[Agent Account](/docs/v3/scheduler/agent-accounts/) participants. Use connected grants for\nround-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.\nThese are merged with participant-specific entries, with participant entries taking precedence\nfor 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).\nUse \"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\").\nRequired when using default_specific_time_availability to ensure proper timezone conversion\nacross 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`\nand their individual `specific_time_availability` entries. Regular `open_hours` and `default_open_hours`\nare completely ignored.\n\nThis is useful for:\n- Temporary availability windows (e.g., hiring events, special booking periods)\n- Disabling all availability by setting to `true` with no specific dates defined\n\n**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\n[standard booking flow](/docs/v3/scheduler/customize-booking-flows/).\n\nIf set to `organizer-confirmation`, Scheduler creates an event marked \"Pending\" in the organizer's\ncalendar and sends a confirmation request email to the organizer. The confirmation request email\nincludes 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\nrescheduled. 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\nevent is created, updated, or deleted. Microsoft grants ignore this flag and\nalways notify participants. This field may be `null` if not explicitly set on\nthe 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\nan [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\nused to check the participant's availability.\n\nFor an [Agent Account](/docs/v3/scheduler/agent-accounts/) participant, set this to\n`[\"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.\n\nFor an [Agent Account](/docs/v3/scheduler/agent-accounts/) participant, set this to\n`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.\nUse \"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).\nUse \"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\").\nOptional 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.\n\nIf the participant provides an `availability` or `booking` block, this email address must be\nassociated with a valid Nylas grant, or the request fails. Participants supplied by email only\n(no `availability` or `booking` block) don't require a grant. They're treated as notification-only\ninvitees: they still receive scheduling emails, but they don't affect availability or free-busy\ncalculation 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.\n\nFor non-round-robin meetings, one of the participants must be specified as the organizer. For\nround-robin meetings, remove the `is_organizer` key/value pair or set `is_organizer` to `false`\nfor 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\n`specific_time_availability` entries. Their regular `open_hours` are ignored.\n\nIf the config-level `availability_rules.only_specific_time_availability` is `true`,\nthis participant-level setting cannot override it to `false`.\n\nSetting to `true` with an empty `specific_time_availability` array results in\nzero 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\n[IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string. Nylas uses this when\ncalculating the participant's open hours, and in email notifications.\n\nIf a participant `open_hours` block includes its own `timezone`, the open-hours timezone\noverrides this participant timezone for that block. If participant `open_hours` doesn't include\na `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. \n\n- For the `metadata` type, this field stores the default metadata value.\n- 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\nNylas 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\nmessages."
},
"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.\nWhen enabled, Notetaker joins the meeting to record, transcribe, and optionally generate\nsummaries 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.\nThe 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\nmeeting will be recorded.",
"default": true,
"example": true
},
"notetaker_name": {
"type": "string",
"description": "The display name for the Notetaker bot that joins the meeting.\nMaximum 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\nmay 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.\n\nParticipants that provide availability (through an `availability` or `booking` block) must be\nassociated with a valid Nylas grant, or the request fails. Participants supplied by email only\ndon't require a grant. They're notification-only invitees who receive scheduling emails but don't\naffect availability calculation and can't be selected as a round-robin host.\n\nThis field isn't accepted for group or round-robin configurations, which are anchored to the\norganizer'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\n[Bookings](/docs/reference/api/bookings/) endpoints require a valid session ID to\nauthenticate requests using the specified Configuration. This field may be `null`\nif not explicitly set on the configuration; treat `null` the same as `false`\n(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\nslug instead of the `configuration_id` when making requests to the Nylas Scheduling endpoints.\nSlugs 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\n[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\ncalendars.",
"example": "primary"
},
"disable_emails": {
"type": [
"boolean",
"null"
],
"description": "When `true`, Nylas doesn't send email notifications when an event is booked, cancelled, or\nrescheduled. 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\n[Bookings](/docs/reference/api/bookings/) endpoints require a valid session ID to\nauthenticate requests using the specified Configuration. This field may be `null`\nif not explicitly set on the configuration; treat `null` the same as `false`\n(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\nslug instead of the `configuration_id` when making requests to the Nylas Scheduling endpoints.\nSlugs 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\n[Group Events endpoints](/docs/reference/api/group-events/) and functionality.\nDefaults 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\none 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\n(master) event. See [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5) for more details.\nYou can use [this tool](https://jkbrzt.github.io/rrule/) to learn more about the `RRULE` spec.\n\nEvents inherit their timezone from the `when` object. Nylas recommends that you use the `when`\nobject to specify the event's start and end time.\n\nProvider specifics:\n - Virtual calendars don't support `DTSTART` or `TZID`.\n - iCloud accounts do _not_ support recurring events for group events\n - 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\ndescription as an HTML string, depending on how the provider formats it.\n\nFor 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\nroom).",
"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\nthe [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.\n\n- **Pending**: The job has been created, but not started. Batch clone runs only after the linked\nsnapshot job is completed.\n- **Running**: The job is currently running.\n- **Completed**: The job has successfully finished all migrations.\n- **Failed**: _All_ migrations failed.\n- **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.\n\nTo request Gmail's \"labels\", include `folders`. (Nylas v3 consolidates folders and labels into\none 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\ntype 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\n[Markdown](https://en.wikipedia.org/wiki/Markdown). Can't be `false` when `html_as_markdown`\nis `true`.",
"example": true,
"default": true
},
"ignore_tables": {
"type": "boolean",
"description": "If `true`, removes table-related tags (`<table>`, `<th>`, `<td>`, `<tr>`) from the message\nwhile 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\n[Markdown](https://en.wikipedia.org/wiki/Markdown). Can't be `true` when\n`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\n[Working with email attachments](/docs/v3/email/attachments/#attachment-schemas-and-size-limits)\nfor more information.",
"example": "YXR0YWNoDQoNCi0tLS0tLS0tLS0gRm9yd2FyZGVkIG1lc3NhZ2UgL="
},
"content_disposition": {
"type": "string",
"description": "(Not supported for Microsoft and EWS) The content disposition of the file. Usually,\nthis 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\nmessage body. To avoid unexpected behavior in threads, make sure to use unique CIDs\nacross messages of a thread.",
"example": "ce9b9547-9eeb-43b2-ac4e-58768bdf04e4"
},
"content_type": {
"type": "string",
"description": "The\n[MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)\nof the file. This is used by the email client to determine how to display the\nattachment.",
"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\ngrant'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\nmessage ID on the provider. For IMAP Send, this is the\n[RFC822](https://datatracker.ietf.org/doc/html/rfc822#section-4.6.1) `Message-ID` header\nof 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\nat least one minute in the future from the time you make your request. You can schedule\na message to be sent up to 30 days in the future. If the request includes\n`tracking_options.domain_name`, Nylas validates the hostname when it creates the schedule\nand 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\ndefined 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\ntemplate.",
"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\n[message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the\nmessage. Nylas generates a\n[`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications)\nwhen a participant first opens the message.",
"default": false
},
"thread_replies": {
"type": "boolean",
"description": "When `true`, enables\n[thread replied tracking](/docs/v3/email/message-tracking/#thread-replied-tracking)\non the message. Nylas generates a\n[`thread.replied` webhook notification](/docs/reference/notifications/#thread-replied-notifications)\nwhen a participant replies to the thread.",
"default": false
},
"links": {
"type": "boolean",
"description": "When `true`, enables\n[link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the\nmessage. Nylas generates a\n[`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications)\nwhen 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\nenabled.",
"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\nuntil 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\ninserts the signature after a line break at the end of the body, including after any quoted\ntext 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\nthe 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.\nMust be at least one minute in the future from the time you make your request. You can\nschedule a message to be sent up to 30 days in the future. If the request includes\n`tracking_options.domain_name`, Nylas validates the hostname when it creates the schedule\nand 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\ndefined 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\ntemplate.",
"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\n[message open tracking](/docs/v3/email/message-tracking/#message-open-tracking) on the\nmessage. Nylas generates a\n[`message.opened` webhook notification](/docs/reference/notifications/#message-opened-notifications)\nwhen a participant first opens the message.",
"default": false
},
"thread_replies": {
"type": "boolean",
"description": "When `true`, enables\n[thread replied tracking](/docs/v3/email/message-tracking/#thread-replied-tracking)\non the message. Nylas generates a\n[`thread.replied` webhook notification](/docs/reference/notifications/#thread-replied-notifications)\nwhen a participant replies to the thread.",
"default": false
},
"links": {
"type": "boolean",
"description": "When `true`, enables\n[link clicked tracking](/docs/v3/email/message-tracking/#link-clicked-tracking) on the\nmessage. Nylas generates a\n[`message.link_clicked` webhook notification](/docs/reference/notifications/#link-clicked-notifications)\nwhen 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\nenabled.",
"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\nuntil 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\ninserts the signature after a line break at the end of the body, including after any quoted\ntext 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\n(base64 inline images are not supported). Nylas sanitizes the HTML on input to prevent\nmalicious 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\nURLs (base64 inline images are not supported). Nylas sanitizes the HTML on input to prevent\nmalicious 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\n`application/json` or `multipart/form-data` schema, depending on the size of the\nattachment.\n\nThe `application/json` schema is limited to 3MB, including the message body. The `content`\nmust be Base64-encoded.\n\nThe `multipart/form-data` schema is limited by the provider to 25MB. See the\n[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\nusing `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)\nof the attachment, used by the email client to determine how to display the\nattachment. 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\nHTML. For example, you might see something like\n`<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.\nUsually, 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\n`from` header. By default, Nylas uses the email address associated with the `grant_id`.\n\nNylas 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\nused to set an alternative `Reply-To` header in the sent message. Not all providers support\nsetting 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\ndefined 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\ntemplate.",
"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\ninserts the signature after a line break at the end of the body. Only one signature can be\nused 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\nis used to set an alternative `Reply-To` header in the sent message. Not all providers\nsupport 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\ndefined 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\ntemplate.",
"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\ninserts the signature after a line break at the end of the body. Only one signature can\nbe 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\nHTML. For example, you might see something like\n`<img src=\\\"cid:ce9b9547-9eeb-43b2-ac4e-58768bdf04e4\\\">` in the message body. Only\ninclude 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\nused to set an alternative `Reply-To` header in the sent message. Not all providers support\nsetting 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\ndefined 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\ntemplate.",
"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\nis used to set an alternative `Reply-To` header in the sent message. Not all providers\nsupport 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\ndefined 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\ntemplate.",
"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\nfolders 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.\n\nMicrosoft 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.\nMicrosoft, 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.\n- IMAP/iCloud/Yahoo: at most one web page per contact.\n- 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\nmeeting immediately.\n\nIf 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\nin 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\ntemplate.",
"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\ndefined 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\ntemplate.",
"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\nsending 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/).\nIf 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\nsending 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/).\nIf 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\nmanually.",
"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\ndescription 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\nroom).",
"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\nmanually.",
"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\ndescription 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\nroom).",
"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\ndefault 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`\nfor 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\none 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\ncapacity 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\nexchange."
},
"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\ngenerate 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\n[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for\ndetails.",
"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\n[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for\ndetails.",
"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\n[notification schemas](/docs/reference/notifications/) for details about\neach trigger type.\n\nSee the [Grants](/docs/reference/api/manage-grants/),\n[Calendar](/docs/reference/api/calendar/), [Events](/docs/reference/api/events/), and\n[Messages](/docs/reference/api/messages/) references for information on how to trigger\neach 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\n[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for\ndetails.",
"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\n[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for\ndetails.",
"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\n[Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for\ndetails.",
"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\nMarkdown-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,\n\nI 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!\n\nBest regards,\n[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\n[Return Attachment Metadata endpoint](/docs/reference/api/attachments/get-attachments-id/)\nto 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\nspecified 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\nan 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\na description of the error."
},
"object": {
"type": "string",
"description": "The object type. If the request succeeds, the value is `free_busy`. If the request\nfails, 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,\nNylas returns an error message in this field. The event is still updated, but the\nICS 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\ntimestamp 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\nbetween `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\ntimestamp 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\nbetween `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\ntimestamp 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\nbetween `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\ntimestamp 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\nbetween `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\ntimestamp 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\nbetween `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\nan account has a meeting scheduled from 10:00–11:00a.m., and you\nset an after buffer of 15 minutes, Nylas treats 10:00–11:15a.m. as\nbusy.",
"example": 15
},
"before": {
"type": "integer",
"description": "The amount of buffer time to add before meetings. For example, if\nan account has a meeting scheduled from 10:00–11:00a.m., and you\nset a before buffer of 30 minutes, Nylas treats 9:30–11:00a.m. as\nbusy.",
"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,\nif a time slot starts at 9:05a.m. and `round_to` is set to 15, Nylas rounds\nit 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,\ncancelled, 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\nwhen the event is created, updated, or deleted. Microsoft grants ignore\nthis flag and always notify participants. This field may be `null` if not\nexplicitly 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\n[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\nsearches 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\nto. 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\nhours, 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\n[IANA-formatted](https://en.wikipedia.org/wiki/Tz_database)\nstring. Nylas uses this when calculating the participant's open\nhours 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\nsession ID to authenticate requests using the Configuration. This field may be\n`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.\nFields 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\nevents.",
"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\nbooking. This field may be `null` if not explicitly set; treat `null` the\nsame as `60`.",
"example": 30
},
"min_cancellation_notice": {
"type": "integer",
"description": "The minimum amount of time before a meeting that the booking can still be\ncancelled, in minutes.",
"example": 30
}
}
},
"slug": {
"type": [
"string",
"null"
],
"description": "The Configuration slug. You can use this instead of the `configuration_id`\nwhen making requests to other Scheduling endpoints. This field may be `null`\nif 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,\ncancelled, 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\nsession ID to authenticate requests using the Configuration. This field may be\n`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\nevents.",
"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\nbooking. This field may be `null` if not explicitly set; treat `null` the\nsame as `60`.",
"example": 30
},
"min_cancellation_notice": {
"type": "integer",
"description": "The minimum amount of time before a meeting that the booking can still be\ncancelled, in minutes.",
"example": 30
}
}
},
"slug": {
"type": [
"string",
"null"
],
"description": "The group Configuration slug. You can use this instead of the `configuration_id`\nwhen making requests to other Scheduling endpoints. This field may be `null`\nif no slug has been set.",
"example": "xyz-en"
},
"type": {
"type": "string",
"description": "The booking type for the Scheduling Page. For group Configurations, this is\nalways `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\nan account has a meeting scheduled from 10:00–11:00a.m., and you\nset an after buffer of 15 minutes, Nylas treats 10:00–11:15a.m. as\nbusy.",
"example": 15
},
"before": {
"type": "integer",
"description": "The amount of buffer time to add before meetings. For example, if\nan account has a meeting scheduled from 10:00–11:00a.m., and you\nset a before buffer of 30 minutes, Nylas treats 9:30–11:00a.m. as\nbusy.",
"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,\nif a time slot starts at 9:05a.m. and `round_to` is set to 15, Nylas rounds\nit 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,\ncancelled, 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\nwhen the event is created, updated, or deleted. Microsoft grants ignore\nthis flag and always notify participants. This field may be `null` if not\nexplicitly 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\n[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\nsearches 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\nto. 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\nhours, 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\n[IANA-formatted](https://en.wikipedia.org/wiki/Tz_database)\nstring. Nylas uses this when calculating the participant's open\nhours 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\nsession ID to authenticate requests using the Configuration. This field may be\n`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.\nFields 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\nevents.",
"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\nbooking. This field may be `null` if not explicitly set; treat `null` the\nsame as `60`.",
"example": 30
},
"min_cancellation_notice": {
"type": "integer",
"description": "The minimum amount of time before a meeting that the booking can still be\ncancelled, in minutes.",
"example": 30
}
}
},
"slug": {
"type": [
"string",
"null"
],
"description": "The Configuration slug. You can use this instead of the `configuration_id`\nwhen making requests to other Scheduling endpoints. This field may be `null`\nif 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,\ncancelled, 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\nsession ID to authenticate requests using the Configuration. This field may be\n`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\nevents.",
"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\nbooking. This field may be `null` if not explicitly set; treat `null` the\nsame as `60`.",
"example": 30
},
"min_cancellation_notice": {
"type": "integer",
"description": "The minimum amount of time before a meeting that the booking can still be\ncancelled, in minutes.",
"example": 30
}
}
},
"slug": {
"type": [
"string",
"null"
],
"description": "The group Configuration slug. You can use this instead of the `configuration_id`\nwhen making requests to other Scheduling endpoints. This field may be `null`\nif no slug has been set.",
"example": "xyz-en"
},
"type": {
"type": "string",
"description": "The booking type for the Scheduling Page. For group Configurations, this is\nalways `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)\nfor 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\nassociated 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\n`next_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more\ninformation."
},
"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\nNylas database. You also need to set the `in` query parameter in your request so Nylas knows which\nfolder 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,\n`select=id,updated_at`). This allows you to receive only the portion of object data that you're\ninterested in. You can use `select` to optimize response size and reduce latency by limiting queries\nto 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.\nRequired when using `shared_from`.\nThis parameter only accepts a single folder ID.\nCheck 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.\nIt also accepts grant ID.\nThis parameter only accepts single email address or grant ID.\nCheck 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/`\nto 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\nthe 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\nfolder. This operation is irreversible.\n\nTo use this query parameter, you need to turn on \"Enable hard delete\" in the\n[Nylas Dashboard](https://dashboard-v3.nylas.com/?utm_source=docs&utm_content=docs-hard-delete) under\n**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\nparameter 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.\n\n(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\nyou filter for events that end at 5:00p.m., and the calendar includes an event that runs from\n4:30–5:30p.m., Nylas returns that event.\n\nDefaults to one month from the time you make the request.\n\nThe `end` value cannot be earlier than `start`. For iCloud accounts, the difference between `start`\nand `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\nmultiple times to select or exclude multiple event types. For example,\n`event_type=default&event_type=outOfOffice` returns all events that are default or `OOO`, and excludes\nany events that are `focusTime` or that have a `workingLocation`.\n\nIf you don't specify an event type, Nylas uses `default` to filter for regular events that don't have\nanother 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\n[Import Events endpoint](/docs/reference/api/events/import-events/)\ninstead**.\n\nWhen `true`, Nylas returns all recurring events within the specified time range, including individual\noccurrences of the recurring event. Otherwise, Nylas only returns the parent event and any event\noverrides (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\nfilters 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`.\n\n`master_event_id` is _not_ respected by metadata filtering.\n\nWhen using `master_event_id` to fetch recurring events with a Google grant, the order of the results will not be sorted chronologically.\nInstead, Nylas returns the unchanged occurrences first, followed by the modified occurrences.\nFor example, if you have a recurring event with the following occurrences:\n- 2025-01-01\n- 2025-01-02\n- 2025-01-03\n\nBut you modify the time of the second occurrence to 2025-01-02, the results will be:\n- 2025-01-01\n- 2025-01-03\n- 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`.\n\nDifferent providers have different semantics for cancelled events:\n\n- **Google**: An event is considered cancelled after a user deletes it from their calendar, until\nit's eventually hard-deleted and is no longer readable.\n- **Microsoft**: An event is considered cancelled if the user is invited to an event and the\norganizer deletes it. The cancelled version of the event stays on the participants' calendars until\nthey 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\nyou filter for events that start at 9:00a.m., and the calendar includes an event that runs from\n8:30–9:30a.m., Nylas returns that event.\n\nDefaults to the time that you make the request.\n\nThe `start` value cannot be later than `end`. For iCloud accounts, the difference between `start`\nand `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,\nin seconds using the Unix timestamp format.\n\n`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,\nin seconds using the Unix timestamp format.\n\n`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.\n\nMicrosoft 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\nof events Nylas returns might be lower than this limit, even if other events match your query\nparameters."
},
"calendar_id_no_validate": {
"name": "calendar_id",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "The calendar ID of the event.\n\nFor Microsoft, we do not validate whether the given calendar ID matches the real calendar ID of the event.\nThis is due to a limitation of the Microsoft Graph API.\n\n(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)\nfor 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\ntimestamp 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\ntimestamp 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\n`prev_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more\ninformation."
},
"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,\nif you filter for events that start at 9:00a.m. and the calendar includes an event that runs from\n8: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,\nif you filter for events that end at 5:00p.m. and the calendar includes an event that runs from\n4:30–5:30p.m., Nylas returns that event."
},
"account_id": {
"name": "account_id",
"required": true,
"in": "path",
"schema": {
"type": "string"
},
"example": "df0yq6c9okc6t9j4ejd5nyrt7"
}
}
}
}![\"Run](\"https://run.pstmn.io/button.svg\")
](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=)\n\n## Enable compression to optimize performance\n\nThe 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.\n\nCompression 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/).\n\n## Query parameters\n\nNylas 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/).\n\nThe table below shows the query parameters you can use for the `GET` requests in the Email, Calendar, Contacts, and Notetaker APIs.\n\n| Endpoint | Query parameters |\n| :------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [`GET /v3/grants/