Обзор Google Apps Script и его возможностей для работы с Gmail
Google Apps Script – это облачная платформа для автоматизации задач и расширения функциональности Google Workspace. Она позволяет интегрировать различные сервисы Google, включая Gmail, создавая кастомные решения, например, автоматическую обработку входящей почты, рассылку уведомлений или архивирование писем. Ключевое преимущество – интеграция непосредственно в экосистему Google, что упрощает авторизацию и взаимодействие с другими сервисами.
Необходимые разрешения и авторизация для доступа к почте
Для доступа к Gmail через Google Apps Script требуются соответствующие разрешения. При первом запуске скрипта, обращающегося к Gmail, Google запросит у пользователя разрешение на доступ к почтовому ящику. Эти разрешения необходимо предоставить. В манифесте проекта Apps Script (appsscript.json) можно явно указать необходимые области доступа (scopes), например, https://mail.google.com/ для полного доступа к почте или https://www.googleapis.com/auth/gmail.readonly для доступа только на чтение. Явное указание scopes повышает прозрачность и безопасность.
Установка и настройка Google Apps Script для работы с Gmail
Создать скрипт можно непосредственно в Google Sheets, Docs, Forms, или отдельно через script.google.com. В редакторе Apps Script необходимо подключить сервис Gmail. Это можно сделать либо через автозаполнение (начните писать GmailApp), либо явно указав в манифесте зависимость от Gmail API. Убедитесь, что ваш проект имеет имя и сохранен.
Чтение электронной почты из Gmail с использованием Google Apps Script
Получение доступа к почтовому ящику пользователя
Для работы с Gmail используется класс GmailApp. Он предоставляет методы для доступа к почтовому ящику текущего пользователя. Например:
/**
* Функция для получения текущего почтового ящика.
* @return {GoogleAppsScript.Gmail.GmailApp} Объект GmailApp.
*/
function getGmailApp(): GoogleAppsScript.Gmail.GmailApp {
return GmailApp;
}
const gmailApp: GoogleAppsScript.Gmail.GmailApp = getGmailApp();Использование классов GmailApp и GmailThread
GmailApp позволяет получить доступ к потокам писем (GmailThread) и отдельным сообщениям (GmailMessage). Например, можно получить все потоки писем в ящике:
/**
* Функция для получения всех потоков писем.
* @return {GoogleAppsScript.Gmail.GmailThread[]} Массив объектов GmailThread.
*/
function getAllThreads(): GoogleAppsScript.Gmail.GmailThread[] {
const threads: GoogleAppsScript.Gmail.GmailThread[] = gmailApp.getInboxThreads();
return threads;
}
const allThreads: GoogleAppsScript.Gmail.GmailThread[] = getAllThreads();Фильтрация писем по различным критериям (отправитель, тема, дата и т.д.)
Для фильтрации писем используется метод search() класса GmailApp. Он принимает строку запроса в формате Gmail API. Например, для поиска писем от конкретного отправителя:
/**
* Функция для поиска писем по отправителю.
* @param {string} senderEmail Адрес электронной почты отправителя.
* @return {GoogleAppsScript.Gmail.GmailThread[]} Массив объектов GmailThread, соответствующих критериям поиска.
*/
function findEmailsBySender(senderEmail: string): GoogleAppsScript.Gmail.GmailThread[] {
const query: string = `from:${senderEmail}`;
const threads: GoogleAppsScript.Gmail.GmailThread[] = gmailApp.search(query);
return threads;
}
const sender: string = 'example@example.com';
const threadsFromSender: GoogleAppsScript.Gmail.GmailThread[] = findEmailsBySender(sender);Другие примеры запросов:
subject:"Важный отчет" – поиск писем с темой "Важный отчет".
after:2023/10/26 before:2023/10/28 – поиск писем за определенный период.
label:Unread — поиск непрочитанных писем. (Использование label вместо is:unread более надежно, т.к. labels — это сущности Gmail, а is:unread — это атрибут).
Перебор и чтение содержимого писем (тело письма, вложения)
После получения потока писем, можно получить отдельные сообщения и их содержимое. Например:
/**
* Функция для чтения содержимого первого письма в потоке.
* @param {GoogleAppsScript.Gmail.GmailThread} thread Объект GmailThread.
* @return {string} Текст первого письма в потоке. Возвращает null, если поток пустой.
*/
function getFirstMessageText(thread: GoogleAppsScript.Gmail.GmailThread): string | null {
const messages: GoogleAppsScript.Gmail.GmailMessage[] = thread.getMessages();
if (messages.length > 0) {
const firstMessage: GoogleAppsScript.Gmail.GmailMessage = messages[0];
const messageText: string = firstMessage.getPlainBody();
return messageText;
} else {
return null;
}
}
if (allThreads.length > 0) {
const firstThread: GoogleAppsScript.Gmail.GmailThread = allThreads[0];
const firstMessageContent: string | null = getFirstMessageText(firstThread);
if (firstMessageContent) {
console.log(firstMessageContent);
}
}Для получения вложений используется метод getAttachments() класса GmailMessage.
Работа с потоками писем (Gmail Threads)
Получение потоков писем
Как уже упоминалось, потоки писем можно получить с помощью методов getInboxThreads(), getStarredThreads(), search() и других методов класса GmailApp.
Чтение всех писем в потоке
Чтобы прочитать все письма в потоке, необходимо получить массив GmailMessage с помощью метода getMessages() класса GmailThread, а затем итерироваться по этому массиву, получая содержимое каждого письма.
Ответ на письма в потоке с помощью Google Apps Script
Для ответа на письмо используется метод reply() класса GmailThread. Можно ответить всем участникам потока с помощью replyAll().
/**
* Функция для ответа на поток писем.
* @param {GoogleAppsScript.Gmail.GmailThread} thread Объект GmailThread.
* @param {string} replyText Текст ответа.
*/
function replyToThread(thread: GoogleAppsScript.Gmail.GmailThread, replyText: string): void {
thread.reply(replyText);
}Продвинутые методы чтения электронной почты
Использование поисковых запросов Gmail API для фильтрации писем
Gmail API предоставляет более гибкие возможности для фильтрации писем, чем стандартные методы GmailApp. Можно использовать сложные запросы с операторами AND, OR, NOT. Например, (from:example1@example.com OR from:example2@example.com) subject:"Отчет" -label:Processed.
Работа с метками (Labels) Gmail
Метки позволяют категоризировать письма. Можно получить список всех меток с помощью GmailApp.getUserLabels(), а затем использовать их для фильтрации писем: label:"Имя метки".
/**
* Функция для получения метки по имени.
* @param {string} labelName Имя метки.
* @return {GoogleAppsScript.Gmail.GmailLabel | null} Объект GmailLabel или null, если метка не найдена.
*/
function getLabelByName(labelName: string): GoogleAppsScript.Gmail.GmailLabel | null {
const labels: GoogleAppsScript.Gmail.GmailLabel[] = GmailApp.getUserLabels();
for (const label of labels) {
if (label.getName() === labelName) {
return label;
}
}
return null;
}
/**
* Функция для поиска писем с определенной меткой.
* @param {string} labelName Имя метки.
* @return {GoogleAppsScript.Gmail.GmailThread[]} Массив объектов GmailThread, соответствующих критериям поиска.
*/
function findEmailsByLabel(labelName: string): GoogleAppsScript.Gmail.GmailThread[] {
const label: GoogleAppsScript.Gmail.GmailLabel | null = getLabelByName(labelName);
if (!label) {
console.log(`Label ${labelName} not found`);
return [];
}
const query: string = `label:${label.getName()}`;
const threads: GoogleAppsScript.Gmail.GmailThread[] = GmailApp.search(query);
return threads;
}
const labelName: string = 'Important';
const threadsWithLabel: GoogleAppsScript.Gmail.GmailThread[] = findEmailsByLabel(labelName);Чтение непрочитанных писем
Для чтения непрочитанных писем можно использовать запрос is:unread или более надежный label:Unread. После обработки письма можно отметить его как прочитанное с помощью markRead().
Автоматическая обработка входящих писем (например, создание задач)
С помощью триггеров можно настроить автоматическую обработку входящих писем. Например, при получении письма с определенной темой можно создать задачу в Google Tasks или добавить строку в Google Sheets.
Примеры скриптов для чтения электронной почты
Скрипт для получения списка всех писем от определенного отправителя
/**
* Функция для получения списка всех писем от определенного отправителя.
* @param {string} senderEmail Адрес электронной почты отправителя.
*/
function listEmailsFromSender(senderEmail: string): void {
const threads: GoogleAppsScript.Gmail.GmailThread[] = findEmailsBySender(senderEmail);
for (const thread of threads) {
const messages: GoogleAppsScript.Gmail.GmailMessage[] = thread.getMessages();
for (const message of messages) {
console.log(`Тема: ${message.getSubject()}, Дата: ${message.getDate()}`);
}
}
}
const sender: string = 'example@example.com';
listEmailsFromSender(sender);Скрипт для сохранения вложений из писем на Google Drive
/**
* Функция для сохранения вложений из писем на Google Drive.
* @param {string} senderEmail Адрес электронной почты отправителя.
* @param {string} folderId ID папки на Google Drive.
*/
function saveAttachmentsToDrive(senderEmail: string, folderId: string): void {
const threads: GoogleAppsScript.Gmail.GmailThread[] = findEmailsBySender(senderEmail);
const folder: GoogleAppsScript.Drive.Folder = DriveApp.getFolderById(folderId);
for (const thread of threads) {
const messages: GoogleAppsScript.Gmail.GmailMessage[] = thread.getMessages();
for (const message of messages) {
const attachments: GoogleAppsScript.Gmail.GmailAttachment[] = message.getAttachments();
for (const attachment of attachments) {
folder.createFile(attachment);
}
}
}
}
const sender: string = 'example@example.com';
const folderId: string = 'YOUR_FOLDER_ID';
saveAttachmentsToDrive(sender, folderId);Скрипт для автоматической отправки уведомлений о новых письмах
/**
* Функция для отправки уведомлений о новых письмах.
*/
function sendNewEmailNotification(): void {
const threads: GoogleAppsScript.Gmail.GmailThread[] = GmailApp.search('is:unread');
if (threads.length > 0) {
const emailAddress: string = Session.getActiveUser().getEmail();
const subject: string = 'Уведомление о новом письме';
const body: string = `У вас ${threads.length} новых писем.`;
GmailApp.sendEmail(emailAddress, subject, body);
for (const thread of threads) {
thread.markRead();
}
}
}