Node.js の googleapis パッケージを使って Gmail API 経由でメールを送信するとき、users.messages.send に渡すリクエストボディの raw フィールドにはどのような形式の値を入れる必要がありますか？

解説

Gmail API の users.messages.send エンドポイントは、メール本文を「RFC 2822（現在は RFC 5322 に更新）形式の生メッセージ」として受け取ります。これは From:・To:・Subject: などのヘッダーと本文を改行で区切った、メールサーバー間でやり取りされる標準フォーマットそのものです。さらに API の仕様上、この生メッセージをbase64url エンコード（通常の base64 から + を -、/ を _ に置き換えたバリアント）した文字列を raw フィールドに渡す必要があります。選択肢Aのような構造化 JSON は受け付けません。選択肢Cの素のテキストではヘッダー情報が欠落します。選択肢Dの multipart/form-data は HTML フォーム送信用の形式で、Gmail API とは別物です。実際の送信コード例googleapis パッケージを使った最小構成は次のようになります。import { google } from 'googleapis'; const gmail = google.gmail({ version: 'v1', auth: oauth2Client }); const message = [ 'To: recipient@example.com', 'Subject: =?UTF-8?B?' + Buffer.from('テスト送信').toString('base64') + '?=', 'Content-Type: text/plain; charset=UTF-8', '', '本文です。', ].join('\r\n'); const encodedMessage = Buffer.from(message) .toString('base64') .replace(/\+/g, '-') .replace(/\//g, '_') .replace(/=+$/, ''); await gmail.users.messages.send({ userId: 'me', requestBody: { raw: encodedMessage }, });ポイントは3つあります。ヘッダーと本文の区切りは空行（CRLF を2つ）で、これがないとパース失敗します。日本語の Subject は MIME エンコード（=?UTF-8?B?...?=）が必要です。そして base64 標準の + / = を URL セーフな文字に置換するのが base64url です。nodemailer と組み合わせる現実的な選択肢上のように生メッセージを手で組み立てるのは面倒で、特に添付ファイル付きや HTML メールでは MIME マルチパートを正しく構築する必要があります。実務では nodemailer でメッセージオブジェクトを生成し、compile().build() で RFC 準拠のバッファを取得してから base64url エンコードする方法がよく使われます。googleapis 単体: 軽量だが MIME を自前で組み立てる必要ありgoogleapis + nodemailer: 添付・HTML・複数宛先などを楽に扱える「Gmail API がなぜ JSON ではなく生メッセージを要求するのか」と疑問に思うかもしれませんが、これは Gmail がメールサーバーとして RFC 準拠のメッセージをそのまま保存・転送する設計だからです。API はあくまで送信口であり、メールの実体は標準フォーマットに従う必要がある、と理解すると腑に落ちます。