【GAS入門#79】カレンダーの予定にゲストを自動招待!CalendarEvent.addGuest()の完全攻略ガイド

前回(第78回)は、Googleカレンダーから指定した期間の予定を一覧取得する Calendar.getEvents() について学びました。「札幌オフィス会議室」の予約状況をズラリと確認できるようになり、カレンダー連携の楽しさが広がってきたのではないでしょうか!

第79回となる今回は、Googleカレンダー連携編の第4弾!

作成済みの予定に対して、参加者(ゲスト)をプログラムから自動で追加・招待できる超便利メソッド CalendarEvent.addGuest() を徹底解説します!

「札幌オフィスの月次報告会に、新しいチームメンバーを招待し忘れてしまった…」

「スプレッドシートにある参加者名簿のメンバーを一括でカレンダー予定に招待したい!」

手動で1人ずつメールアドレスを入力して招待状を送るのは、人数が増えるほど手間がかかりますし、打ち間違いなどのミスも起きやすくなります。

GASを使えば、ボタン1つで指定したメンバーをカレンダー予定に一括招待することが可能です。

今回も札幌オフィスのミーティングを題材に、基礎文法からスプレッドシートと連携した一括招待の応用例、初心者がハマりやすいトラブル解決策まで、どこよりも分かりやすく丁寧に紐解いていきますね!

1. そもそも CalendarEvent.addGuest() とは?

CalendarEvent.addGuest() は、Googleカレンダー上の特定の「予定(CalendarEventオブジェクト)」に対して、指定したメールアドレスのユーザーをゲスト(参加者)として追加・招待する命令(メソッド)です。

「スケジュール帳とパーティー」の例えで理解しよう!

本連載ではおなじみのイメージ例えで構造を整理してみましょう。

  • 【スケジュール帳】= カレンダー全体(Calendarオブジェクト)
    • 第76回で学んだ CalendarApp.getCalendarById() などで取得する対象です。
  • 【パーティーの予定】= 個別のイベント(CalendarEventオブジェクト)
    • 第77回で学んだ createEvent() や、第78回で学んだ getEvents() で取得した「札幌オフィス月次報告会」などの特定の1コマです。
  • 【招待状を渡す】= ゲストの追加(CalendarEvent.addGuest())★今回の主役!
    • 特定の「パーティー(予定)」を開いて、参加してほしいメンバー(ゲスト)へメールアドレスで招待状を送る操作にあたります。

基本的な書き方(構文)

// 1. 招待したい「予定(イベント)」を取得する
var event = calendar.getEventById("イベントID");

// 2. その予定にゲスト(メールアドレス)を追加・招待する
event.addGuest("sapporo.taro@example.com");

ドット(.)でつないで event.addGuest("メールアドレス"); と記述するだけの非常にシンプルな構造をしています。

2. STEP1:準備!「札幌オフィス月次報告会」の予定を用意しよう

まずは、GASから操作するためのテスト用予定(イベント)をGoogleカレンダー上に作成しましょう。

手順

  1. Googleカレンダーを開くブラウザで Googleカレンダー にアクセスします。
  2. テスト用の予定を作成する
    • 本日の適当な時間帯に、タイトル 「札幌オフィス月次報告会」 という予定を手動で作成します。
    • (※第77回で作成したスクリプトを使って createEvent() で自動作成した予定を使ってもOKです!)
  3. 招待テスト用のメールアドレスを準備する
    • 実験用に、ご自身が管理している別のメールアドレス(サブアカウントや同僚の許可を得たアドレス)を用意しておきましょう。

3. STEP2:【実践】指定した予定にゲストを追加してみよう!

準備ができたら、さっそくGASのエディタを開いてコードを書いていきましょう!

今回は、本日のカレンダーから「札幌オフィス月次報告会」の予定を自動検索し、そこにゲストを1人招待するプログラムを作成します。

1. コードを入力する

スプレッドシート(またはスタンドアロンスクリプト)のメニューバーから 「拡張機能」 > 「Apps Script」 を開き、以下のコードを貼り付けます。

function addGuestToSapporoMeeting() {
  // ① メインのカレンダーを取得する
  var calendar = CalendarApp.getDefaultCalendar();
  
  // ② 本日の「札幌オフィス月次報告会」の予定を取得する
  var today = new Date();
  var events = calendar.getEventsForDay(today);
  
  var targetEvent = null;
  
  // 予定の中から「札幌オフィス月次報告会」を探す
  for (var i = 0; i < events.length; i++) {
    if (events[i].getTitle() === "札幌オフィス月次報告会") {
      targetEvent = events[i];
      break; // 目的の予定が見つかったのでループを抜ける
    }
  }
  
  // ③ 目的の予定が見つかった場合、ゲストを追加招待する
  if (targetEvent) {
    var guestEmail = "sapporo.member@example.com"; // ★ここに実際のテスト用メールアドレスを入れてください
    
    // ゲストを追加!
    targetEvent.addGuest(guestEmail);
    
    Logger.log("「" + targetEvent.getTitle() + "」に " + guestEmail + " 様を招待しました!");
  } else {
    Logger.log("本日の予定に「札幌オフィス月次報告会」が見つかりませんでした。");
  }
}

