Create an event - Events - API Reference

POST

https://api.us.nylas.com/v3/grants/{grant_id}/events

Creates an event.

Microsoft limitations

Microsoft ignores the notify_participants field and always sends email notifications about changes to events.

iCloud limitations

iCloud ignores the notify_participants field and always sends email notifications about changes to events.
Email addresses that are registered with iCloud will not receive notify_participants notifications containing the event. These events are automatically added to the iCloud calendar.
Participants' information might be replaced by their iCloud alias. For example, if the organizer's email address is [email protected] and their iCloud account was registered with [email protected], you might encounter cases where [email protected] is replaced with [email protected].

NYLAS API KEYACCESS TOKEN

Parameters

Path parameters

grant_id*string

ID of the grant to access. You can also use the email address associated with the grant, or use /me/ to refer to the grant associated with an access token.

Example: "[email protected]"

Query parameters

calendar_id*string

Filter for the specified calendar ID.

(Not supported for iCloud) You can use primary to query the user's primary calendar.

For an Agent Account, you can also pass the account's own email address, in any letter case, to query its primary calendar. Any other email address returns a 400 error.

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

Filter for events matching the specified notify_participants setting.

Microsoft and iCloud do not support notify_participants=false.

Default: true

tentative_as_busyboolean

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

Default: true

Request body

busybooleannullable

When true, shows the event's time block as "busy" on shared or public calendars. This might be called "transparency" in some systems. This field may be null if not explicitly set. Treat null the same as true (the default behavior).

Example: true

capacityinteger

The maximum number of participants that can attend the event.

Example: 5

conferencingobject

An object that lets you automatically create a conference, or enter conferencing details manually.

You can't use autocreate and details in the same request. If you do, Nylas returns an error.

Nylas stores conference information in the event description. To remove conference details, set conferencing to {} and remove the corresponding conference information from the description in the same request.

descriptionstring

A brief description of the event (for example, its agenda). Nylas might return the description as an HTML string, depending on how the provider formats it.

For Google accounts, this field accepts a maximum of 8,192 characters.

Example: "Come ready to talk philosophy!"

hide_participantsboolean

When true, hides the event's list of participants.

Example: false

locationstring

The location of the event (for example, a physical address or the name of a meeting room).

Example: "Room 130"

maxLength: 255

metadataobject

The metadata associated with the object. For more information, see Metadata.

notetakerobject

idstringread-only

The Notetaker bot ID. Read-only; returned in responses but not required in create or update requests.

Example: "71c807752c744ad0902f64d43e6cc399"

meeting_settingsobject

A collection of settings for the Notetaker bot.

action_itemsboolean

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.

Default: true

Example: true

action_items_settingsobject

audio_recordingboolean

When true, Notetaker records the meeting's audio.

Default: true

Example: true

leave_after_silence_secondsinteger

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).

Default: 300

Example: 360

min: 10max: 3600

summaryboolean

When true, Notetaker generates a summary of the meeting. If summary is true, video_recording, audio_recording, and transcription must also be true.

Default: true

Example: true

summary_settingsobject

transcriptionboolean

When true, Notetaker transcribes the meeting's audio. If transcription is true, video_recording and audio_recording must also be true.

Default: true

Example: true

video_recordingboolean

When true, Notetaker records the meeting's video.

Default: true

Example: true

transcription_settingsobjectnullable

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 for supported language codes and validation rules.

messagesobject

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.

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 for the full inheritance model.

on_joinarray<object>

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.

maxItems: 10

on_participant_joinarray<object>

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.

maxItems: 10

namestring

The display name for the Notetaker bot.

Default: "Nylas Notetaker"

Example: "Nylas Notetaker"

participantsarray<object>

resourcesarray<object>

recurrencearray<string>

An array of RRULE and EXDATE strings. Nylas includes this field only if the event is the main (master) event. See RFC-5545 for more details. You can use this tool 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.

Example: ["RRULE:FREQ=WEEKLY;BYDAY=MO","EXDATE:20210405T000000Z"]

remindersobject

A list of reminders to send for the event. If left empty or omitted, the event uses the provider defaults.

titlestring

The name of the event.

Example: "Annual Philosophy Club Meeting"

maxLength: 1024

visibilitystringnullable

