Event Reminders From an Agent's Calendar

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 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 — 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:

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 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?