【GAS入門#36】届いたメールから添付ファイルを自動抽出!GmailMessage.getAttachments() の使い方と活用ガイド

取引先から届く請求書や、出張先で受け取った領収書のPDFメール。「届くたびに1通ずつメールを開いて、添付ファイルをPCにダウンロードして、指定のフォルダへ保存する……」という単純作業、繰り返していませんか?

メールの件数が増えてくると、毎回のダウンロード作業が面倒なだけでなく、「保存し忘れ」や「二重保存」といったミスも起こりやすくなります。

そこで今回解説するのが、Gmailに届いたメールから添付ファイルをプログラムで一括抽出できる GmailMessage.getAttachments() です!

これまでの記事で学んだ「メール検索」や「メッセージ取得」のテクニックと組み合わせることで、特定のメールに添付されたPDFや画像ファイルを全自動で取り出せるようになります。

「冬の札幌オフィスで毎月届く“除雪費用の請求書PDF”」をテーマに、コード例や実務での応用テクニック、初心者がハマりやすい注意点まで、超わかりやすく解説していきますね!

1. そもそも GmailMessage.getAttachments() とは?

GmailMessage.getAttachments()(ゲット・アタッチメンツ)は、Gmailの特定のメール(1通)についている すべての添付ファイルをまとめて持ってくる命令(メソッド) です。

コードの形を見てみよう

var attachments = message.getAttachments();
  • message:操作したい「1通のメール」(GmailMessageオブジェクト)
  • .getAttachments():「添付されているファイルを全部まとめてちょうだい!」という命令

「手紙と同封物」でイメージしよう!

メールの構造は、お手紙セットに例えると一発で理解できます。

メールでの要素お手紙での例えGASでの取得命令
件名封筒の表書き(タイトル)message.getSubject()
本文封筒の中の手紙(本文)message.getBody()
添付ファイル封筒に一緒に入っている写真や書類message.getAttachments()★今回!

手紙の本文を読むのとは別に、「同封されている書類や写真だけをパッと取り出す操作」こそが、今回の getAttachments() なのです!

2. 【重要用語】超やさしく解説!「Blob」と「MIMEタイプ」ってなに?

添付ファイルを扱うようになると、GASの世界で絶対に避けて通れない2つの専門用語が登場します。ここで完璧にマスターしておきましょう!

① Blob(ブロブ)オブジェクト = 「中身を壊さず運ぶカプセル」

【画像やPDF】 ➔ [ 🔒 Blobカプセル ] ➔ 【Googleドライブへ保存】
  • Blob とは?
    • Binary Large Object の略ですが、覚える必要はありません!
    • イメージとしては 「データの中身(画像・PDF・テキストなど)を崩さずに持ち運ぶための『特製ダンボール(カプセル)』」 です。
  • なぜ Blob が必要なの?
    • プログラムにとって、テキスト文字(「こんにちは」など)と、画像やPDFのデータは扱い方がまったく違います。
    • 「画像データを文字として読み込もうとしたら壊れてしまった!」という事故を防ぐため、GASではファイルを安全に移動・保存できるように「Blobという専用のカプセル」で包んで受け渡す仕組みになっています。

💡 ポイント

getAttachments() で取得したファイル1つ1つは、この 「Blobカプセル」 の状態になっています!

② MIME(マイム)タイプ = 「中身の種類を示す世界共通ラベル」

[ 🔒 Blobカプセル ] 🏷️ ラベル: application/pdf ➔ 「あ、これはPDFだな!」
  • MIMEタイプ とは?
    • 「このファイルが何のデータなのか」 をコンピューター同士で教え合うための世界共通のラベル(識別名)です。
  • 普段使っている「拡張子」との違い
    • 私たちが普段目にする「.pdf」や「.png」はファイル名の末尾につく拡張子です。
    • MIMEタイプは、システム内部で使う正式な分類コードです。

よく使うMIMEタイプの例:

ファイルの種類普段の拡張子MIMEタイプ(GASで取得される文字列)
PDFファイル.pdfapplication/pdf
PNG画像.pngimage/png
JPEG画像.jpg / .jpegimage/jpeg
CSVファイル.csvtext/csv
ZIP圧縮ファイル.zipapplication/zip

3. Gmail操作の4ステップ階層構造

GASでGmailの添付ファイルを取得するときは、以下の4つの階段を順番に下りていきます。

階層1:GmailApp.search("検索条件")
   └─ 条件に合う「スレッド(やり取りのまとまり)」を探す
         ↓
階層2:thread.getMessages()
   └─ スレッドの中から「1通ごとのメール」を取り出す
         ↓
