سرویس پیشرفته جیمیل

سرویس پیشرفته جیمیل به شما امکان می‌دهد از API جیمیل در Apps Script استفاده کنید. این API، بسیار شبیه به سرویس جیمیل داخلی Apps Script، به اسکریپت‌ها اجازه می‌دهد تا موضوعات، پیام‌ها و برچسب‌ها را در صندوق پستی جیمیل پیدا و تغییر دهند. در بیشتر موارد، استفاده از سرویس داخلی آسان‌تر است، اما این سرویس پیشرفته چند ویژگی اضافی و دسترسی به اطلاعات دقیق‌تر در مورد محتوای جیمیل را فراهم می‌کند.

مرجع

برای اطلاعات دقیق در مورد این سرویس، به مستندات مرجع برای Gmail API مراجعه کنید. مانند تمام سرویس‌های پیشرفته در Apps Script، سرویس پیشرفته Gmail از همان اشیاء، متدها و پارامترهای API عمومی استفاده می‌کند. برای اطلاعات بیشتر، به بخش «نحوه تعیین امضاهای متد» مراجعه کنید.

برای گزارش مشکلات و یافتن پشتیبانی‌های دیگر، به راهنمای پشتیبانی Gmail مراجعه کنید.

کد نمونه

کد نمونه زیر از نسخه ۱ این API استفاده می‌کند.

اطلاعات برچسب فهرست

مثال زیر نحوه‌ی فهرست کردن تمام اطلاعات برچسب کاربر را نشان می‌دهد. این شامل نام برچسب، نوع، شناسه و تنظیمات نمایش آن می‌شود.

پیشرفته/gmail.gs
/**
 * Lists the user's labels, including name, type,
 * ID and visibility information.
 */
function listLabelInfo() {
  try {
    const response = Gmail.Users.Labels.list("me");
    for (let i = 0; i < response.labels.length; i++) {
      const label = response.labels[i];
      console.log(JSON.stringify(label));
    }
  } catch (err) {
    console.log(err);
  }
}

فهرست کردن اسنیپت‌های صندوق ورودی

مثال زیر نحوه فهرست کردن قطعه متن‌های مرتبط با هر رشته در صندوق ورودی کاربر را نشان می‌دهد. به استفاده از توکن‌های صفحه برای دسترسی به لیست کامل نتایج توجه کنید.

پیشرفته/gmail.gs
/**
 * Lists, for each thread in the user's Inbox, a
 * snippet associated with that thread.
 */
function listInboxSnippets() {
  try {
    let pageToken;
    do {
      const threadList = Gmail.Users.Threads.list("me", {
        q: "label:inbox",
        pageToken: pageToken,
      });
      if (threadList.threads && threadList.threads.length > 0) {
        for (const thread of threadList.threads) {
          console.log(`Snippet: ${thread.snippet}`);
        }
      }
      pageToken = threadList.nextPageToken;
    } while (pageToken);
  } catch (err) {
    console.log(err);
  }
}

فهرست کردن تاریخ اخیر

مثال زیر نحوه ثبت تاریخچه فعالیت‌های اخیر را نشان می‌دهد. به طور خاص، این مثال شناسه رکورد تاریخچه مرتبط با آخرین پیام ارسال شده کاربر را بازیابی می‌کند و سپس شناسه‌های پیام هر پیامی را که از آن زمان تغییر کرده است، ثبت می‌کند. هر پیام تغییر یافته فقط یک بار ثبت می‌شود، مهم نیست که چند رویداد تغییر در رکوردهای تاریخچه وجود داشته باشد. به استفاده از توکن‌های صفحه برای دسترسی به لیست کامل نتایج توجه کنید.

پیشرفته/gmail.gs
/**
 * Gets a history record ID associated with the most
 * recently sent message, then logs all the message IDs
 * that have changed since that message was sent.
 */
function logRecentHistory() {
  try {
    // Get the history ID associated with the most recent
    // sent message.
    const sent = Gmail.Users.Threads.list("me", {
      q: "label:sent",
      maxResults: 1,
    });
    if (!sent.threads || !sent.threads[0]) {
      console.log("No sent threads found.");
      return;
    }
    const historyId = sent.threads[0].historyId;

    // Log the ID of each message changed since the most
    // recent message was sent.
    let pageToken;
    const changed = [];
    do {
      const recordList = Gmail.Users.History.list("me", {
        startHistoryId: historyId,
        pageToken: pageToken,
      });
      const history = recordList.history;
      if (history && history.length > 0) {
        for (const record of history) {
          for (const message of record.messages) {
            if (changed.indexOf(message.id) === -1) {
              changed.push(message.id);
            }
          }
        }
      }
      pageToken = recordList.nextPageToken;
    } while (pageToken);

    for (const id of changed) {
      console.log("Message Changed: %s", id);
    }
  } catch (err) {
    console.log(err);
  }
}

لیست کردن پیام‌ها

مثال زیر نحوه فهرست کردن پیام‌های خوانده نشده کاربر Gmail را نشان می‌دهد.

پیشرفته/gmail.gs
/**
 * Lists unread messages in the user's inbox using the advanced Gmail service.
 */
function listMessages() {
  // The special value 'me' indicates the authenticated user.
  const userId = "me";

  // Define optional parameters for the request.
  const options = {
    maxResults: 10, // Limit the number of messages returned.
    q: "is:unread", // Search for unread messages.
  };

  try {
    // Call the Gmail.Users.Messages.list method.
    const response = Gmail.Users.Messages.list(userId, options);
    const messages = response.messages;
    console.log("Unread Messages:");

    for (const message of messages) {
      console.log(`- Message ID: ${message.id}`);
    }
  } catch (err) {
    // Log any errors to the Apps Script execution log.
    console.log(`Failed with error: ${err.message}`);
  }
}