Understanding `notify_participants` in the Calendar and Events API

Question and Answers
1

I was digging into the notify_participants flag in the Events API, because I have an app that has already been set up to support Google Calendar, and I was working to also support Outlook Calendar… but I think I don’t understand it. First I found this bit of documentation

Events API documentation: Nylas Email, Calendar, and Contacts API docs | Docs

notify_participants - boolean - default: true

Filter for events matching the specified notify_participants setting.

Microsoft and iCloud do not support notify_participants=false.

So first of all, this is the page about creating an event, so I’m confused why it’s talking about filtering. I understand that Microsoft does not support false, and the Nylas API told me so early on, so I set it to true for Outlook events in particular early on – and then while testing around later on, I learned that this enabled sending calendar invites (via ICS attachments) to Google calendar users.

The issue I’m running into is understanding the behavior behind notify_participants=true because I’m trying not to send unnecessary emails and spam my guests if a calendar’s events needs updating. And I also want to make sure to support cross-calendar invites (i.e. create either a Microsoft Outlook calendar or a Google calendar, create events, and invite a mixture of Google calendar and Microsoft Outlook emails).

So then I tried to find where the notify_participants field is described more completely/thoroughly and found this.

Notify Participants documentation: Using the Events API | Docs

The query string parameter notify_participants=true sends an email invitation to all email addresses listed in the participants sub-object. The query string parameter defaults to true.

:warning: Keep in mind: When notify_participants=false, your request doesn’t create an event for the participant. Participants don’t receive a message or an ICS file.

Is notify_participants smart enough to perform the equivalent to notify_participants=false to guests with with Google emails when sending them a Google calendar event? From testing around, I think it does, but the documentation doesn’t seem to point to that behavior.

  • If it does the smart thing and invites users to the calendar if their provider matches and sends emails if their provider doesn’t, I’d like to ask that the documentation be updated to represent that.
  • If it does not do the smart thing (which I think is the case here), how might you suggest updating a Google-hosted calendar to Google participants using notify_participants=false, and all others with notify_participants=true to prevent email spam.
    • My worry here is that the Nylas API won’t support making 2 API calls to update the event for a split set of users so that some can have notify_participants=false and others with notify_participants=true
2

Hello Julianna,

No, notify_participants is NOT provider-aware. It’s a simple boolean that maps directly to provider APIs:

  • Google: notify_participants=true → sendUpdates=all, false → sendUpdates=none

  • Microsoft/Outlook: Only supports true (returns 400 error if false)

When notify_participants=true:

  1. Google Calendar uses sendUpdates=all, which tells Google to “send notifications to all guests” - but Google decides how to notify them:

    • Google participants: Usually just a calendar notification (no email)

    • Non-Google emails: Email with ICS attachment

  2. Outlook/Exchange always sends email invitations to all participants (can’t be disabled via Nylas API)

You cannot update an event with different notify_participants values per participant. The API applies one value to the entire event, and you cannot make multiple calls to the same event with different notification settings for different guests - the last update would override the previous one.

Workaround

For Google Calendar specifically, rely on Google’s native behavior: when you use notify_participants=true, Google already handles same-provider participants more gracefully (calendar notifications vs emails). For cross-provider scenarios, there’s currently no way to selectively notify only non-Google participants without also notifying Google ones.

3

Thank you very much for the response, Josias! I appreciate it.

Hopes going up

Your message gave me a lot of hope, and it also gave me an idea. Specifically these parts:

When notify_participants=true:

  1. Google Calendar uses sendUpdates=all, which tells Google to “send notifications to all guests” - but Google decides how to notify them:

    • Google participants: Usually just a calendar notification (no email)

and

For Google Calendar specifically, rely on Google’s native behavior: when you use notify_participants=true, Google already handles same-provider participants more gracefully (calendar notifications vs emails).

My new idea can also be half-attributed to this other answer I found having to do with the calendar-api before that I read before I made my post:

With the Nylas Calendar API, you can only control the calendar of connected accounts (internal interviewers). The recipient will receive a calendar invite via email that they can add to their calendar manually.

Testing the new theory

So then I thought, maybe its only silent and doesn’t send an email when it’s the same domain! (It’s a case I don’t remember the result of because testing it on my own is difficult.) And I found that it does send simply send emails with ICS attachments and doesn’t detect that they’re both Google emails within the same domain:

Events sent from To internal Gmail domain To @gmail.com
internal Gmail domain Received invite emails with ICS attachments :sob: Received invite emails with ICS attachments
@gmail.com Received invite emails with ICS attachments Received invite emails with ICS attachments

Result – hopes crashed back down:

Calendar invites from internal Google emails to internal Google emails still receive emails with ICS attachments rather than getting added/invited to the calendar silently.

For the moment, we’ve chosen to keep Gmail silent (with notify_participants=false) and not work cross-functionally with other email providers, as our use case mostly has to do with corporate events, where the email domain of the calendar owner and invitees are the same. But I’ll admit it’s disappointing.

4

Hello,

Short answer: No, notify_participants is not currently smart enough to distinguish between same-provider and cross-provider participants.

Current behavior:

  • Google Calendar: notify_participants=true sends emails to all participants (both Google and non-Google users), and notify_participants=false sends to no one

  • Microsoft/Outlook: Does not support notify_participants=false at all—it will always notify all participants

Why you’re seeing ICS emails to Google users:

When you set notify_participants=true on a Google Calendar event, Google sends email invitations (with ICS attachments) to all participants, even if they’re Google Calendar users who already have the event on their calendar.

Google Calendar’s API supports a third option (sendUpdates=externalOnly) that sends emails only to non-Google participants, but Nylas does not currently expose this option. This would address your cross-calendar invite scenario. While we will raise this internally, we recommend submitting a feature request to our Product team to share your interest and use case: https://feedback.nylas.com

Workaround for now:

Unfortunately, you cannot make separate API calls with different notify_participants values for the same event. Your options are:

  1. Accept the duplicate emails for Google-to-Google invites

  2. Use notify_participants=false and manually send emails to external participants via the Messages API

We’ll also pass along your feedback regarding the documentation.

Feel free to reach out if you have any questions.

Many thanks,
Samuel R.
Support Engineer, Nylas

5

Thank you for the suggestion! For cross-linking completeness, here’s the feature request.

6

Many thanks,
Samuel R.
Support Engineer, Nylas