階層3:targetMessage(1通のメール)
   └─ 対象のメールを指定する
         ↓
階層4:message.getAttachments() ★今回!
   └─ メールに付いている「添付ファイル(Blob)」を一括取得!

いきなり添付ファイルに行き着くことはできません。「スレッド ➔ メッセージ ➔ 添付ファイル」という順番を守ることが大切です!

4. STEP1:準備!テストメールを作ろう

実際に動かしてみるために、まずは自分宛てにテストメールを1通送信しましょう。

手順

  1. ご自身のGmailを開きます。
  2. 自分宛て(自分のGmailアドレス)に以下の内容でメールを作成して送信します。
    • 宛先:自分のGmailアドレス
    • 件名:【請求書】2026年1月分_札幌オフィス除雪費用
    • 本文:お世話になっております。今月の除雪費用請求書をPDFで添付いたします。
    • 添付ファイル:PC内にある適当なPDFファイル(画像やテキストファイルでもOK)を1つ添付
  3. 送信後、受信トレイにメールが届いたことを確認してください。

5. STEP2:【実践】添付ファイルの情報をログに表示してみよう!

準備ができたら、GASのプログラムを書いて添付ファイルの情報を読み取ってみましょう!

1. エディタを開く

新規Googleスプレッドシートを開き、上部メニューの 「拡張機能」 > 「Apps Script」 をクリックします。

2. コードを入力する

元々書かれているコードを消して、以下のコードを貼り付けてください。

function getSnowRemovalInvoiceAttachment() {
  // ① 件名に「札幌オフィス除雪費用」が含まれるメールを探す
  var threads = GmailApp.search("subject:札幌オフィス除雪費用");
  
  // メールが見つからなかった場合の安全装置
  if (threads.length === 0) {
    Logger.log("該当するメールが見つかりませんでした。");
    return;
  }
  
  // ② 一番新しいスレッドから「1通目のメール」を取得する
  var messages = threads[0].getMessages();
  var targetMessage = messages[0];
  
  // ③ メールから添付ファイル一覧を取得する(★本日の主役)
  var attachments = targetMessage.getAttachments();
  
  // ④ 添付ファイルが付いているかチェック
  if (attachments.length === 0) {
    Logger.log("メールに添付ファイルが含まれていませんでした。");
    return;
  }
  
  // ⑤ 取得した添付ファイル(Blob)の情報を1個ずつログに出す
  for (var i = 0; i < attachments.length; i++) {
    var file = attachments[i]; // fileの正体は「Blobオブジェクト」
    
    // Blobから情報(名前・サイズ・MIMEタイプ)を引き出す
    var fileName = file.getName();
    var fileSize = file.getSize();        // バイト単位
    var fileType = file.getContentType(); // MIMEタイプ
    
    Logger.log("■ 添付ファイルが見つかりました!");
    Logger.log("・ファイル名: " + fileName);
    Logger.log("・サイズ: " + fileSize + " バイト");
    Logger.log("・形式(MIMEタイプ): " + fileType);
  }
}

3. コードのポイント解説

  • targetMessage.getAttachments()
    • 添付ファイルを配列(リスト)の形で取得します。ファイルが1つだけでも「要素数1の配列」として返ってきます。
  • var file = attachments[i];
    • 配列から取り出した1つ分のファイルデータ(=Blobカプセル)です。
  • file.getName()
    • カプセルの外側に書いてあるファイル名(例:除雪費請求書.pdf)を取得します。
  • file.getSize()
    • ファイルのデータ容量をバイト単位(Byte)で取得します。
  • file.getContentType()
    • ファイルの MIMEタイプ(例:application/pdf)を取得します。

4. 実行する

  1. エディタ上部の 「保存(フロッピーアイコン)」 を押します。
  2. 「実行」 ボタンをクリックします。(初回実行時は画面の指示に従ってアクセス許可を行ってください)

5. 実行結果の確認

エディタ下の「実行ログ」に以下のように表示されれば大成功です!

情報    ■ 添付ファイルが見つかりました!
情報    ・ファイル名: 202601_除雪費請求書.pdf
情報    ・サイズ: 145820 バイト
情報    ・形式(MIMEタイプ): application/pdf

メールを人間が開くことなく、GASが自動で添付ファイルを検出して情報を読み取ってくれました!

6. STEP3:実務で使える!応用パターン3選

実務でそのまま使える発展的な書き方を3つ紹介します。

応用①:PDFファイルだけを選んで処理する(MIMEタイプで判別)

メールに請求書PDFだけでなく、相手の署名画像(ロゴ)などが一緒に添付されていることがあります。MIMEタイプを使って「PDFファイルだけ」を抽出しましょう!

