Skip to content
Skip to main content
POST
https://api.us.nylas.com/v3/grants/{grant_id}/events/batch

Create, update, and delete events in a batch

Creates, updates, and deletes up to 50 events in one request. Only Google and Microsoft grants are supported.

Each operation in operations uses the same body as the Create an event or Update an event request, and returns the same event or error that the single-event request returns. The query parameters apply to every operation.

The response is 200 when every operation succeeds and 207 when one or more fail. Nylas doesn't roll back the operations that succeeded. data[i] is always the result of operations[i].

Request rules

Nylas returns a 400 error and runs none of the operations when a request breaks one of these rules:

  • operations has 1 to 50 items.
  • A create operation has a body. An update operation has an event_id and a body. A delete operation has an event_id.
  • An event_id appears in only one operation.
  • An event_id doesn't contain /, ?, #, %, \, whitespace, or control characters, and isn't made up only of dots.
  • (Google only) A recurring series and one of its occurrences aren't in the same request. Several occurrences of the same series are allowed.
  • (Microsoft only) notify_participants isn't false.

Retry failed operations

Retry only the operations that failed, and check each result before you retry it:

  • provider_event_created: true means the provider created the event before a later step failed. Don't retry the operation, because a retry creates a duplicate event.
  • A 429 or 503 result with a message that starts with Not attempted means Nylas didn't send the operation to the provider. It's safe to retry. Wait retry_after seconds first when the result includes it.
  • Any other 429 result means the provider rate-limited the operation and didn't run it. Retry it with exponential backoff. Google often doesn't return retry_after.

When the provider rate-limits an operation, Nylas doesn't send the operations that haven't started. Nylas also doesn't start an operation when fewer than 10 seconds of the 90-second request timeout remain.

Response time

A batch of 50 operations can take up to about a minute, and updates take longest. Set your HTTP client's timeout above 90 seconds. If the connection drops before you get a response, some operations might already have run, so check the calendar before you send the batch again.

Provider rate limits

Each operation counts against the provider's rate limits in the same way as a single-event request. A batch reduces the number of requests you make to Nylas. It doesn't reduce the provider quota you use.

Works with an API key, an access token (use /v3/grants/me/ in place of the grant ID), or an IAM API key with the events.create, events.update, and events.delete permissions.

Parameters

Path parameters

grant_id*string

ID of the grant to access. Use /me/ to refer to the grant associated with an access token.

Query parameters

calendar_id*string

The ID of the calendar that every operation in the request applies to. You can use primary for the user's primary calendar.

selectstring

Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at). This allows you to receive only the portion of object data that you're interested in. You can use select to optimize response size and reduce latency by limiting queries to only the information that you need.

notify_participantsboolean

When true, the provider emails participants about each change. Set to false to make the changes without notifying participants.

Microsoft returns a 400 error for notify_participants=false, and Nylas runs none of the operations.

Default: true
tentative_as_busyboolean

(Microsoft and EWS only) When true, Nylas treats tentative events as busy.

Default: true

Request body

operations*array<object>

The operations to run. Nylas returns one result for each operation, in the same order.

minItems: 1maxItems: 50

Responses

request_idstring

The request ID.

dataarray<object>

One result for each operation, in the same order as operations in the request.

POSThttps://api.us.nylas.com/v3/grants/{grant_id}/events/batch?notify_participants=true&tentative_as_busy=true

Find your API key in the Nylas Dashboard under API Keys in your application settings.

grant_idrequiredstring

ID of the grant to access. Use /me/ to refer to the grant associated with an access token.

calendar_idrequiredstring

The ID of the calendar that every operation in the request applies to. You can use primary for the user's primary calendar.

selectstring

Specify fields that you want Nylas to return, as a comma-separated list (for example, select=id,updated_at). This allows you to receive only the portion of object data that you're interested in. You can use select to optimize response size and reduce latency by limiting queries to only the information that you need.

notify_participantsboolean

When true, the provider emails participants about each change. Set to false to make the changes without notifying participants. Microsoft returns a 400 error for notify_participants=false, and Nylas runs none of the operations.

tentative_as_busyboolean

(Microsoft and EWS only) When true, Nylas treats tentative events as busy.

Loading editor...

Autocomplete and validation come from this endpoint's request schema.