Reducing response sizes with field selection

Field selection is available for Full platform and Contract plans.

Nylas supports field selection, which allows you to choose which fields are returned in API responses and notifications. Instead of sending all available fields, Nylas sends only the data you specify. This helps protect sensitive information, improves performance, and prevents timeouts and rate limiting.

You can implement field selection at any of the following levels:

• Application level for API responses: Applies to all responses to Messages or Events requests.
• Application level for webhook notifications: Applies to all Message or Event webhook notifications.
• Request level: Applies to the request in which you define the select query parameter.

If you use both application-level and request-level field selection for a request, Nylas returns the intersection of your selections. This means you receive only the fields specified at both the application and request level.

Enable application-level field selection for responses

Contact the Nylas Sales team to enable field selection for your application. After we configure your settings, Nylas starts returning only the specified fields for the affected endpoints.

Enable application-level field selection for webhooks

1. Log in to the Nylas Dashboard.
2. Select Customizations in the left navigation.
3. Toggle either Email message field selection for notifications or Calendar event field selection for notifications on.
4. Select the fields you want to include in Nylas’ responses.
5. Save your changes.

After you save your field selection settings, Nylas starts sending *.transformed notifications for the affected trigger types. For more information, see Using webhooks with Nylas.

Enable request-level field selection

You can specify the fields you want Nylas to return for individual API requests by including the select query parameter.

Get all Messages requestGet all Events request

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?limit=5&select=id,subject,from,to" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>&select=id,title,when,location' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'