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.

Filtering is most of the job

Not every event in the window should trigger an email. The recipe's filter skips three categories:

Already-reminded events — track sent reminders by event ID in a persistent store, or your 15-minute cron will nag attendees four times an hour.
All-day events — timed events have when.object set to "timespan"; all-day ones use "date" or "datespan" with date strings. Holidays and OOO blocks don't need reminders.
Events with no external participants — a calendar hold with only the organizer on it is a note-to-self, not a meeting.

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.

Composing something better than "Event in 1 hour"

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.

The half you'd forget: changes

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.

Quirks that surface in production

Recurring events arrive pre-expanded. Each occurrence in your query window is its own event with its own ID. Track reminders per occurrence, not per master_event_id.
Sync lag varies by provider. Google events typically appear within seconds; Microsoft and Exchange can take longer. If your reminder window is tight — say 30 minutes before start — budget for that.
Calendar IDs aren't portable. Google uses the account's email address as the primary calendar ID; Microsoft uses a long opaque string. Discover them via the list-calendars endpoint instead of hardcoding.
Rate limits are per grant. A dense calendar means many sends per scan — add a small delay between emails or queue them.

Start with the read, not the send

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?

推荐订阅源