(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.

defaultprivatepublic

when*object

An object that represents the time and duration of an event.

You can format when as one of four sub-objects: time, timespan, date, or datespan. These sub-objects allow you to capture and represent specific points in time.

time and timespan objects include optional timezone support.

Responses

request_idstring

The request ID.

dataobject

busyboolean

If true, shows the event's time block as busy on shared or public calendars. This may be called "transparency" in some systems.

calendar_idstringnullable

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.

Example: "7d93zl2palhxqdy6e5qinsakt"

conferencingobject

An object that contains event conferencing details. Nylas appends the conference information to the Event description.

created_atintegernullable

When the event was created, in seconds using the Unix timestamp format.

Example: 1661874192

descriptionstringnullable

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.

Example: "Time for us to sync weekly on any new project changes"

minLength: 0

text_descriptionstringnullable

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.

Example: "Time for us to sync weekly on any new project changes"

minLength: 0

hide_participantsboolean

(Not supported for iCloud or EWS events) When true, hides the event's list of participants.

grant_idstringread-only

The ID of grant for the connected user.

Example: "41009df5-bf11-4c97-aa18-b285b5f2e386"

html_linkstring

(Not supported for EWS events) A link to the event on the provider.

Example:

"https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Ef3feD2VuM29fMjAyMjA2MjdUMjIwMDAwWiBoYWxsYUBueWxhcy5jb20"

ical_uidstringnullable

A unique ID that you can use to identify events across calendaring systems, in iCalendar format. Recurring events might share the same ID.

Can be null for events synced before the year 2020.

idstring

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"

minLength: 1

locationstringnullable

The location of the event (for example, a physical address or the name of a meeting room).

master_event_idstringnullable

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.

metadataobject

The metadata associated with the object. For more information, see Metadata.

objectstring

The type of object.

organizerobject

An object that contains information about an event's organizer.

participantsarray<object>

An array of participants invited to the event. The organizer doesn't need to be explicitly included in this list.

minItems: 1

resourcesarray<object>

An array of room resource bookings added to the event.

read_onlyboolean

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.

remindersobject

A list of reminders to generate for the event. If not defined, Nylas uses the provider's default settings.

recurrencearray<string>

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.

Example: ["RRULE:FREQ=WEEKLY;BYDAY=MO","EXDATE:20210405T000000Z"]

statusstring

(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 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.

confirmedcancelledmaybe

Example: "confirmed"

titlestring

The name of the event.

Example: "Remote Event: Group Yoga Class"

minLength: 1maxLength: 1024

updated_atintegernullable

When the event was last updated, in seconds using the Unix timestamp format.

Example: 1661874192

visibilitystringnullable

defaultprivatepublic

whenobjectnullable

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_timeinteger

(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.

Example: 1633698000

notetakerobject

idstringread-only

The Notetaker bot ID. Read-only; returned in responses but not required in create or update requests.

Example: "71c807752c744ad0902f64d43e6cc399"

meeting_settingsobject

A collection of settings for the Notetaker bot.

action_itemsboolean

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.

Default: true

Example: true

action_items_settingsobject

audio_recordingboolean

When true, Notetaker records the meeting's audio.

Default: true

Example: true

leave_after_silence_secondsinteger

Default: 300

Example: 360

min: 10max: 3600

summaryboolean

When true, Notetaker generates a summary of the meeting. If summary is true, video_recording, audio_recording, and transcription must also be true.

Default: true

Example: true

summary_settingsobject

transcriptionboolean

When true, Notetaker transcribes the meeting's audio. If transcription is true, video_recording and audio_recording must also be true.

Default: true

Example: true

video_recordingboolean

When true, Notetaker records the meeting's video.

Default: true

Example: true

transcription_settingsobjectnullable

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.

See Set transcription languages for supported language codes and validation rules.

messagesobject

on_joinarray<object>

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.

maxItems: 10

on_participant_joinarray<object>

maxItems: 10

namestring

The display name for the Notetaker bot.

Default: "Nylas Notetaker"

Example: "Nylas Notetaker"

Code examples

curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Annual Philosophy Club Meeting",
    "busy": true,
    "conferencing": {
        "provider": "Zoom Meeting",
        "autocreate": {
          "conf_grant_id": "<NYLAS_GRANT_ID>",
          "conf_settings": {
            "settings": {
              "join_before_host": true,
              "waiting_room": false,
              "mute_upon_entry": false,
              "auto_recording": "none"
            }
          }
        }
      },
    "participants": [
      {
        "name": "Leyah Miller",
        "email": "[email protected]"
      },
      {
        "name": "Nyla",
        "email": "[email protected]"
      }
    ],
    "resources": [{
      "name": "Conference room",
      "email": "[email protected]"
    }],
    "description": "Come ready to talk philosophy!",
    "when": {
      "start_time": 1674604800,
      "end_time": 1722382420,
      "start_timezone": "America/New_York",
      "end_timezone": "America/New_York"
    },
    "location": "New York Public Library, Cave room",
    "recurrence": [
      "RRULE:FREQ=WEEKLY;BYDAY=MO",
      "EXDATE:20211011T000000Z"
  ],
}'
Sign in and select an app and grant, then add any required auth token, to auto-fill these placeholders with your real values.

Copy

View as Markdown

Install

Open in

Open in Claude Open in ChatGPT Open in Cursor