Skip to content
Skip to main content
POST
/v3/grants/{grant_id}/events

Create an event

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.

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.

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

busybooleannull

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
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.
  • Virtual calendars don't support DTSTART or TZID.
  • 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
visibilitystringnull

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

For virtual calendar events, you can explicitly set visibility to private or public on create and update requests. 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
POSThttps://api.us.nylas.com/v3/grants/nyla%40example.com/events?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. You can also use the email address associated with the grant, or use /me/ to refer to the grant associated with an access token.

calendar_idrequiredstring

Filter for the specified calendar ID. (Not supported for iCloud) You can use primary to query 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

Filter for events matching the specified notify_participants setting. Microsoft and iCloud do not support notify_participants=false.

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.