Turn Gmail into a smart, self-labelling inbox

/**
 * Maverick Smart Gmail Organizer — Public Edition
 * Version 1.0.0
 *
 * What it does:
 * - Applies useful labels to recent inbox threads using Gmail search rules.
 * - Gives VIP and action-needed messages extra visibility.
 * - Can run automatically every hour with an installable trigger.
 *
 * What it never does:
 * - It does not delete email.
 * - It does not send or forward email.
 * - It does not transmit message data anywhere.
 *
 * Start safely:
 * 1. Add your important email addresses and keywords below.
 * 2. Run previewSmartInbox() and review the execution log.
 * 3. Run setupSmartInbox() once and approve Google's permission prompt.
 */

const SMART_INBOX = {
  lookbackDays: 30,
  maxThreadsPerRule: 100,
  labelPrefix: 'Smart Inbox',

  // Replace these examples. Leave the arrays empty if you do not need them.
  vipSenders: [
    'important.client@example.com',
    'accounts@yourcompany.com',
  ],
  actionKeywords: [
    'action required',
    'approval needed',
    'please confirm',
    'deadline',
  ],
};

function buildSmartInboxRules_() {
  const vipQuery = SMART_INBOX.vipSenders.length
    ? `{${SMART_INBOX.vipSenders.map(address => `from:${address}`).join(' ')}}`
    : 'is:important';

  const keywordQuery = SMART_INBOX.actionKeywords.length
    ? `{${SMART_INBOX.actionKeywords.map(keyword => `\"${keyword}\"`).join(' ')}}`
    : '{\"action required\" \"please confirm\"}';

  return [
    {
      label: '01 — VIP',
      query: `in:inbox ${vipQuery}`,
      markImportant: true,
      star: true,
    },
    {
      label: '02 — Action needed',
      query: `in:inbox ${keywordQuery}`,
      markImportant: true,
      star: false,
    },
    {
      label: '03 — Money',
      query: 'in:inbox {subject:(invoice receipt payment paid due quotation estimate) from:(razorpay.com stripe.com paypal.com)}',
      markImportant: false,
      star: false,
    },
    {
      label: '04 — Meetings',
      query: 'in:inbox {subject:(meeting invite schedule reschedule appointment webinar) filename:ics}',
      markImportant: false,
      star: false,
    },
    {
      label: '05 — Orders & delivery',
      query: 'in:inbox subject:(order shipped dispatch delivered tracking purchase)',
      markImportant: false,
      star: false,
    },
    {
      label: '06 — Travel',
      query: 'in:inbox {subject:(booking itinerary ticket flight hotel train) filename:pdf filename:pkpass}',
      markImportant: false,
      star: false,
    },
    {
      label: '07 — Documents',
      query: 'in:inbox has:attachment {filename:pdf filename:doc filename:docx filename:xls filename:xlsx filename:csv filename:ppt filename:pptx}',
      markImportant: false,
      star: false,
    },
    {
      label: '08 — Updates',
      query: 'in:inbox {category:updates category:forums}',
      markImportant: false,
      star: false,
    },
    {
      label: '09 — Read later',
      query: 'in:inbox category:promotions -is:important',
      markImportant: false,
      star: false,
    },
  ];
}

/** Preview how many threads each rule currently matches. Makes no changes. */
function previewSmartInbox() {
  const rules = buildSmartInboxRules_();
  rules.forEach(rule => {
    const threads = GmailApp.search(withLookback_(rule.query), 0, SMART_INBOX.maxThreadsPerRule);
    console.log(`${rule.label}: ${threads.length} matching thread(s)`);
  });
}

/** Apply labels and visibility actions to matching recent inbox threads. */
function organizeSmartInbox() {
  const rules = buildSmartInboxRules_();

  rules.forEach(rule => {
    const label = getOrCreateLabel_(fullLabelName_(rule.label));
    const threads = GmailApp.search(withLookback_(rule.query), 0, SMART_INBOX.maxThreadsPerRule);

    if (!threads.length) return;

    label.addToThreads(threads);
    if (rule.markImportant) threads.forEach(thread => thread.markImportant());
    if (rule.star) threads.forEach(thread => {
      const messages = thread.getMessages();
      messages[messages.length - 1].star();
    });

    console.log(`${rule.label}: organized ${threads.length} thread(s)`);
  });
}

/** Run once: create labels, organize now, and install one hourly trigger. */
function setupSmartInbox() {
  buildSmartInboxRules_().forEach(rule => getOrCreateLabel_(fullLabelName_(rule.label)));
  removeOrganizerTriggers_();
  ScriptApp.newTrigger('organizeSmartInbox').timeBased().everyHours(1).create();
  organizeSmartInbox();
  console.log('Smart Inbox is ready and will run approximately every hour.');
}

/** Stop automation. Existing labels and labeled messages stay untouched. */
function stopSmartInboxAutomation() {
  const removed = removeOrganizerTriggers_();
  console.log(`Stopped Smart Inbox automation. Removed ${removed} trigger(s).`);
}

function withLookback_(query) {
  return `${query} newer_than:${SMART_INBOX.lookbackDays}d`;
}

function fullLabelName_(name) {
  return `${SMART_INBOX.labelPrefix}/${name}`;
}

function getOrCreateLabel_(name) {
  return GmailApp.getUserLabelByName(name) || GmailApp.createLabel(name);
}

function removeOrganizerTriggers_() {
  let removed = 0;
  ScriptApp.getProjectTriggers().forEach(trigger => {
    if (trigger.getHandlerFunction() === 'organizeSmartInbox') {
      ScriptApp.deleteTrigger(trigger);
      removed += 1;
    }
  });
  return removed;
}