# Create, update, and delete events in a batch

> **POST** `https://api.us.nylas.com/v3/grants/{grant_id}/events/batch`

Source: https://developer.nylas.com/docs/reference/api/events/batch-events/

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](/docs/reference/api/events/create-event/) or
[Update an event](/docs/reference/api/events/put-events-id/) 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.

**Authentication:** Works with an API key, an [access token](/docs/v3/auth/hosted-oauth-accesstoken/) (use `/v3/grants/me/` in place of the grant ID), or an [IAM API key](/docs/v3/auth/nylas-iam/) with the `events.create`, `events.update`, and `events.delete` permissions.

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `calendar_id` | string | Yes | The ID of the calendar that every operation in the request applies to. You can use `primary` for the user's primary calendar. |
| `select` | string | No | 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_participants` | boolean, default: `true` | No | 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_busy` | boolean, default: `true` | No | (Microsoft and EWS only) When `true`, Nylas treats tentative events as busy. |

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `grant_id` | string | Yes | ID of the grant to access. Use `/me/` to refer to the grant associated with an access token. |

## Request body

Content-Type: application/json

- `operations` (array, minItems: 1, maxItems: 50) **(required)** - The operations to run. Nylas returns one result for each operation, in the same order.
  - `method` (string, one of: `create`, `update`, `delete`) **(required)** - The operation to run.
  - `event_id` (string) - The ID of the event to update or delete. Required for `update` and `delete`. Nylas
