NYnylas
Events

Create an event

Changed on

Creates an event.

Microsoft limitations

Microsoft always sends email notifications about changes to events. If you set notify_participants=false on a Microsoft grant, Nylas returns a 400 error.

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

Request

  • Base URL
    https://api.us.nylas.com
  • Auth
    • HTTP bearer
    • or HTTP bearer

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.

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

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

Microsoft returns a 400 error for notify_participants=false. iCloud ignores the setting and always notifies participants.

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

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
      },
      "messages": {
        "on_join": [
          {
            "type": "text",
            "content": "👋 Hey team! I'm your AI notetaker — here to capture the key points.",
            "send_after_ms": 5000
          }
        ],
        "on_participant_join": [
          {
            "type": "text",
            "content": "👋 Welcome! Recording and transcription are running.",
            "debounce_ms": 3000
          }
        ]
      }
    },
    "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

  • 0e71ff80a4ceRevision changes
    • info

      added the optional property // to the response with the status

  • a669a04b02baRevision changes
    • breaking

      removed subschema #1: Auto-conferencing subschema #2: Google Meet subschema #3: Zoom Meeting subschema #4: Microsoft Teams subschema #5: Teams for Business subschema #6: Skype for Consumer subschema #7: Skype for Business subschema #8: WebEx subschema #9: GoToMeeting from the request property oneOf list

    • breaking

      the / response's property type changed from no type to object for status

    • info

      added subschema #1: Auto-conferencing subschema #2: Google Meet subschema #3: Zoom Meeting subschema #4: Microsoft Teams subschema #5: Teams for Business subschema #6: Skype for Consumer subschema #7: Skype for Business subschema #8: WebEx subschema #9: GoToMeeting subschema #10: Remove conferencing to the request property anyOf list

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      removed from the / response property allOf list for the response status