[GAS Beginner Series #79] Invite Guests Automatically to Google Calendar Events: CalendarEvent.addGuest() Tutorial

In the previous installment (Part 78), we covered how to retrieve events within a specified date range from Google Calendar using Calendar.getEvents(). Being able to view room reservations such as the Sapporo Office Meeting Room all at once opened up a whole new level of practical automation with Google Calendar, didn’t it?

In this 79th installment, we dive into Part 4 of our Google Calendar integration series!

Today, we will take a deep dive into CalendarEvent.addGuest(), an incredibly convenient Google Apps Script (GAS) method that lets you programmatically add and invite attendees (guests) to existing calendar events.

“Oh no, I forgot to invite our new team members to the Sapporo Office Monthly Meeting…”

“I want to bulk-invite an entire roster of attendees stored in a Google Spreadsheet directly to a calendar event!”

Typing in email addresses one by one by hand to send invitations takes tons of effort as the guest list grows, and typos are bound to happen sooner or later.

With Google Apps Script, you can invite all specified members to any calendar event in one click.

Using our familiar Sapporo office meetings as examples, we will walk step-by-step through basic syntax, practical bulk-invitation workflows powered by Google Sheets, and solutions to common beginner pitfalls. Let’s make calendar automation simple and fun!

1. What Is CalendarEvent.addGuest()?

CalendarEvent.addGuest() is a Google Apps Script method that adds and invites a user with a specified email address as a guest (attendee) to a specific event (CalendarEvent object) on Google Calendar.

Understanding the Concept: The Planner and the Party Analogy

Let’s organize the object hierarchy using our ongoing organizer-and-party analogy.

  • [The Planner] = The entire calendar (Calendar object)
    • The object you retrieve using methods like CalendarApp.getCalendarById() covered in Part 76.
  • [The Party] = An individual event (CalendarEvent object)
    • A specific time slot such as the “Sapporo Office Monthly Meeting”, created via createEvent() (Part 77) or fetched via getEvents() (Part 78).
  • [Handing Out Invitations] = Adding a guest (CalendarEvent.addGuest()) ★Today’s focus!
    • The action of opening a specific party (event) and sending an invitation by entering a member’s email address.

Basic Syntax

// 1. Retrieve the target event to which you want to invite guests
var event = calendar.getEventById("EVENT_ID");

// 2. Add and invite the guest via email address
event.addGuest("sapporo.taro@example.com");

The syntax is very straightforward: simply chain the method using dot notation like event.addGuest("email address");.

2. STEP 1: Preparation – Create the Sapporo Office Monthly Meeting Event

First, let’s create a test event on Google Calendar so that we can manipulate it using GAS.

Steps

  1. Open Google Calendar: Access Google Calendar in your web browser.
  2. Create a Test Event
    • Manually create an event for any time slot today with the title “Sapporo Office Monthly Meeting”.
    • (Note: You can also use an event automatically generated via createEvent() using the script from Part 77!)
  3. Prepare a Test Email Address
    • For testing, prepare a secondary email address that you manage (such as an alternate account or a colleague’s address with their prior permission).

3. STEP 2: Hands-on – Add a Guest to a Specific Calendar Event

Once your test event is ready, open the Apps Script editor and let’s write some code!

Here, we will write a script that searches today’s calendar for the “Sapporo Office Monthly Meeting” event and automatically invites a guest to it.

1. Enter the Code

From your Google Sheet (or standalone script), navigate to Extensions > Apps Script in the menu bar, and paste in the following code:

function addGuestToSapporoMeeting() {
  // 1. Get the primary calendar
  var calendar = CalendarApp.getDefaultCalendar();
  
  // 2. Retrieve today's events to find "Sapporo Office Monthly Meeting"
  var today = new Date();
  var events = calendar.getEventsForDay(today);
  
  var targetEvent = null;
  
  // Search for "Sapporo Office Monthly Meeting" among today's events
  for (var i = 0; i < events.length; i++) {
    if (events[i].getTitle() === "Sapporo Office Monthly Meeting") {
      targetEvent = events[i];
      break; // Found the target event, exit loop
    }
  }
  
  // 3. If target event is found, invite the guest
  if (targetEvent) {
    var guestEmail = "sapporo.member@example.com"; // * Replace with your actual test email address
    
    // Add guest!
    targetEvent.addGuest(guestEmail);
    
    Logger.log("Invited " + guestEmail + " to \"" + targetEvent.getTitle() + "\"!");
  } else {
    Logger.log("Sapporo Office Monthly Meeting was not found in today's schedule.");
  }
}

2. Line-by-Line Code Breakdown

Let’s examine the essential points step-by-step for clear understanding:

  • CalendarApp.getDefaultCalendar()
    • Retrieves the primary calendar of the Google account executing the script.
  • calendar.getEventsForDay(today)
    • Fetches all calendar events scheduled for today as an array (list).
  • for (var i = 0; i < events.length; i++) { ... }
    • Iterates through each event in the list, checking whether .getTitle() matches “Sapporo Office Monthly Meeting”.
  • targetEvent.addGuest(guestEmail);
    • The main star of this tutorial! Calling .addGuest() on the matched event object (targetEvent) and passing the email address automatically invites the user within Google Calendar.

3. Save and Run the Script

  1. Click the Save icon (floppy disk) at the top of the script editor.
  2. Click the Run button.
    • * If this is your first time running the script, an authorization pop-up requesting access permissions to Google Calendar will appear. Follow the prompts to grant access.
  3. Check your Google Calendar!

[Verifying Execution Results]

Open the details of the “Sapporo Office Monthly Meeting” event in Google Calendar. You will notice that the specified email address has been automatically added under the “Guests” section!

4. STEP 3: Professional Use Cases – 3 Practical Patterns for CalendarEvent.addGuest()

Beyond inviting a single person, here are three real-world techniques widely used in workplace automation.

Pattern 1: Bulk Invite Attendees from a Google Spreadsheet Roster

The most popular enterprise use case is inviting all members at once from a member roster organized in Google Sheets.

[Spreadsheet Layout Sample] (Sheet Name: “Sapporo Team Roster”)

A B
1 Name Email Address
2 Taro Sapporo taro.sapporo@example.com
3 Hanako Odori hanako.odori@example.com
4 Jiro Susukino jiro.susukino@example.com
function addGuestsFromSpreadsheet() {
  // 1. Retrieve the email address list from Google Sheets
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Sapporo Team Roster");
  var lastRow = sheet.getLastRow();
  
  // Get data as a 2D array from range A2:B4 (see Part 13: Range.getValues)
  var memberData = sheet.getRange(2, 1, lastRow - 1, 2).getValues();
  
  // 2. Retrieve today's "Sapporo Office Monthly Meeting" from Calendar
  var calendar = CalendarApp.getDefaultCalendar();
  var events = calendar.getEventsForDay(new Date());
  var targetEvent = null;
  
  for (var i = 0; i < events.length; i++) {
    if (events[i].getTitle() === "Sapporo Office Monthly Meeting") {
      targetEvent = events[i];
      break;
    }
  }
  
  if (!targetEvent) {
    Logger.log("Target event was not found.");
    return;
  }
  
  // 3. Loop through and invite each member sequentially!
  for (var j = 0; j < memberData.length; j++) {
    var email = memberData[j][1]; // Column B email address
    
    if (email !== "") {
      targetEvent.addGuest(email);
      Logger.log("Invited " + memberData[j][0] + " (" + email + ").");
    }
  }
}

Running this script allows you to invite 10 or even 50 attendees from your sheet to the calendar event in seconds!

Pattern 2: Add Guests Simultaneously When Creating an Event

The Calendar.createEvent() method covered in Part 77 also supports specifying guests directly through an optional parameter.

When you know who to invite right from the start, utilizing options keeps your code clean and concise.

function createEventWithGuests() {
  var calendar = CalendarApp.getDefaultCalendar();
  
  var title = "Sapporo Soup Curry New Menu Tasting";
  var startTime = new Date("2026/10/05 12:00:00");
  var endTime   = new Date("2026/10/05 13:00:00");
  
  // Specify comma-separated email addresses in options
  var options = {
    guests: "taro.sapporo@example.com, hanako.odori@example.com",
    sendInvites: true // Automatically send invitation notification emails
  };
  
  // Create event and invite guests simultaneously!
  calendar.createEvent(title, startTime, endTime, options);
  
  Logger.log("Tasting event created and guests invited successfully!");
}
  • Adding attendees to an existing event later ➡ CalendarEvent.addGuest()
  • Inviting everyone at the moment of creating an event ➡ options.guests in createEvent()

Knowing when to use each approach gives you total flexibility in your workflows!

Pattern 3: Check Guest RSVP Status

After sending out invitations, you can also inspect who has accepted, declined, or not yet responded via code.

function checkGuestStatus() {
  var calendar = CalendarApp.getDefaultCalendar();
  var events = calendar.getEventsForDay(new Date());
  
  if (events.length === 0) return;
  
  var event = events[0]; // Get the first event
  var guests = event.getGuestList(); // Get array of EventGuest objects
  
  Logger.log("■ Attendance status for \"" + event.getTitle() + "\":");
  
  for (var i = 0; i < guests.length; i++) {
    var email = guests[i].getEmail();
    var status = guests[i].getGuestStatus(); // Retrieve RSVP status
    
    // Status evaluation
    // YES (Accepted), NO (Declined), MAYBE (Tentative), INVITED (Awaiting response)
    Logger.log("- " + email + " : " + status);
  }
}

With this logic, you can easily build advanced automations, such as automatically emailing reminder notifications only to guests who have not responded yet!

5. Troubleshooting: Top 5 Traps Beginners Encounter and How to Fix Them

Here are the five most common errors developers encounter when using CalendarEvent.addGuest(), along with their solutions.

Trap 1: Calling CalendarApp.addGuest() and Getting a TypeError

// Incorrect syntax: Calling addGuest directly on CalendarApp
CalendarApp.addGuest("sapporo@example.com");
// Error: TypeError: CalendarApp.addGuest is not a function

[Solution]

addGuest() is a method belonging to an individual event (CalendarEvent), not the entire calendar service (CalendarApp).

Always ensure you call it on an event object obtained through methods like getEvents() or createEvent(), using event.addGuest(...).

Trap 2: Email Formatting Mistakes (Full-width Characters or Trailing Spaces)

// Incorrect: Full-width @ symbol or extra trailing whitespace
event.addGuest("sapporo.taro@example.com ");

If an address contains full-width symbols like @ or unwanted spaces at the end, it will be flagged as an invalid email address, resulting in script errors or failed invitations.

[Solution]

When reading values from Google Sheets, sanitize strings using JavaScript’s .trim() to strip unnecessary spaces, and make sure all inputs use standard half-width alphanumeric characters.

Trap 3: Invitation Emails Are Not Received or Notifications Are Missing

“I executed addGuest(), but the recipient didn’t get an email notification!” This is one of the most frequent support questions.

[Explanation and Solution]

Due to Google Calendar’s notification architecture, invitations added after event creation via addGuest() may not trigger instant email alerts depending on the user’s Google Calendar settings.

If you must ensure that guests receive an email notification, create the event with createEvent(..., {sendInvites: true}) as demonstrated in Pattern 2, or trigger a custom notification using GmailApp.sendEmail() (covered in Part 32) stating that they have been added to the calendar event.

Trap 4: Scope or Permission Errors on Shared Calendars

If you try to run addGuest() against a read-only shared calendar or another person’s calendar where you do not possess edit permissions, an access denied error will occur.

[Solution]

Only execute the script against calendars and events where your account holds “Make changes to events” permissions.

Trap 5: Repeatedly Inviting the Same Person Inside a Loop

When iterating over Google Sheets rows, running scripts repeatedly might call addGuest() multiple times for guests who have already been added.

[Solution]

Call event.getGuestList() in advance to inspect current attendees. By checking if the guest’s email is already in the list before invoking addGuest(), you can avoid redundant invite calls.

6. Summary and What’s Next

In this tutorial, we mastered CalendarEvent.addGuest() to automatically add attendees to Google Calendar events.

Key Takeaways for Today

  1. CalendarEvent.addGuest("email") invites an attendee to a specific calendar event.
  2. Always call the method on an individual CalendarEvent object, not on CalendarApp.
  3. Combining this method with Google Sheets enables fully automated bulk invitations for entire teams.
  4. Using getGuestList() lets you programmatically check guest RSVP statuses (accepted, declined, etc.).

You now possess full control over creating calendar events, retrieving schedules, and automatically inviting team members!

As your calendar automations evolve, you will inevitably run into cases where meeting times change, requiring you to remove outdated, duplicate events or automatically cancel canceled meetings.

In our next installment (Part 80), wrapping up our Google Calendar integration phase, we will cover CalendarEvent.deleteEvent() to automatically delete obsolete events!

We will build clean automations to clear away duplicate, outdated meetings. Stay tuned!