ignores it for `create`. An `event_id` can appear in only one operation, and can't
contain `/`, `?`, `#`, `%`, `\`, whitespace, or control characters.
  - `body` (object) - The event to create, or the fields to update. Required for `create` and `update`.
It takes the same fields as the request body of
[Create an event](/docs/reference/api/events/create-event/) for `create`, and of
[Update an event](/docs/reference/api/events/put-events-id/) for `update`.

## Responses

### 200 - Every operation succeeded.

- `request_id` (string) - The request ID.
- `data` (array) - One result for each operation, in the same order as `operations` in the request.
  - `status` (integer) **(required)** - The HTTP status code for this operation. It's the status the single-event request would
return.
  - `data` (object) - The event that the operation created or updated. Not returned for a `delete` operation or
a failed operation.
    - `busy` (boolean) - If `true`, shows the event's time block as `busy` on shared or public calendars. This may be
called "transparency" in some systems.
    - `calendar_id` (string, nullable) - The calendar ID associated with the event. If you used the `calendar_id=primary` query parameter in
your request, Nylas returns the real calendar ID instead of `primary`.

For Microsoft calendars, there are some cases where the event Nylas returns isn't associated with
a calendar ID. This happens most often when the event is created in a shared calendar.

This field may be `null` for certain event types (for example, virtual calendar events). It's always populated for Agent Account events.
    - `conferencing` (object) - An object that contains event conferencing details. Nylas appends the conference information to the
Event `description`.
      - `provider` (string, one of: `Google Meet`, `GoToMeeting`, `Microsoft Teams`, `Teams for Business`, `Skype for Business`, `Skype for Consumer`, `WebEx`, `Zoom Meeting`, `unknown`)
      - `details` (object) - An object that contains the conferencing details. Nylas returns the same set of fields for every
`provider`, and populates only the fields that the provider supplies:

- Google Meet: `url`, `meeting_code`, `phone`, `pin`.
- Zoom Meeting: `url`, `meeting_code`, `password`, `phone`.
- Microsoft Teams: `url`.
- WebEx: `url`, `password`, `pin`, `phone`.
- GoToMeeting: `url`, `meeting_code`, `password`, `phone`.
        - `url` (string) - The URL for the conference.
        - `meeting_code` (string) - A unique ID associated with the conference (Google Meet, Zoom Meeting, GoToMeeting).
        - `password` (string) - The password for the conference, if applicable (Zoom Meeting, WebEx, GoToMeeting).
        - `pin` (string) - The PIN for the conference, if applicable (Google Meet, WebEx).
        - `phone` (array) - The phone numbers associated with the conference (Google Meet, Zoom Meeting, WebEx, GoToMeeting).
      - `autocreate` (object) - The autocreate settings Nylas used to generate the conference for the event.

After the conferencing provider creates the meeting, Nylas returns the concrete meeting
information — such as the URL and meeting code — in the `details` object and appends it to
the event `description`. For an autocreated conference, expect the response `conferencing`
object to contain a `provider` and a `details` object once the meeting exists.
    - `created_at` (integer, nullable) - When the event was created, in seconds using the Unix timestamp format.
    - `description` (string, nullable, minLength: 0) - A brief description of the event (for example, its agenda). The description might be returned
as an HTML string, depending on how the provider formats it.
For Google accounts, this field accepts a maximum of 8,192 characters.
    - `text_description` (string, nullable, minLength: 0) - A brief text description of the event (for example, its agenda). If the description is HTML-formatted,
this field will contain the text version of the description.
    - `hide_participants` (boolean) - (Not supported for iCloud or EWS events) When `true`, hides the event's list of participants.
    - `grant_id` (string) - The ID of grant for the connected user.
    - `html_link` (string) - (Not supported for EWS events) A link to the event on the provider.
    - `ical_uid` (string, nullable) - A unique ID that you can use to identify events across calendaring systems, in
[iCalendar format](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.4.7).
Recurring events might share the same ID.

Can be `null` for events synced before the year 2020.
    - `id` (string, minLength: 1) - 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.
    - `is_owner` (boolean) - (Agent Accounts only) If `true`, the Agent Account grant can act as the organizer of this event.
If `false`, the event's organizer is someone the grant can't act as, such as the sender of an
invitation, or the event has no organizer.

Nylas sets `is_owner` on every event it returns for an Agent Account grant, and ignores the field
in create and update requests. It isn't included in webhook notifications. `is_owner` doesn't
change which edit, RSVP, and delete rules apply to the event.
    - `location` (string, nullable) - The location of the event (for example, a physical address or the name of a meeting room).
    - `master_event_id` (string, nullable) - If the event is an instance of a recurring event series, this field lists the ID of the parent
event. If the parent event belongs to a different calendar that you don't have access to, or it's
been deleted or cancelled, you can't retrieve it using this ID.
    - `metadata` (object) - The metadata associated with the object. For more information, see
[Metadata](/docs/reference/api/#metadata).
    - `object` (string) - The type of object.
    - `organizer` (object) - An object that contains information about an event's organizer.
      - `name` (string) - The organizer's full name.
      - `email` (string) - The organizer's email address. 

For an event in a Google calendar, Nylas returns the `email` based on the calender type.
- For a primary calendar, `email` is the same as the `calendar_id`.
- For a non-primary calendar, `email` is set to the actual ID of the calendar.
    - `participants` (array, minItems: 1) - An array of participants invited to the event. The organizer doesn't need to be explicitly
included in this list.
      - `comment` (string) - A note or comment about the participant (for example, their nickname).
      - `email` (string) - The participant's email address. For Microsoft Graph, this field can be missing.
      - `name` (string) - The participant's name.
      - `phone_number` (string) - The participant's phone number.
      - `status` (string, one of: `yes`, `no`, `maybe`, `noreply`, default: `"noreply"`) - The participant's RSVP status.
    - `resources` (array) - An array of room resource bookings added to the event.
      - `email` (string) **(required)** - The resource's email address.
      - `name` (string) - The resource's full name.
    - `read_only` (boolean) - If `true`, indicates that the event is read-only. The provider sets the `read_only` value based on
the connected calendar, and you can't modify it.

In cases where you _can_ update this field on a cloned event (for example, an event imported to your
calendar from an email invitation), `read_only` is `true`.

If the calendar is read-only, all events on the calendar have `read_only` set to `true`.
    - `reminders` (object) - A list of reminders to generate for the event. If not defined, Nylas uses the provider's default
settings.
      - `use_default` (boolean, nullable) - When `true`, the event uses the calendar's default reminder settings.
This field may be `null` if reminders are not explicitly configured.

- **Google**: Generates a `popup`-style reminder 10 minutes before the event begins.
- **Microsoft**: Generates a reminder 15 minutes before the event begins.
- **iCloud**: Does not generate a reminder.
- **EWS**: Generates a `display`-style reminder 15 minutes before the event begins.
      - `overrides` (array, nullable) - A list of reminders for the event to use when `use_default` is `false`. If this field is empty
or omitted, and `use_default` is `false`, the event does not send reminders. If `true`, Nylas
generates both the default event reminder and any reminders in the `overrides` list.

You cannot set reminder overrides if `use_default` is `true`.

For Microsoft Graph, EWS, and iCloud, you can set only one reminder per event.

This field may be `null` if no reminder overrides have been set. Treat `null` the same as an
empty array.
        - `reminder_minutes` (integer) - The number of minutes before the event to display a reminder.
        - `reminder_method` (string, one of: `popup`, `email`, `display`, `sound`) - (Google and iCloud only) The method used to notify the user about the event, with separate
options and default settings for each provider.

- **Google**:
  - Default: `popup`
  - Options: `popup`, `email`
- **iCloud**:
  - Default: `display`
  - Options: `display`, `sound`
    - `recurrence` (array) - An array of `RRULE` and `EXDATE` strings. Nylas includes this field only if the event is the main
(master) event. See [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5) for more details.
You can use [this tool](https://jkbrzt.github.io/rrule/) to learn more about the `RRULE` spec.

Events inherit their timezone from the `when` object. Nylas recommends that you use the `when`
object to specify the event's start and end time.

Provider specifics:
- On some providers, `EXDATE` might not include exception or cancelled event timestamps. When this
happens, Nylas represents those event instances as separate objects in its responses.
- Agent Accounts and virtual calendars don't support `DTSTART` or `TZID`. Nylas uses the event's `when` values as the start of the series instead.
- iCloud accounts do _not_ support changing an event from recurring to non-recurring. You can create,
update, or delete information on recurring events.
- Microsoft Graph adds one day to the `UNTIL` date.
    - `status` (string, one of: `confirmed`, `cancelled`, `maybe`) - (Not supported for iCloud) The status of the event. You can't set this field when creating or updating
an event. If you're the organizer of the event and you want to reply "maybe" or "no" to the
invitation, use the
[Send RSVP endpoint](/docs/reference/api/events/send-rsvp/)
instead.

For Google events, a `cancelled` status indicates that the event was an occurrence of a recurring
event, and that the occurrence has been cancelled by the event organizer.

For Microsoft and EWS events, a `cancelled` status indicates that the event was organized by someone
else, and the organizer cancelled or deleted the event.
    - `title` (string, minLength: 1, maxLength: 1024) - The name of the event.
    - `updated_at` (integer, nullable) - When the event was last updated, in seconds using the Unix timestamp format.
    - `visibility` (string, nullable, one of: `default`, `private`, `public`) - (Not supported for iCloud events) Specifies whether the event is `public` or `private`. If not
defined, Nylas uses the account's default provider settings. For Google and Microsoft, event visibility is `public` by default.

The `default` enum value is only valid for Google events, where it defers to the calendar's own sharing settings. Microsoft and EWS events only support `public` and `private`; sending `default` for these providers returns a 400 error.

For Agent Account and virtual calendar events, you can explicitly set `visibility` to `private` or `public` on create and update requests, and the value is returned on read. If not set, virtual calendar events default to `public` behavior.
    - `when` (object, nullable) - An object that represents the time and duration of an event. Nylas might format `when` as one of three
sub-objects: `timespan`, `date`, or `datespan`. These sub-objects allow Nylas to capture and represent
specific points in time.

`timespan` objects include optional timezone support.

This field may be `null` when event timing data is unavailable (for example, when using field selection
that excludes the underlying time fields).
    - `original_start_time` (integer) - (Not supported for virtual calendars, but supported for Agent Accounts) The original start time of the event, in seconds using the Unix timestamp
format. This field is present only if the event is an instance of a recurring event.
    - `notetaker` (object)
      - `id` (string) - The Notetaker bot ID. Read-only; returned in responses but not required in create or update requests.
      - `meeting_settings` (object) - A collection of settings for the Notetaker bot.
        - `action_items` (boolean, default: `true`) - When `true`, Notetaker generates a list of action items from the meeting. If `action_items` is
`true`, `video_recording`, `audio_recording`, and `transcription` must also be `true`.
        - `action_items_settings` (object)
          - `custom_instructions` (string) - A custom prompt to pass to Nylas' AI model and specify settings for the list of action items
it generates. `action_items` must be `true` to use this field.
        - `audio_recording` (boolean, default: `true`) - When `true`, Notetaker records the meeting's audio.
        - `leave_after_silence_seconds` (integer, min: 10, max: 3600, default: `300`) - The number of seconds of silence after which the Notetaker bot automatically leaves
the meeting. This helps end recordings when meetings have concluded but participants
haven't disconnected the call. Must be between 10 and 3600 seconds (1 hour).
        - `summary` (boolean, default: `true`) - When `true`, Notetaker generates a summary of the meeting. If `summary` is `true`,
`video_recording`, `audio_recording`, and `transcription` must also be `true`.
        - `summary_settings` (object)
          - `custom_instructions` (string) - A custom prompt to pass to Nylas' AI model and specify settings for the summary it generates.
`summary` must be `true` to use this field.
        - `transcription` (boolean, default: `true`) - When `true`, Notetaker transcribes the meeting's audio. If `transcription` is `true`,
`video_recording` and `audio_recording` must also be `true`.
        - `video_recording` (boolean, default: `true`) - When `true`, Notetaker records the meeting's video.
        - `transcription_settings` (object, nullable) - Optional settings that tune how Notetaker transcribes audio. `transcription` must be
`true` for these settings to take effect. Provide any combination of the fields below.

The fields fall into two independent groups:

- **Language hints** (`expected_languages`, `fallback_language`) constrain automatic
  language detection. This declares the languages you expect; it does not translate
  transcripts or force the recording into a specific language.
- **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward
  domain-specific terms such as names, acronyms, and product names.

Set on individual Notetakers, on calendar sync, or on event sync. When set on a calendar,
events inherit the value unless the event's own request overrides it. Send `null` or `{}`
to clear inherited settings and return to default transcription behavior.

See [Set transcription languages](/docs/v3/notetaker/transcription-settings/) for
supported language codes and validation rules.
          - `expected_languages` (array, minItems: 1) - Language codes the audio is expected to contain. Optional. When provided, it must
contain at least one supported code and cannot be `null` or empty. When omitted,
transcription considers all supported languages.
          - `fallback_language` (string) - Language to use if Notetaker does not detect one of the `expected_languages`. Optional.
When `expected_languages` is set, the fallback must be one of those codes. When
`expected_languages` is omitted, transcription considers all supported languages and
the fallback may be any supported code. When `fallback_language` is omitted, the
transcriber auto-detects the language. The field is not stored, so responses do not
return it.
          - `keywords` (array, maxItems: 200) - Domain-specific terms that bias transcription toward recognizing them correctly, such
as names, acronyms, and product names. Optional. All terms together can contain up
to 200 words, and each term can contain up to 6 words. Words are separated by spaces,
so `Nylas` uses 1 word and `Jane Doe` uses 2. Each term must also be 1 to 200
characters and cannot contain control characters. Cannot be `null`.
          - `use_speaker_names_as_keywords` (boolean) - When `true`, Notetaker adds known speaker names to the keyword set so they are
transcribed accurately. Optional. Cannot be `null`.
        - `messages` (object) - Custom announcements the Notetaker bot posts to the meeting chat. Use this to
greet attendees when the bot joins, or to acknowledge new participants as they
arrive. Messages are optional; when omitted, the bot only posts the default
recording-and-transcription notice described in [Using Nylas Notetaker](/docs/v3/notetaker/).

Like other `notetaker_settings` fields, `messages` participates in the
configuration hierarchy and uses whole-object override semantics: the most
specific layer that sets `messages` completely replaces the parent's value
(there is no per-message merging). See [Custom announcements](/docs/v3/notetaker/custom-announcements/)
for the full inheritance model.
          - `on_join` (array, maxItems: 10) - Messages the bot sends shortly after it joins the meeting. Each message has
its own configurable delay measured from the moment the bot joins. Up to
10 messages per trigger.
            - `type` (string, one of: `text`) **(required)** - The message format. Currently only `text` is supported. Plain-text content
is preferred; any HTML tags in `content` are stripped before the message
is sent.
            - `content` (string, minLength: 1, maxLength: 1000) **(required)** - The message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
`content` becomes empty after sanitization are rejected with a validation
error.
            - `send_after_ms` (integer, min: 1, max: 600000) **(required)** - Delay in milliseconds between the moment the bot joins the meeting and
the moment this message is posted. Each `on_join` message is scheduled
independently against its own delay; messages are posted in the order
their delays expire.
          - `on_participant_join` (array, maxItems: 10) - Messages the bot sends when a new participant joins the meeting. Each message
uses a trailing debounce window — if another participant joins before the
window expires, the timer resets and only one message is posted per burst of
joins. Up to 10 messages per trigger.
            - `type` (string, one of: `text`) **(required)** - The message format. Currently only `text` is supported. Plain-text content
is preferred; any HTML tags in `content` are stripped before the message
is sent.
            - `content` (string, minLength: 1, maxLength: 1000) **(required)** - The message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
`content` becomes empty after sanitization are rejected with a validation
error.
            - `debounce_ms` (integer, min: 1, max: 600000) **(required)** - Trailing debounce window in milliseconds. When a participant joins, the
bot waits this long before posting the message. If another participant
joins inside the window, the timer resets — the message is only posted
once the window expires without another join event. This collapses a
burst of nearly-simultaneous joins into a single announcement.
      - `name` (string, default: `"Nylas Notetaker"`) - The display name for the Notetaker bot.
  - `error` (object) - The error for a failed operation. Not returned for a successful operation.
    - `type` (string) - The error type.
    - `message` (string) - The error message.
    - `provider_error` (object) - The error from the provider.
  - `retry_after` (number) - The number of seconds to wait before you retry the operation. Returned only on a failed
operation, when the provider rate-limited the request and gave a wait time. Can be `0`.
  - `provider_event_created` (boolean) - Returned as `true` only on a failed `create` operation, when the provider created the event
before a later step failed. Don't retry the operation, because a retry creates a duplicate
event.

### 207 - One or more operations failed. Nylas returns `207` even when every operation fails. Check the
`status` of each result.

- `request_id` (string) - The request ID.
- `data` (array) - One result for each operation, in the same order as `operations` in the request.
  - `status` (integer) **(required)** - The HTTP status code for this operation. It's the status the single-event request would
return.
  - `data` (object) - The event that the operation created or updated. Not returned for a `delete` operation or
a failed operation.
    - `busy` (boolean) - If `true`, shows the event's time block as `busy` on shared or public calendars. This may be
called "transparency" in some systems.
    - `calendar_id` (string, nullable) - The calendar ID associated with the event. If you used the `calendar_id=primary` query parameter in
your request, Nylas returns the real calendar ID instead of `primary`.

For Microsoft calendars, there are some cases where the event Nylas returns isn't associated with
a calendar ID. This happens most often when the event is created in a shared calendar.

This field may be `null` for certain event types (for example, virtual calendar events). It's always populated for Agent Account events.
    - `conferencing` (object) - An object that contains event conferencing details. Nylas appends the conference information to the
Event `description`.
      - `provider` (string, one of: `Google Meet`, `GoToMeeting`, `Microsoft Teams`, `Teams for Business`, `Skype for Business`, `Skype for Consumer`, `WebEx`, `Zoom Meeting`, `unknown`)
      - `details` (object) - An object that contains the conferencing details. Nylas returns the same set of fields for every
`provider`, and populates only the fields that the provider supplies:

- Google Meet: `url`, `meeting_code`, `phone`, `pin`.
- Zoom Meeting: `url`, `meeting_code`, `password`, `phone`.
- Microsoft Teams: `url`.
- WebEx: `url`, `password`, `pin`, `phone`.
- GoToMeeting: `url`, `meeting_code`, `password`, `phone`.
        - `url` (string) - The URL for the conference.
        - `meeting_code` (string) - A unique ID associated with the conference (Google Meet, Zoom Meeting, GoToMeeting).
        - `password` (string) - The password for the conference, if applicable (Zoom Meeting, WebEx, GoToMeeting).
        - `pin` (string) - The PIN for the conference, if applicable (Google Meet, WebEx).
        - `phone` (array) - The phone numbers associated with the conference (Google Meet, Zoom Meeting, WebEx, GoToMeeting).
      - `autocreate` (object) - The autocreate settings Nylas used to generate the conference for the event.

After the conferencing provider creates the meeting, Nylas returns the concrete meeting
information — such as the URL and meeting code — in the `details` object and appends it to
the event `description`. For an autocreated conference, expect the response `conferencing`
object to contain a `provider` and a `details` object once the meeting exists.
    - `created_at` (integer, nullable) - When the event was created, in seconds using the Unix timestamp format.
    - `description` (string, nullable, minLength: 0) - A brief description of the event (for example, its agenda). The description might be returned
as an HTML string, depending on how the provider formats it.
For Google accounts, this field accepts a maximum of 8,192 characters.
    - `text_description` (string, nullable, minLength: 0) - A brief text description of the event (for example, its agenda). If the description is HTML-formatted,
this field will contain the text version of the description.
    - `hide_participants` (boolean) - (Not supported for iCloud or EWS events) When `true`, hides the event's list of participants.
    - `grant_id` (string) - The ID of grant for the connected user.
    - `html_link` (string) - (Not supported for EWS events) A link to the event on the provider.
    - `ical_uid` (string, nullable) - A unique ID that you can use to identify events across calendaring systems, in
[iCalendar format](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.4.7).
Recurring events might share the same ID.

Can be `null` for events synced before the year 2020.
    - `id` (string, minLength: 1) - 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.
    - `is_owner` (boolean) - (Agent Accounts only) If `true`, the Agent Account grant can act as the organizer of this event.
If `false`, the event's organizer is someone the grant can't act as, such as the sender of an
invitation, or the event has no organizer.

Nylas sets `is_owner` on every event it returns for an Agent Account grant, and ignores the field
in create and update requests. It isn't included in webhook notifications. `is_owner` doesn't
change which edit, RSVP, and delete rules apply to the event.
    - `location` (string, nullable) - The location of the event (for example, a physical address or the name of a meeting room).
    - `master_event_id` (string, nullable) - If the event is an instance of a recurring event series, this field lists the ID of the parent
event. If the parent event belongs to a different calendar that you don't have access to, or it's
been deleted or cancelled, you can't retrieve it using this ID.
    - `metadata` (object) - The metadata associated with the object. For more information, see
[Metadata](/docs/reference/api/#metadata).
    - `object` (string) - The type of object.
    - `organizer` (object) - An object that contains information about an event's organizer.
      - `name` (string) - The organizer's full name.
      - `email` (string) - The organizer's email address. 

For an event in a Google calendar, Nylas returns the `email` based on the calender type.
- For a primary calendar, `email` is the same as the `calendar_id`.
- For a non-primary calendar, `email` is set to the actual ID of the calendar.
    - `participants` (array, minItems: 1) - An array of participants invited to the event. The organizer doesn't need to be explicitly
included in this list.
      - `comment` (string) - A note or comment about the participant (for example, their nickname).
      - `email` (string) - The participant's email address. For Microsoft Graph, this field can be missing.
      - `name` (string) - The participant's name.
      - `phone_number` (string) - The participant's phone number.
      - `status` (string, one of: `yes`, `no`, `maybe`, `noreply`, default: `"noreply"`) - The participant's RSVP status.
    - `resources` (array) - An array of room resource bookings added to the event.
      - `email` (string) **(required)** - The resource's email address.
      - `name` (string) - The resource's full name.
    - `read_only` (boolean) - If `true`, indicates that the event is read-only. The provider sets the `read_only` value based on
the connected calendar, and you can't modify it.

In cases where you _can_ update this field on a cloned event (for example, an event imported to your
calendar from an email invitation), `read_only` is `true`.

If the calendar is read-only, all events on the calendar have `read_only` set to `true`.
    - `reminders` (object) - A list of reminders to generate for the event. If not defined, Nylas uses the provider's default
settings.
      - `use_default` (boolean, nullable) - When `true`, the event uses the calendar's default reminder settings.
This field may be `null` if reminders are not explicitly configured.

- **Google**: Generates a `popup`-style reminder 10 minutes before the event begins.
- **Microsoft**: Generates a reminder 15 minutes before the event begins.
- **iCloud**: Does not generate a reminder.
- **EWS**: Generates a `display`-style reminder 15 minutes before the event begins.
      - `overrides` (array, nullable) - A list of reminders for the event to use when `use_default` is `false`. If this field is empty
or omitted, and `use_default` is `false`, the event does not send reminders. If `true`, Nylas
generates both the default event reminder and any reminders in the `overrides` list.

You cannot set reminder overrides if `use_default` is `true`.

For Microsoft Graph, EWS, and iCloud, you can set only one reminder per event.

This field may be `null` if no reminder overrides have been set. Treat `null` the same as an
empty array.
        - `reminder_minutes` (integer) - The number of minutes before the event to display a reminder.
        - `reminder_method` (string, one of: `popup`, `email`, `display`, `sound`) - (Google and iCloud only) The method used to notify the user about the event, with separate
options and default settings for each provider.

- **Google**:
  - Default: `popup`
  - Options: `popup`, `email`
- **iCloud**:
  - Default: `display`
  - Options: `display`, `sound`
    - `recurrence` (array) - An array of `RRULE` and `EXDATE` strings. Nylas includes this field only if the event is the main
(master) event. See [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5) for more details.
You can use [this tool](https://jkbrzt.github.io/rrule/) to learn more about the `RRULE` spec.

Events inherit their timezone from the `when` object. Nylas recommends that you use the `when`
object to specify the event's start and end time.

Provider specifics:
- On some providers, `EXDATE` might not include exception or cancelled event timestamps. When this
happens, Nylas represents those event instances as separate objects in its responses.
- Agent Accounts and virtual calendars don't support `DTSTART` or `TZID`. Nylas uses the event's `when` values as the start of the series instead.
- iCloud accounts do _not_ support changing an event from recurring to non-recurring. You can create,
update, or delete information on recurring events.
- Microsoft Graph adds one day to the `UNTIL` date.
    - `status` (string, one of: `confirmed`, `cancelled`, `maybe`) - (Not supported for iCloud) The status of the event. You can't set this field when creating or updating
an event. If you're the organizer of the event and you want to reply "maybe" or "no" to the
invitation, use the
[Send RSVP endpoint](/docs/reference/api/events/send-rsvp/)
instead.

For Google events, a `cancelled` status indicates that the event was an occurrence of a recurring
event, and that the occurrence has been cancelled by the event organizer.

For Microsoft and EWS events, a `cancelled` status indicates that the event was organized by someone
else, and the organizer cancelled or deleted the event.
    - `title` (string, minLength: 1, maxLength: 1024) - The name of the event.
    - `updated_at` (integer, nullable) - When the event was last updated, in seconds using the Unix timestamp format.
    - `visibility` (string, nullable, one of: `default`, `private`, `public`) - (Not supported for iCloud events) Specifies whether the event is `public` or `private`. If not
defined, Nylas uses the account's default provider settings. For Google and Microsoft, event visibility is `public` by default.

The `default` enum value is only valid for Google events, where it defers to the calendar's own sharing settings. Microsoft and EWS events only support `public` and `private`; sending `default` for these providers returns a 400 error.

For Agent Account and virtual calendar events, you can explicitly set `visibility` to `private` or `public` on create and update requests, and the value is returned on read. If not set, virtual calendar events default to `public` behavior.
    - `when` (object, nullable) - An object that represents the time and duration of an event. Nylas might format `when` as one of three
sub-objects: `timespan`, `date`, or `datespan`. These sub-objects allow Nylas to capture and represent
specific points in time.

`timespan` objects include optional timezone support.

This field may be `null` when event timing data is unavailable (for example, when using field selection
that excludes the underlying time fields).
    - `original_start_time` (integer) - (Not supported for virtual calendars, but supported for Agent Accounts) The original start time of the event, in seconds using the Unix timestamp
format. This field is present only if the event is an instance of a recurring event.
    - `notetaker` (object)
      - `id` (string) - The Notetaker bot ID. Read-only; returned in responses but not required in create or update requests.
      - `meeting_settings` (object) - A collection of settings for the Notetaker bot.
        - `action_items` (boolean, default: `true`) - When `true`, Notetaker generates a list of action items from the meeting. If `action_items` is
`true`, `video_recording`, `audio_recording`, and `transcription` must also be `true`.
        - `action_items_settings` (object)
          - `custom_instructions` (string) - A custom prompt to pass to Nylas' AI model and specify settings for the list of action items
it generates. `action_items` must be `true` to use this field.
        - `audio_recording` (boolean, default: `true`) - When `true`, Notetaker records the meeting's audio.
        - `leave_after_silence_seconds` (integer, min: 10, max: 3600, default: `300`) - The number of seconds of silence after which the Notetaker bot automatically leaves
the meeting. This helps end recordings when meetings have concluded but participants
haven't disconnected the call. Must be between 10 and 3600 seconds (1 hour).
        - `summary` (boolean, default: `true`) - When `true`, Notetaker generates a summary of the meeting. If `summary` is `true`,
`video_recording`, `audio_recording`, and `transcription` must also be `true`.
        - `summary_settings` (object)
          - `custom_instructions` (string) - A custom prompt to pass to Nylas' AI model and specify settings for the summary it generates.
`summary` must be `true` to use this field.
        - `transcription` (boolean, default: `true`) - When `true`, Notetaker transcribes the meeting's audio. If `transcription` is `true`,
`video_recording` and `audio_recording` must also be `true`.
        - `video_recording` (boolean, default: `true`) - When `true`, Notetaker records the meeting's video.
        - `transcription_settings` (object, nullable) - Optional settings that tune how Notetaker transcribes audio. `transcription` must be
`true` for these settings to take effect. Provide any combination of the fields below.

The fields fall into two independent groups:

- **Language hints** (`expected_languages`, `fallback_language`) constrain automatic
  language detection. This declares the languages you expect; it does not translate
  transcripts or force the recording into a specific language.
- **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward
  domain-specific terms such as names, acronyms, and product names.

Set on individual Notetakers, on calendar sync, or on event sync. When set on a calendar,
events inherit the value unless the event's own request overrides it. Send `null` or `{}`
to clear inherited settings and return to default transcription behavior.

See [Set transcription languages](/docs/v3/notetaker/transcription-settings/) for
supported language codes and validation rules.
          - `expected_languages` (array, minItems: 1) - Language codes the audio is expected to contain. Optional. When provided, it must
contain at least one supported code and cannot be `null` or empty. When omitted,
transcription considers all supported languages.
          - `fallback_language` (string) - Language to use if Notetaker does not detect one of the `expected_languages`. Optional.
When `expected_languages` is set, the fallback must be one of those codes. When
`expected_languages` is omitted, transcription considers all supported languages and
the fallback may be any supported code. When `fallback_language` is omitted, the
transcriber auto-detects the language. The field is not stored, so responses do not
return it.
          - `keywords` (array, maxItems: 200) - Domain-specific terms that bias transcription toward recognizing them correctly, such
as names, acronyms, and product names. Optional. All terms together can contain up
to 200 words, and each term can contain up to 6 words. Words are separated by spaces,
so `Nylas` uses 1 word and `Jane Doe` uses 2. Each term must also be 1 to 200
characters and cannot contain control characters. Cannot be `null`.
          - `use_speaker_names_as_keywords` (boolean) - When `true`, Notetaker adds known speaker names to the keyword set so they are
transcribed accurately. Optional. Cannot be `null`.
        - `messages` (object) - Custom announcements the Notetaker bot posts to the meeting chat. Use this to
greet attendees when the bot joins, or to acknowledge new participants as they
arrive. Messages are optional; when omitted, the bot only posts the default
recording-and-transcription notice described in [Using Nylas Notetaker](/docs/v3/notetaker/).

Like other `notetaker_settings` fields, `messages` participates in the
configuration hierarchy and uses whole-object override semantics: the most
specific layer that sets `messages` completely replaces the parent's value
(there is no per-message merging). See [Custom announcements](/docs/v3/notetaker/custom-announcements/)
for the full inheritance model.
          - `on_join` (array, maxItems: 10) - Messages the bot sends shortly after it joins the meeting. Each message has
its own configurable delay measured from the moment the bot joins. Up to
10 messages per trigger.
            - `type` (string, one of: `text`) **(required)** - The message format. Currently only `text` is supported. Plain-text content
is preferred; any HTML tags in `content` are stripped before the message
is sent.
            - `content` (string, minLength: 1, maxLength: 1000) **(required)** - The message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
`content` becomes empty after sanitization are rejected with a validation
error.
            - `send_after_ms` (integer, min: 1, max: 600000) **(required)** - Delay in milliseconds between the moment the bot joins the meeting and
the moment this message is posted. Each `on_join` message is scheduled
independently against its own delay; messages are posted in the order
their delays expire.
          - `on_participant_join` (array, maxItems: 10) - Messages the bot sends when a new participant joins the meeting. Each message
uses a trailing debounce window — if another participant joins before the
window expires, the timer resets and only one message is posted per burst of
joins. Up to 10 messages per trigger.
            - `type` (string, one of: `text`) **(required)** - The message format. Currently only `text` is supported. Plain-text content
is preferred; any HTML tags in `content` are stripped before the message
is sent.
            - `content` (string, minLength: 1, maxLength: 1000) **(required)** - The message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
`content` becomes empty after sanitization are rejected with a validation
error.
            - `debounce_ms` (integer, min: 1, max: 600000) **(required)** - Trailing debounce window in milliseconds. When a participant joins, the
bot waits this long before posting the message. If another participant
joins inside the window, the timer resets — the message is only posted
once the window expires without another join event. This collapses a
burst of nearly-simultaneous joins into a single announcement.
      - `name` (string, default: `"Nylas Notetaker"`) - The display name for the Notetaker bot.
  - `error` (object) - The error for a failed operation. Not returned for a successful operation.
    - `type` (string) - The error type.
    - `message` (string) - The error message.
    - `provider_error` (object) - The error from the provider.
  - `retry_after` (number) - The number of seconds to wait before you retry the operation. Returned only on a failed
operation, when the provider rate-limited the request and gave a wait time. Can be `0`.
  - `provider_event_created` (boolean) - Returned as `true` only on a failed `create` operation, when the provider created the event
before a later step failed. Don't retry the operation, because a retry creates a duplicate
event.

### 400 - The request is invalid. Nylas ran none of the operations.

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

## Code samples

### cURL

```bash
curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/batch?calendar_id=<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "operations": [
      {
        "method": "create",
        "body": {
          "title": "Annual Philosophy Club Meeting",
          "when": {
            "start_time": 1798794000,
            "end_time": 1798797600
          }
        }
      },
      {
        "method": "update",
        "event_id": "<EVENT_ID>",
        "body": {
          "title": "Philosophy Club Meeting (moved)"
        }
      },
      {
        "method": "delete",
        "event_id": "<EVENT_ID>"
      }
    ]
  }'

