https://api.us.nylas.com/v3/grants/{grant_id}/events/importImport events
Returns a list of recurring events, recurring event exceptions, and single events from the specified calendar within a given time frame. This is useful when you want to import, store, and synchronize events from the time frame to your application (for example, to enrich events with custom data or integrate events into your own calendaring solution).
If you want to retrieve a list of all events from a calendar, use the Get all Events endpoint instead.
Limitations
- Nylas might return multiple instances of a single recurring event if the results are paginated.
- The number of events Nylas returns might be lower than
max_results, even if others match your query parameters. - Events are not guaranteed to be sorted by their start time.
- Nylas does not support metadata for this endpoint.
- Support for Microsoft Graph is in beta.
Path parameters
Query parameters
Specifies the maximum number of events Nylas returns in a single page of results. The actual number of events Nylas returns might be lower than this limit, even if other events match your query parameters.
50An identifier that specifies which page of data to return. You can get this value from the
next_cursor response field. See Pagination for more
information.
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.
Filter for events that start at or after the specified time, in seconds using the Unix timestamp format. For example, if you filter for events that start at 9:00a.m., and the calendar includes an event that runs from 8:30–9:30a.m., Nylas returns that event.
Defaults to the time that you make the request.
The start value cannot be later than end. For iCloud accounts, the difference between start
and end can't be greater than one year.
Filter for events that end at or before the specified time, in seconds using the Unix timestamp format. For example, if you filter for events that end at 5:00p.m., and the calendar includes an event that runs from 4:30–5:30p.m., Nylas returns that event.
Defaults to one month from the time you make the request.
The end value cannot be earlier than start. For iCloud accounts, the difference between start
and end can't be greater than one year.
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.
calendar_idstringnullableThe 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.
"7d93zl2palhxqdy6e5qinsakt"conferencingobjectAn object that contains event conferencing details. Nylas appends the conference information to the
Event description.
detailsobjectAn 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.
autocreateobjectThe 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.
1661874192descriptionstringnullableA 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.
"Time for us to sync weekly on any new project changes"text_descriptionstringnullableA 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.
"Time for us to sync weekly on any new project changes""41009df5-bf11-4c97-aa18-b285b5f2e386""https://www.google.com/calendar/event?eid=bTMzcGJrNW4yYjk4bjk3OWE4Ef3feD2VuM29fMjAyMjA2MjdUMjIwMDAwWiBoYWxsYUBueWxhcy5jb20"ical_uidstringnullableA 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.
idstringThe 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.
"5d3qmne77v32r8l4phyuksl2x"emailstringThe organizer's email address.
For an event in a Google calendar, Nylas returns the email based on the calender type.
- For a primary calendar,
emailis the same as thecalendar_id. - For a non-primary calendar,
emailis set to the actual ID of the calendar.
"[email protected]"participantsarray<object>An array of participants invited to the event. The organizer doesn't need to be explicitly included in this list.
"[email protected]"read_onlybooleanIf 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.
remindersobjectA list of reminders to generate for the event. If not defined, Nylas uses the provider's default settings.
use_defaultbooleannullableWhen 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.
overridesarray<object>nullableA 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.
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,
EXDATEmight 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
DTSTARTorTZID. Nylas uses the event'swhenvalues 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
UNTILdate.
["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.
"confirmed""Remote Event: Group Yoga Class"updated_atintegernullableWhen the event was last updated, in seconds using the Unix timestamp format.
1661874192visibilitystringnullable(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.
whenobjectnullableAn 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).
1409594400start_timezonestringnullableThe timezone of the event's start_time as an
IANA-formatted string.
If you define start_timezone in your request, you must also define end_timezone.
"America/New_York"end_timezonestringnullableThe timezone of the event's end_time as an
IANA-formatted string.
If you define end_timezone in your request, you must also define start_timezone.
"America/New_York"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.
1633698000idstringread-onlyThe Notetaker bot ID. Read-only; returned in responses but not required in create or update requests.
"71c807752c744ad0902f64d43e6cc399"action_itemsbooleanWhen 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.
truetrueleave_after_silence_secondsintegerThe 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).
300360summarybooleanWhen true, Notetaker generates a summary of the meeting. If summary is true,
video_recording, audio_recording, and transcription must also be true.
truetruetranscriptionbooleanWhen true, Notetaker transcribes the meeting's audio. If transcription is true,
video_recording and audio_recording must also be true.
truetruetranscription_settingsobjectnullableOptional 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.
expected_languagesarray<string>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.
["en","es"]fallback_languagestringLanguage 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.
"en"keywordsarray<string>Domain-specific terms that bias transcription toward recognizing them correctly, such
as names, acronyms, and product names. Optional. Up to 200 terms; each term must be
1 to 200 characters and cannot contain control characters. Cannot be null.
["Nylas","AssemblyAI"]messagesobjectCustom 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.
type*stringThe message format. Currently only text is supported. Plain-text content
is preferred; any HTML tags in content are stripped before the message
is sent.
"text"content*stringThe 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.
"👋 Hey team! I'm your AI notetaker — here to capture the key points."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.
type*stringThe message format. Currently only text is supported. Plain-text content
is preferred; any HTML tags in content are stripped before the message
is sent.
"text"content*stringThe 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.
"👋 Welcome! Recording and transcription are running."debounce_ms*integerTrailing 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.
3000Rate limited. The provider or Nylas throttled the request. If a provider throttles a request and
says how long to wait, the Retry-After header gives that number of seconds. When the header
is missing, retry with exponential backoff. See
429 rate limit errors by provider.