Event Reminders From an Agent's Calendar

Nylas published a recipe for building an event reminder system using its Calendar API. The system fetches events via a single API call, filters out all-day, cancelled, and organizer-only events, and sends email reminders to external participants. It supports Google Calendar, Microsoft, and Exchange without provider-specific code, and can be paired with Agent Accounts for dedicated reminder addresses.

An entire appointment-reminder system hangs off this one request: curl --request GET \ --url 'https://api.us.nylas.com/v3/grants/<NYLAS GRANT ID /events?calendar id=<CALENDAR ID &start=1700000000&end=1700086400&limit=50' \ --header 'Authorization: Bearer <NYLAS API KEY ' start and end are Unix timestamps in seconds, so that's "every event in the next 24 hours" in a single call. Run it on a cron every 15 minutes, filter out events that don't deserve a reminder, email the attendees who do, and you've replaced the reminder feature that calendar apps never built — because built-in notifications only reach the event's owner , not the patient, student, or prospect on the other side. The event reminder recipe https://developer.nylas.com/docs/cookbook/use-cases/act/schedule-event-reminders/ walks the whole thing end to end, and it runs across Google Calendar, Microsoft, and Exchange with no provider-specific code. Pair it with an Agent Account https://developer.nylas.com/docs/v3/agent-accounts/ — in beta — and the reminders come from a dedicated address whose calendar the agent owns outright, instead of borrowing a human's grant. Not every event in the window should trigger an email. The recipe's filter skips three categories: when.object set to "timespan" ; all-day ones use "date" or "datespan" with date strings. Holidays and OOO blocks don't need reminders.The organizer also gets excluded from the recipient list. Nobody needs a reminder about the meeting they created. Cancelled events get skipped too — the status field on each event tells you whether it's still confirmed, and reminding someone about a dead meeting is worse than no reminder at all. In code, the whole filter is about a dozen lines: js const sentReminders = new Set ; // use a database in production function shouldSendReminder event { if sentReminders.has event.id return false; // All-day events use "date"/"datespan" instead of "timespan" if event.when?.object === "date" || event.when?.object === "datespan" { return false; } if event.status === "cancelled" return false; // Calendar holds with only the organizer aren't meetings return getExternalParticipants event .length 0; } function getExternalParticipants event { return event.participants || .filter p = p.email == process.env.ORGANIZER EMAIL, ; } The in-memory Set is fine for a prototype and a bug in production: it resets on every restart, and your attendees get re-reminded after each deploy. The recipe's recommendation is a database keyed by event ID with a timestamp — and, smarter still, a hash of the key fields time, title, participants so you can tell "already reminded" apart from "event changed enough to deserve a fresh notification." One nice property of the setup: a single grant handles both halves. The same connected account that reads calendar events also sends the reminder emails — no separate grants for calendar and email access. Because the event object carries title , location , conferencing.details.url , description , and per-event timezones, the reminder can be a properly branded HTML email: meeting name, formatted local time, join link, agenda. The recipe formats times using the event's start timezone — the docs are blunt that this is the hardest part to get right, and that an attendee in Tokyo doesn't want a time formatted for Chicago. Fall back to UTC when a provider leaves the timezone field empty. A reminder sent Tuesday is misinformation by Wednesday if the meeting moved. The recipe's second flow subscribes to event.updated and event.deleted webhooks: curl --request POST \ --url 'https://api.us.nylas.com/v3/webhooks/' \ --header 'Authorization: Bearer <NYLAS API KEY ' \ --header 'Content-Type: application/json' \ --data '{ "trigger types": "event.updated", "event.deleted" , "description": "Event change notifications for reminder system", "webhook url": "https://your-server.com/webhooks/nylas" }' The handler's first move is a guard: if the event ID isn't in your sent-reminders store, do nothing. You only owe attendees an update about meetings you already told them about — otherwise every calendar edit in the account triggers email. For events that do match, event.deleted or status: "cancelled" gets a cancellation notice and removes the dedup entry; event.updated gets an "Updated:" email with the newly formatted time. Both flows can share one process. Run the Express or Flask webhook server alongside the cron scanner — the cron handles proactive sends, the webhook listener handles reactive updates, and they read and write the same dedup store. One sharp edge from the docs: the event.deleted payload is minimal — just the event ID, grant ID, and calendar ID. By the time you learn the meeting is gone, its title and participant list are gone too. Store event metadata alongside your reminder record at send time, or your cancellation email will read "a meeting was cancelled" with no way to say which one. master event id .Wire up just the fetch-and-filter half first: run the 24-hour scan on the 15-minute cron and log which events would get reminders. A day of logs tells you whether your filters are right before any attendee sees a duplicate or a misfire. Then turn on sending and add the webhook listener for changes. The full recipe https://developer.nylas.com/docs/cookbook/use-cases/act/schedule-event-reminders/ has Node.js and Python versions of every piece — which side of it would save your users more pain: the proactive reminder, or the cancellation notice that actually arrives?