```

### Node.js SDK

```javascript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function batchEvents() {
  try {
    // A 207 response (one or more operations failed) is returned, not thrown.
    const response = await nylas.events.batch({
      identifier: "<NYLAS_GRANT_ID>",
      queryParams: {
        calendarId: "<CALENDAR_ID>",
      },
      requestBody: {
        operations: [
          {
            method: "create",
            body: {
              title: "Annual Philosophy Club Meeting",
              when: { startTime: 1798794000, endTime: 1798797600 },
            },
          },
          {
            method: "update",
            eventId: "<EVENT_ID>",
            body: { title: "Philosophy Club Meeting (moved)" },
          },
          { method: "delete", eventId: "<EVENT_ID>" },
        ],
      },
    });

    // response.data[i] is the result of operations[i].
    response.data.forEach((result, index) => {
      if (result.error) {
        console.log(index, "failed:", result.status, result.error.message);
      } else {
        console.log(index, "succeeded:", result.status, result.data?.id);
      }
    });
  } catch (error) {
    console.error("Error running the batch:", error);
  }
}

batchEvents();

```

### Python SDK

```python
from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

# A 207 response (one or more operations failed) is returned, not raised.
response = nylas.events.batch(
    identifier=grant_id,
    query_params={
        "calendar_id": "<CALENDAR_ID>"
    },
    request_body={
        "operations": [
            {
                "method": "create",
                "body": {
                    "title": "Annual Philosophy Club Meeting",
                    "when": {
                        "start_time": 1798794000,
                        "end_time": 1798797600
                    },
                },
            },
            {
                "method": "update",
                "event_id": "<EVENT_ID>",
                "body": {"title": "Philosophy Club Meeting (moved)"},
            },
            {"method": "delete", "event_id": "<EVENT_ID>"},
        ]
    },
)