2. コードの1行ずつ徹底解説!

初心者向けに、重要なポイントを分解して解説します。

  • CalendarApp.getDefaultCalendar()
    • 実行しているユーザーのプライマリ(メイン)Googleカレンダーを取得します。
  • calendar.getEventsForDay(today)
    • 今日1日分の予定を配列(リスト)としてまとめて取得します。
  • for (var i = 0; i < events.length; i++) { ... }
    • 取得した予定を1つずつチェックし、.getTitle() で予定のタイトルが「札幌オフィス月次報告会」と一致するものを探しています。
  • targetEvent.addGuest(guestEmail);
    • 本日の主役です!見つかった予定オブジェクト(targetEvent)に対して .addGuest() を呼び出し、引数にメールアドレスを渡すことで、Googleカレンダー上で招待状が自動送信されます。

3. 保存して実行する

  1. エディタ上部の 「保存アイコン(フロッピーディスク)」 をクリックします。
  2. 「実行」 ボタンをクリックします。
    • ※初回実行時はGoogleカレンダーへのアクセス権限を求めるポップアップが表示されますので、画面の指示に従って「許可」してください。
  3. Googleカレンダーの画面を確認してみましょう!

【実行結果の確認】

Googleカレンダーで「札幌オフィス月次報告会」の予定をクリックして詳細を開くと、「参加者(ゲスト)」の欄に指定したメールアドレスが自動追加されているはずです!

4. STEP3:実務で差がつく!CalendarEvent.addGuest() の応用パターン3選

単に1人追加するだけでなく、実際の業務でよく使われる3つの実践テクニックを紹介します。

応用①:スプレッドシートの「参加者リスト」から一括で自動招待する

実務で最もよく使われるのが、スプレッドシートにまとめたメンバー名簿から全員を一括で招待するパターンです。

【スプレッドシートのイメージ】(シート名:「札幌チーム名簿」)

AB
1氏名メールアドレス
2札幌 太郎taro.sapporo@example.com
3大通 花子hanako.odori@example.com
4すすきの 次郎jiro.susukino@example.com
function addGuestsFromSpreadsheet() {
  // 1. スプレッドシートからメールアドレス一覧を取得
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("札幌チーム名簿");
  var lastRow = sheet.getLastRow();
  
  // A2:B4 の範囲からデータ(2次元配列)を取得(第13回 Range.getValues 参照)
  var memberData = sheet.getRange(2, 1, lastRow - 1, 2).getValues();
  
  // 2. カレンダーから今日の「札幌オフィス月次報告会」を取得
  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() === "札幌オフィス月次報告会") {
      targetEvent = events[i];
      break;
    }
  }
  
  if (!targetEvent) {
    Logger.log("対象の予定が見つかりませんでした。");
    return;
  }
  
  // 3. ループ処理で全員を順番に招待!
  for (var j = 0; j < memberData.length; j++) {
    var email = memberData[j][1]; // B列のメールアドレス
    
    if (email !== "") {
      targetEvent.addGuest(email);
      Logger.log(memberData[j][0] + " 様(" + email + ")を招待しました。");
    }
  }
}

このコードを実行すれば、名簿に10人でも50人でも、一瞬でカレンダーの予定に一括招待できます!

応用②:予定の「新規作成」と同時にゲストを追加する

第77回で学んだ Calendar.createEvent() には、オプション引数として最初からゲストを指定する機能もあります。

新規作成時にまとめて招待したい場合は、オプションを使うとコードがすっきりします。

function createEventWithGuests() {
  var calendar = CalendarApp.getDefaultCalendar();
  
  var title = "札幌スープカレー新メニュー試食会";
  var startTime = new Date("2026/10/05 12:00:00");
  var endTime   = new Date("2026/10/05 13:00:00");
  
  // オプションでカンマ区切りのメールアドレスを指定
  var options = {
    guests: "taro.sapporo@example.com, hanako.odori@example.com",
    sendInvites: true // 招待メールを自動送信する設定
  };
  
  // 予定作成と同時に招待!
  calendar.createEvent(title, startTime, endTime, options);
  
  Logger.log("試食会の予定作成とゲスト招待が完了しました!");
}
  • 既存の予定に後から追加したい時 ➡ CalendarEvent.addGuest()
  • 新しい予定を作る時に一括で呼びたい時 ➡ createEvent() の options.guests

状況に合わせて使い分けられるようになると完璧ですね!

応用③:招待したゲストの「参加ステータス(返答状況)」を確認する