function filterPdfAttachments() {
  var threads = GmailApp.search("subject:札幌オフィス除雪費用");
  if (threads.length === 0) return;
  
  var messages = threads[0].getMessages();
  var attachments = messages[0].getAttachments();
  
  for (var i = 0; i < attachments.length; i++) {
    var file = attachments[i];
    
    // MIMEタイプが application/pdf の場合だけ処理する
    if (file.getContentType() === "application/pdf") {
      Logger.log("【PDFを検出】保存処理へ進みます: " + file.getName());
      // ここにGoogleドライブ保存などの処理を書く
    } else {
      Logger.log("【スキップ】PDF以外のファイルです: " + file.getName());
    }
  }
}

応用②:ファイルが複数あっても一括で取得する

1通のメールに「見積書」「納品書」「請求書」の3つが添付されていても、for ループを使えば漏れなく全件処理できます。

for (var i = 0; i < attachments.length; i++) {
  // (i + 1) で 「1個目」「2個目」 と読みやすく出力
  Logger.log((i + 1) + "個目のファイル: " + attachments[i].getName());
}

応用③:受信した添付ファイルのリストをスプレッドシートに記録する

Sheet.appendRow() と組み合わせれば、「いつ・どのメールから・どんなファイルが届いたか」を全自動で記録する受信管理表が作れます!

function logAttachmentToSheet() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var threads = GmailApp.search("subject:札幌オフィス除雪費用");
  if (threads.length === 0) return;
  
  var message = threads[0].getMessages()[0];
  var attachments = message.getAttachments();
  
  for (var i = 0; i < attachments.length; i++) {
    var file = attachments[i];
    
    // 受信日時, メール件名, ファイル名, サイズ を1行ずつ書き込む
    sheet.appendRow([
      message.getDate(),
      message.getSubject(),
      file.getName(),
      file.getSize()
    ]);
  }
  
  Logger.log("スプレッドシートへ受信ログを書き込みました!");
}

7. 初心者が絶対につまずく!4大トラップと解決策

よくあるトラブルと解決策をまとめました。エラーが出たらここをチェック!

❌ トラップ1:GmailThread に命令を出してエラーになる

  • 間違いのコード:JavaScriptvar attachments = threads[0].getAttachments(); // エラー!
  • 理由:getAttachments() は「スレッド(やり取り全体)」ではなく、「メッセージ(1通のメール)」が持っている命令です。
  • 解決策:必ず threads[0].getMessages()[0].getAttachments() のように、メッセージまで掘り下げてから呼び出しましょう。

❌ トラップ2:添付ファイルがないメールで実行してエラーになる

  • 理由:添付ファイルがないのに attachments[0].getName() を実行すると、「中身がないよ(Cannot read properties of undefined)」とおこられます。
  • 解決策:処理の前に「ファイルが1つ以上あるか」をチェックする条件分岐を入れましょう。JavaScriptif (attachments.length === 0) { Logger.log("添付ファイルはありません。"); return; // 処理を終了 }

❌ トラップ3:Logger.log(attachments[0]) と書いても中身が見えない

  • 理由:attachments[0] の正体はテキストではなく 「Blob(カプセル)」 です。そのままログに出力しても Blob という型名が表示されるだけです。
  • 解決策:ファイル名を知りたいときは .getName()、サイズを知りたいときは .getSize() を使いましょう。

❌ トラップ4:メール内のロゴ画像まで取得されてしまう

  • 理由:メール本文の署名欄などにある「埋め込み画像(インライン画像)」も、デフォルトでは添付ファイルとして一緒に取得されてしまいます。
  • 解決策:手動で添付されたファイルだけを取得したい場合は、オプションで includeInlineImages: false を指定します。JavaScriptvar attachments = message.getAttachments({ includeInlineImages: false // 本文内の埋め込み画像を除外! });

8. まとめ & 次回予告

今回は、メールから添付ファイルを自動取得する GmailMessage.getAttachments() について解説しました。

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

  1. getAttachments() は、1通のメールから添付ファイルを配列でまとめて取得する命令!
  2. 取得できるファイルは Blob(データが入った特製カプセル) の形をしている!
  3. getContentType() で取得できる MIMEタイプ(application/pdf など)を使えば、特定ファイルだけを判別できる!

これでメールの件名や本文だけでなく、同封されている添付ファイルまで自由自在に扱えるようになりました!

次回は、処理が終わったメールを自動で整理する GmailThread.addLabel() を解説します!

「処理済み請求書」といったラベルをGASで自動付与して、受信トレイをいつでもスッキリ整理整頓するテクニックを学びましょう。お楽しみに!