# response.data[i] is the result of operations[i].
for index, result in enumerate(response.data):
    if result.error is not None:
        print(index, "failed:", result.status, result.error.message)
    else:
        print(index, "succeeded:", result.status)

```

### Ruby SDK

```ruby
require 'nylas'

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

query_params = {
  calendar_id: "<CALENDAR_ID>"
}

request_body = {
  operations: [
    {
      method: "create",
      body: {
        title: "Annual Philosophy Club Meeting",
        when: {
          start_time: 1798794000,
          end_time: 1798797600
        }
      }
    },
    {
      method: "update",
      event_id: "<EVENT_ID>",
      body: { title: "Philosophy Club Meeting (moved)" }
    },
    { method: "delete", event_id: "<EVENT_ID>" }
  ]
}

# A 207 response (one or more operations failed) is returned, not raised.
results, _request_id = nylas.events.batch(
  identifier: "<NYLAS_GRANT_ID>",
  request_body: request_body,
  query_params: query_params
)

# results[i] is the result of operations[i].
results.each_with_index do |result, index|
  if result[:error]
    puts "#{index} failed: #{result[:status]} #{result[:error][:message]}"
  else
    puts "#{index} succeeded: #{result[:status]}"
  end
end

```

### Kotlin SDK

```kotlin
import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")

  val operations = listOf(
    BatchEventOperation.create(
      CreateEventRequest.Builder(
        CreateEventRequest.When.Timespan.Builder(1798794000, 1798797600).build()
      ).title("Annual Philosophy Club Meeting").build()
    ),
    BatchEventOperation.update(
      "<EVENT_ID>",
      UpdateEventRequest.Builder().title("Philosophy Club Meeting (moved)").build()
    ),
    BatchEventOperation.delete("<EVENT_ID>")
  )

  val queryParams = BatchEventsQueryParams.Builder("<CALENDAR_ID>").build()

  // A 207 response (one or more operations failed) is returned, not thrown.
  val response = nylas.events().batch("<NYLAS_GRANT_ID>", BatchEventsRequest(operations), queryParams)

  // response.data[i] is the result of operations[i].
  response.data.forEachIndexed { index, result ->
    if (result.error != null) {
      println("$index failed: ${result.status} ${result.error?.message}")
    } else {
      println("$index succeeded: ${result.status}")
    }
  }
}

