You want to pull a user’s events into your own database: a month of meetings to mirror in your product, or a back-catalog to analyze. Listing events page by page works for browsing, but it isn’t built for loading a whole time range into storage.
The Nylas Events API has a dedicated import endpoint for exactly this. It returns events from a calendar across a time frame in a read-only call tuned for ingestion rather than interactive browsing.
How do I import events for a date range?
Section titled “How do I import events for a date range?”Send a GET /v3/grants/{grant_id}/events/import request with the calendar_id, a start, and an end as Unix timestamps. Nylas returns the events in that window so you can store them in your own system. It’s a read-only endpoint, so it only needs read scopes, and it’s available on 2 providers: Google and Microsoft (Microsoft Graph support is in beta).
The request below imports events from a calendar within a time frame.
curl --compressed --request GET \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/import?calendar_id=<CALENDAR_ID>&start=<TIMESTAMP>&end=<TIMESTAMP>' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <NYLAS_API_KEY>' \ --header 'Content-Type: application/json'When should I use import instead of listing?
Section titled “When should I use import instead of listing?”The import endpoint is built for ingestion, while the Get all Events endpoint is built for browsing. Reach for import when you want to load, store, and process events in your own system; reach for the list endpoint when a user is paging through their calendar in your UI. Both work on 2 providers and return the same event objects for different jobs.
One behavior to plan for: imported events aren’t guaranteed to be sorted by start time, so sort them yourself after fetching if order matters.
Things to know about importing events
Section titled “Things to know about importing events”A couple of constraints are worth noting. The import endpoint doesn’t support metadata, so if you rely on custom metadata filtering you’ll use the standard list endpoint instead. Import also needs only the read-only calendar scope, which keeps the permission footprint small when all you do is ingest.
Because import covers a start-to-end window, paginate by time: pull events in monthly or weekly chunks for a large back-catalog rather than one enormous range. This keeps responses manageable across the 2 providers (Google and Microsoft).
What’s next
Section titled “What’s next”- Import events reference for every request parameter
- List Google events for interactive browsing instead of ingestion
- Create and list calendars to get the calendar IDs you import from
- Sync calendar events to a CRM for an end-to-end sync workflow