ゲストを招待した後、「誰が承諾してくれて、誰が辞退しているか」をプログラムで確認することもできます。

function checkGuestStatus() {
  var calendar = CalendarApp.getDefaultCalendar();
  var events = calendar.getEventsForDay(new Date());
  
  if (events.length === 0) return;
  
  var event = events[0]; // 最初の予定を取得
  var guests = event.getGuestList(); // ゲスト一覧(EventGuestオブジェクトの配列)を取得
  
  Logger.log("■ 「" + event.getTitle() + "」の参加状況:");
  
  for (var i = 0; i < guests.length; i++) {
    var email = guests[i].getEmail();
    var status = guests[i].getGuestStatus(); // 参加ステータスを取得
    
    // ステータスの判定
    // YES (承諾), NO (辞退), MAYBE (仮承諾), INVITED (未返答)
    Logger.log("- " + email + " : " + status);
  }
}

これを使えば、「まだ返答していない人だけにリマインドメールを送る」といった高度な自動化仕組みも作ることができます!

5. 初心者が絶対につまずく!5大トラップと完全対処法

CalendarEvent.addGuest() を使う際、プログラミング初心者が直面しやすい5つのエラーと解決策をまとめました。

トラップ1:CalendarApp.addGuest() と書いて TypeError になる

// ✕ エラーになる書き方(CalendarApp に命令を出している)
CalendarApp.addGuest("sapporo@example.com");
// エラー:TypeError: CalendarApp.addGuest is not a function

【解決策】

addGuest() は カレンダー全体(CalendarApp)ではなく、個別の予定(CalendarEvent)が持っている命令です。

必ず event.addGuest(...) のように、getEvents() や createEvent() で取得したイベントオブジェクトに対して呼び出すようにしましょう!

トラップ2:メールアドレスの入力ミス(全角文字や空白スペース)

// ✕ NG:全角のアットマークやスペースが入っている
event.addGuest("sapporo.taro@example.com ");

全角の @(アットマーク)が入っていたり、末尾に不要な半角スペースが入っていると、無効なメールアドレスと判定されてエラーになったり、招待メールが正しく届かなかったりします。

【解決策】

スプレッドシート等から取得する場合は、JavaScriptの .trim() を使って余計な空白を除去したり、英半角入力になっているか確認しましょう。

トラップ3:招待メールが届かない・通知が飛ばない

「addGuest() を実行したのに相手に通知メールが届かない」という問い合わせは非常によくあります。

【解説と解決策】

Googleカレンダーの仕様上、addGuest() で後から追加されたゲストには、アカウント設定やGoogleの通知仕様によって通知メールが即座に飛ばない場合があります。

確実に招待メールを送信させたい場合は、応用②で紹介したように予定作成時に createEvent(..., {sendInvites: true}) を使用するか、別途 GmailApp.sendEmail()(第32回)を組み合わせて「カレンダーに招待しました」とメールを送るのが確実です。

トラップ4:権限(Scope)やアクセス権がないカレンダーでのエラー

自分に編集権限のない「読み取り専用の共有カレンダー」や「他人のカレンダー」の予定に対して addGuest() を動かそうとすると、アクセス拒否のエラーが発生します。

【解決策】

自分が 「予定の変更権限」を持っているカレンダーおよび予定 に対してのみ実行してください。

トラップ5:Loop処理で同じ人を何度も繰り返し招待してしまう

スプレッドシートの繰り返し処理などで、すでに招待済みのゲストに対して何度も addGuest() を実行してしまうケースがあります。

【解決策】

事前に event.getGuestList() を使って現在のゲスト一覧を取得し、「すでにリストに含まれているか」をチェックしてから addGuest() を呼ぶようにすると、無駄な重複処理を防ぐことができます。

6. 今回のまとめと次回予告

今回は、Googleカレンダーの予定にゲストを自動追加する CalendarEvent.addGuest() について学びました。

今日の重要ポイントおさらい

  1. CalendarEvent.addGuest("メールアドレス") は特定の予定に参加者を招待する命令
  2. CalendarApp ではなく、個別の「予定(CalendarEvent)」オブジェクトに対して呼び出す
  3. スプレッドシートのデータと組み合わせることで、メンバー全員の一括自動招待が可能になる
  4. getGuestList() を使うと、招待したメンバーの回答状況(承諾/辞退など)もプログラムから確認できる

これでカレンダーの予定作成から一覧取得、参加者の自動招待まで自由自在にコントロールできるようになりましたね!

さて、カレンダーを運用していると「会議の開催日時が変更になったので、古い重複した予定を削除したい」「中止になったミーティングを自動キャンセルしたい」という場面が出てきます。

そこで次回(第80回)は、カレンダー連携編の締めくくりとして、不要になった予定を自動削除する CalendarEvent.deleteEvent() を解説します!

重複した旧ミーティング予定を綺麗にクリーンアップする自動化処理をマスターしましょう。お楽しみに!