Sign in
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 example@icloud.com and their iCloud account was registered with example@gmail.com, you might encounter cases where example@icloud.com is replaced with example@gmail.com.
post/v3/grants/{grant_id}/events

Query parameters

calendar_idstring required

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.

Request body

busyboolean nullable

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

capacityinteger

The maximum number of participants that can attend the event.

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.

hide_participantsboolean

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

locationstring

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

metadataMetadata

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

recurrencestring[]

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

The name of the event.

visibility'default' | 'private' | 'public' nullable

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

Example request

{
  "busy": true,
  "capacity": 5,
  "description": "Come ready to talk philosophy!",
  "location": "Room 130",
  "notetaker": {
    "id": "71c807752c744ad0902f64d43e6cc399",
    "meeting_settings": {
      "action_items": true,
      "action_items_settings": {
        "custom_instructions": "Only return the 5 most important action items."
      },
      "audio_recording": true,
      "leave_after_silence_seconds": 360,
      "summary": true,
      "summary_settings": {
        "custom_instructions": "Return this summary in the MEDPIC sales methodology."
      },
      "transcription": true,
      "video_recording": true,
      "transcription_settings": {
        "expected_languages": [
          "en",
          "es"
        ],
        "fallback_language": "en",
        "keywords": [
          "Nylas",
          "AssemblyAI"
        ],
        "use_speaker_names_as_keywords": true
      }
    },
    "name": "Nylas Notetaker"
  },
  "participants": [
    {
      "email": "dorothy@example.com",
      "name": "Dorothy Vaughan"
    }
  ],
  "resources": [
    {
      "email": "conference-room@resource.google.com",
      "name": "Conference room"
    }
  ],
  "recurrence": [
    "RRULE:FREQ=WEEKLY;BYDAY=MO",
    "EXDATE:20210405T000000Z"
  ],
  "reminders": {
    "overrides": [
      {
        "reminder_minutes": 20,
        "reminder_method": "popup"
      }
    ]
  },
  "title": "Annual Philosophy Club Meeting",
  "when": {
    "time": 1633698000,
    "timezone": "America/New_York"
  }
}

Response

Event Response

request_idstring

The request ID.

Example response

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88"
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.