Field selection

You can choose which fields are returned in API responses and webhook notifications using field selection.

What is field selection?

Field selection lets you specify which fields you want to receive in API responses and webhook notifications. Instead of receiving all available fields, you can choose to receive only the specific data your application needs. This helps protect sensitive data, improve performance, and reduce response sizes to prevent timeouts and rate limiting.

Nylas supports field selection at three levels:

• Application level for API responses: Configure once. Applies to all API calls.
• Application level for webhook notifications: Configure once. Applies to all webhook notifications.
• Per API request: Specify fields for individual API calls.

Why use field selection?

Privacy and security

Field selection helps protect sensitive information by excluding fields that contain private data such as:

• Event descriptions with meeting details
• Meeting URLs in event locations
• Email message bodies
• Attachment file names
• Personal contact information

Performance optimization

Smaller API responses provide several benefits:

• Faster API calls: less data to transfer and process.
• Reduced timeouts: smaller payloads are less likely to timeout.
• Lower rate limiting: reduced bandwidth usage helps avoid rate limits.
• Improved webhook performance: faster webhook processing and delivery.

Application-level field selection

Webhook notifications

To enable field selection for webhook notifications across your entire application:

1. Log in to the Nylas Dashboard.
2. Click the Customizations tab.
3. Click Add.
4. Select the fields.
5. Click Save.

Once enabled, all webhook notifications contain only the fields you selected.

API responses

To enable field selection for API responses across your entire application, contact the Nylas sales team. Once enabled, all API responses contain only the fields you selected.

Per-request field selection

You can specify fields for individual API requests using the select query parameter. Any invalid fields will be ignored, and the API response contains only the valid fields you specified.

The following example shows a request using the select query parameter:

# Get only specific event fields
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/{grant_id}/events?select=id,title,when,location' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

# Get only specific message fields
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/{grant_id}/messages?select=id,subject,from,to' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Using both application-level and per-request field selection

When you have application-level field selection enabled and also pass the select query parameter, Nylas will return the intersection of both selections. This means you’ll only receive fields that are selected at both the application-level and the per-request level. This provides an additional layer of control, allowing you to further restrict fields on a per-request basis.

Supported endpoints

Application-level field selection

The application-level field selection is currently available for:

• Calendar events: controls which event fields are returned.
• Email messages: controls which message fields are returned.

Per-request field selection (select parameter)

The per-request field selection is available for the following endpoint categories:

• Calendar endpoints
• Event endpoints
• Draft endpoints
• Message endpoints
• Thread endpoints
• Folder endpoints
• Attachment endpoints
• Contact endpoints