```

### Java SDK

```java
import com.nylas.NylasClient;
import com.nylas.models.*;

import java.util.Arrays;
import java.util.List;

public class BatchEvents {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    List<BatchEventOperation> operations = Arrays.asList(
        BatchEventOperation.create(new CreateEventRequest.Builder(
            new CreateEventRequest.When.Timespan.Builder(1798794000, 1798797600).build()
        ).title("Annual Philosophy Club Meeting").build()),
        BatchEventOperation.update("<EVENT_ID>",
            new UpdateEventRequest.Builder().title("Philosophy Club Meeting (moved)").build()),
        BatchEventOperation.delete("<EVENT_ID>")
    );

    BatchEventsQueryParams queryParams = new BatchEventsQueryParams.Builder("<CALENDAR_ID>").build();

    // A 207 response (one or more operations failed) is returned, not thrown.
    BatchEventsResponse response = nylas.events().batch(
        "<NYLAS_GRANT_ID>", new BatchEventsRequest(operations), queryParams);

    // response.getData().get(i) is the result of operations.get(i).
    for (int i = 0; i < response.getData().size(); i++) {
      BatchEventResult result = response.getData().get(i);

      if (result.getError() != null) {
        System.out.println(i + " failed: " + result.getStatus() + " " + result.getError().getMessage());
      } else {
        System.out.println(i + " succeeded: " + result.getStatus());
      }
    }
  }
}

```
