Auto-Archive Gmail Emails with Apps Script: Keep Your Inbox Clean Automatically

A cluttered Gmail inbox is one of those productivity problems that everyone acknowledges, few people solve properly, and most people manage by sheer habit. You archive manually when things get bad. You set up a filter that half-works. You declare inbox zero on a Friday afternoon and lose it again by Monday. The problem is not discipline — it is that inbox maintenance is a repetitive, mechanical task that should not require a human to perform.

Google Apps Script solves this permanently. Using the GmailApp service built into every Google Workspace account, you can write scripts that search your inbox, identify emails matching specific criteria, and archive, label, or trash them automatically — on a schedule that runs whether or not you are at your desk.

This guide covers everything you need to build a practical inbox automation system: how the GmailApp class works, how to search and archive threads, how to build label-based and sender-based rules, how to tell the difference between archiving and moving to trash, how to schedule scripts with time-based triggers, and how to log every action to a Google Sheet for a clear audit trail. Three complete, ready-to-deploy scripts are included that you can adapt to your inbox today.

Understanding the GmailApp Class

Before writing any code, it helps to understand how Apps Script talks to Gmail. The GmailApp service is the built-in Apps Script class that provides methods for interacting with your Gmail account: searching threads, reading messages, applying labels, moving items to the archive or trash, and sending email.

The fundamental model in Gmail automation is threads, not individual messages. A Gmail thread is a conversation — a group of related messages that Gmail keeps together. When you archive in the Gmail interface, you are archiving a thread. Apps Script works the same way: most GmailApp operations act on GmailThread objects, with individual GmailMessage objects available when you need to inspect the content of a specific email.

The key methods you will use throughout this guide are:

• GmailApp.search(query) — Searches your Gmail using the same search syntax as the Gmail search bar, and returns an array of GmailThread objects matching that query.
• GmailApp.search(query, start, max) — The same as above, but with pagination. start is the result index to begin from, and max is the maximum number of results to return (capped at 500 per call).
• thread.moveToArchive() — Moves the thread out of the inbox without deleting it. The thread is still searchable and accessible in All Mail.
• thread.moveToTrash() — Moves the thread to the Trash. It will be permanently deleted after 30 days unless you empty Trash manually.
• thread.addLabel(label) — Applies a Gmail label to the thread. Labels must be retrieved first using GmailApp.getUserLabelByName().
• thread.removeLabel(label) — Removes a label from the thread.
• GmailApp.createLabel(name) — Creates a new Gmail label if one does not already exist.

The search query string follows Gmail's standard search operator syntax. If you can type it into the Gmail search bar, you can pass it to GmailApp.search(). Common operators for inbox automation include:

You can combine operators: from:notifications@linkedin.com older_than:3d in:inbox is:read would match read LinkedIn notification emails that have been in your inbox for more than three days.

Setting Up the Script Environment

All scripts in this guide use the same setup. Open script.google.com in your browser while signed into your Google Workspace account, click New project, and name it something like "Gmail Auto-Archive". You can also open the script editor directly from Gmail by clicking the Apps Script option in Google Workspace, though using script.google.com as a standalone project is cleaner for automation scripts.

When you run any GmailApp script for the first time, Google will prompt you to authorise the permissions it needs. Gmail automation scripts typically require:

• Read, compose, send, and permanently delete all your email from Gmail — the broadest Gmail scope, required for searching, reading, and archiving threads
• See and edit your spreadsheets — required only if your script logs to Google Sheets

Click Review permissions, choose your account, then Allow. This authorisation is a one-time step per script project.

Script 1: Archive Newsletters Older Than 7 Days

The most common inbox clutter problem is newsletters. You subscribe to them with good intentions. You read some of them. The ones you do not read accumulate and bury everything else.

This script finds all read emails in your inbox tagged with the Gmail label "Newsletters" that are older than seven days and archives them.

function archiveOldNewsletters() {
  var LABEL_NAME = 'Newsletters';
  var DAYS_OLD = 7;

  // Build the search query
  var query = 'label:' + LABEL_NAME +
              ' older_than:' + DAYS_OLD + 'd' +
              ' in:inbox' +
              ' is:read';

  // Search returns up to 500 threads by default
  var threads = GmailApp.search(query);

  if (threads.length === 0) {
    Logger.log('No newsletter threads found matching criteria.');
    return;
  }

  var archivedCount = 0;
  var errors = [];

  for (var i = 0; i < threads.length; i++) {
    try {
      threads[i].moveToArchive();
      archivedCount++;
    } catch (e) {
      errors.push('Thread ' + i + ': ' + e.message);
    }
  }

  Logger.log(
    'Newsletter archive complete. Archived: ' + archivedCount +
    ', Errors: ' + errors.length
  );

  if (errors.length > 0) {
    Logger.log('Errors: ' + errors.join('\n'));
  }
}

To use this script, first make sure you have a Gmail label called "Newsletters" (or update LABEL_NAME to match the label you actually use). The search query combines four conditions: the label, the age, the inbox location, and the read status. All four must match — this means unread newsletters are left alone, and newsletters you have already archived will not be counted again.

Handling large inboxes with pagination

If you have more than 500 matching threads, GmailApp.search() will only return the first 500. For inboxes with significant backlogs, loop through results in batches:

function archiveOldNewslettersBatched() {
  var LABEL_NAME = 'Newsletters';
  var DAYS_OLD = 7;
  var BATCH_SIZE = 100;

  var query = 'label:' + LABEL_NAME +
              ' older_than:' + DAYS_OLD + 'd' +
              ' in:inbox' +
              ' is:read';

  var start = 0;
  var totalArchived = 0;

  while (true) {
    var threads = GmailApp.search(query, start, BATCH_SIZE);

    if (threads.length === 0) {
      break; // No more results
    }

    for (var i = 0; i < threads.length; i++) {
      try {
        threads[i].moveToArchive();
        totalArchived++;
      } catch (e) {
        Logger.log('Error archiving thread: ' + e.message);
      }
    }

    // If fewer results than batch size, we have reached the end
    if (threads.length < BATCH_SIZE) {
      break;
    }

    start += BATCH_SIZE;

    // Pause briefly to avoid hitting API rate limits
    Utilities.sleep(500);
  }

  Logger.log('Total archived: ' + totalArchived);
}

The Utilities.sleep(500) call pauses for 500 milliseconds between batches. This prevents the script from hitting Gmail's API rate limits, which can cause errors on large batch operations. For a typical inbox cleanup, you will not need this — but for a first-run archive on an inbox with thousands of old emails, batching with a small delay is good practice.

Script 2: Archive Read Emails from Specific Senders

Some senders reliably produce emails that serve a short-term purpose — shipping notifications, calendar event confirmations, weekly digests from apps you use. Once you have read them, they have no ongoing value. This script archives read emails from a configurable list of senders after a specified number of days.

function archiveReadEmailsBySender() {
  // Add sender addresses or domains you want to auto-archive
  var SENDERS = [
    'noreply@uber.com',
    'no-reply@airbnb.com',
    'notifications@trello.com',
    'noreply@dropbox.com',
    'receipts@stripe.com',
  ];

  var DAYS_OLD = 3;   // Archive read emails older than this many days
  var archivedCount = 0;
  var errors = [];

  for (var s = 0; s < SENDERS.length; s++) {
    var sender = SENDERS[s];

    var query = 'from:' + sender +
                ' older_than:' + DAYS_OLD + 'd' +
                ' in:inbox' +
                ' is:read';

    try {
      var threads = GmailApp.search(query);

      for (var i = 0; i < threads.length; i++) {
        try {
          threads[i].moveToArchive();
          archivedCount++;
        } catch (e) {
          errors.push('Error archiving from ' + sender + ': ' + e.message);
        }
      }

      Logger.log('Archived ' + threads.length + ' thread(s) from: ' + sender);

    } catch (e) {
      errors.push('Search failed for sender ' + sender + ': ' + e.message);
    }
  }

  Logger.log(
    'Sender archive complete. Total archived: ' + archivedCount +
    ', Errors: ' + errors.length
  );
}

Archiving by subject pattern

You can also target emails by subject line keyword rather than sender. This is useful when a single sender sends both important and archivable emails:

function archiveBySubjectPattern() {
  // Subject patterns to auto-archive (case-insensitive in Gmail search)
  var SUBJECT_PATTERNS = [
    'subject:"Your order has shipped"',
    'subject:"Receipt for your payment"',
    'subject:"Your weekly digest"',
    'subject:"You have a new follower"',
  ];

  var DAYS_OLD = 5;
  var archivedCount = 0;

  for (var p = 0; p < SUBJECT_PATTERNS.length; p++) {
    var query = SUBJECT_PATTERNS[p] +
                ' older_than:' + DAYS_OLD + 'd' +
                ' in:inbox' +
                ' is:read';

    var threads = GmailApp.search(query);

    for (var i = 0; i < threads.length; i++) {
      try {
        threads[i].moveToArchive();
        archivedCount++;
      } catch (e) {
        Logger.log('Error: ' + e.message);
      }
    }
  }

  Logger.log('Subject pattern archive complete. Archived: ' + archivedCount);
}

Note that Gmail search operators match across the entire message thread, not just the most recent message. A thread that started with a subject matching your pattern but has since had replies added with different subject lines may still appear in results.

Archiving vs Moving to Trash: What Is the Difference?

This is a question worth answering clearly before you write any script that permanently affects your email.

Archiving (thread.moveToArchive()) removes the thread from your inbox and the "Inbox" label, but the thread remains in your account indefinitely. It is fully searchable under "All Mail". Nothing is deleted. If someone replies to an archived thread, the new message reappears in your inbox as a new thread. Archiving is reversible — you can search for the thread and move it back to your inbox at any time.

Moving to Trash (thread.moveToTrash()) moves the thread to your Trash. Gmail permanently deletes trashed emails after 30 days. This action is recoverable within that 30-day window, but not after.

The practical rule for automated scripts: Archive by default. Only move to Trash when you are certain the content has no future value — for example, promotional emails older than 30 days with no meaningful content. Never trash emails that could contain purchase records, correspondence with clients, or anything that might be needed for compliance, tax, or legal purposes.

For Australian businesses, the ATO recommends keeping business records for a minimum of five years. An Apps Script that inadvertently trashes supplier invoices or client emails is a far more serious problem than a cluttered inbox. Stick to moveToArchive() for automated rules unless you have explicitly verified that a category of email is genuinely disposable.

Label-Based Archiving

Labels are Gmail's organisational system, and combining label-based rules with Apps Script gives you a powerful way to manage email categories independently. The pattern is: Gmail filters apply labels automatically as email arrives; your Apps Script then acts on those labelled threads according to age, read status, or other criteria.

This script demonstrates label-based archiving for multiple categories at once:

function labelBasedArchive() {
  // Define rules: label name and how many days before archiving
  var ARCHIVE_RULES = [
    { label: 'Newsletters',     daysOld: 7,  requireRead: true  },
    { label: 'Notifications',   daysOld: 3,  requireRead: true  },
    { label: 'Receipts',        daysOld: 30, requireRead: false }, // Archive receipts regardless of read status
    { label: 'Social',          daysOld: 5,  requireRead: true  },
    { label: 'Weekly-Digests',  daysOld: 7,  requireRead: false },
  ];

  var totalArchived = 0;
  var summary = [];

  for (var r = 0; r < ARCHIVE_RULES.length; r++) {
    var rule = ARCHIVE_RULES[r];
    var labelObj = GmailApp.getUserLabelByName(rule.label);

    // Skip this rule if the label does not exist in Gmail
    if (!labelObj) {
      Logger.log('Label not found, skipping: ' + rule.label);
      continue;
    }

    var query = 'label:' + rule.label +
                ' older_than:' + rule.daysOld + 'd' +
                ' in:inbox';

    if (rule.requireRead) {
      query += ' is:read';
    }

    var threads = GmailApp.search(query);
    var ruleArchived = 0;

    for (var i = 0; i < threads.length; i++) {
      try {
        threads[i].moveToArchive();
        ruleArchived++;
        totalArchived++;
      } catch (e) {
        Logger.log('Error on label ' + rule.label + ': ' + e.message);
      }
    }

    summary.push(rule.label + ': ' + ruleArchived + ' archived');
  }

  Logger.log('=== Label Archive Summary ===');
  Logger.log(summary.join('\n'));
  Logger.log('Total archived: ' + totalArchived);
}

The requireRead flag in each rule object gives you fine-grained control. Receipts are archived regardless of whether you have read them (after 30 days, you have either dealt with the purchase or you have not). Social media notifications are only archived if read — an unread one from seven days ago might still be relevant.

Creating a label programmatically

If you want your script to create a label that does not yet exist rather than silently skipping it:

function getOrCreateLabel(labelName) {
  var label = GmailApp.getUserLabelByName(labelName);
  if (!label) {
    label = GmailApp.createLabel(labelName);
    Logger.log('Created new label: ' + labelName);
  }
  return label;
}

Call getOrCreateLabel('Newsletters') instead of GmailApp.getUserLabelByName('Newsletters') wherever you need a label reference, and the script will create the label automatically on first run.

Logging Actions to a Google Sheet

When automated scripts modify your email, visibility matters. A Google Sheet audit log tells you exactly what was archived, when, and why — so you can verify the script is behaving correctly, investigate if something goes missing, and adjust rules based on real data.

This function writes archive actions to a Sheet named "Archive Log" in a designated spreadsheet:

function logArchiveAction(spreadsheetId, label, sender, subject, dateArchived, action) {
  var ss = SpreadsheetApp.openById(spreadsheetId);
  var sheet = ss.getSheetByName('Archive Log');

  // Create the sheet if it does not exist
  if (!sheet) {
    sheet = ss.insertSheet('Archive Log');
    // Add header row
    sheet.appendRow([
      'Timestamp',
      'Label / Rule',
      'Sender',
      'Subject',
      'Email Date',
      'Action'
    ]);
    // Freeze header row
    sheet.setFrozenRows(1);
  }

  sheet.appendRow([
    new Date(),       // Timestamp of the archive action
    label,            // Which rule triggered the archive
    sender,           // The from address
    subject,          // Email subject
    dateArchived,     // Date the email was received
    action            // 'Archived' or 'Trashed'
  ]);
}

To use this logging function, you need the ID of a Google Spreadsheet. Navigate to any spreadsheet and copy the long string from the URL between /spreadsheets/d/ and the next /. For example, in https://docs.google.com/spreadsheets/d/1aBcDeFgHiJkLmNoPqRsTuVwXyZ/edit, the ID is 1aBcDeFgHiJkLmNoPqRsTuVwXyZ.

Here is a complete version of Script 1 (archive old newsletters) with full logging integrated:

function archiveNewslettersWithLogging() {
  var SPREADSHEET_ID = 'YOUR_SPREADSHEET_ID_HERE';
  var LABEL_NAME = 'Newsletters';
  var DAYS_OLD = 7;

  var query = 'label:' + LABEL_NAME +
              ' older_than:' + DAYS_OLD + 'd' +
              ' in:inbox' +
              ' is:read';

  var threads = GmailApp.search(query);
  var archivedCount = 0;

  for (var i = 0; i < threads.length; i++) {
    var thread = threads[i];

    try {
      // Get details of the most recent message in the thread
      var messages = thread.getMessages();
      var latestMessage = messages[messages.length - 1];
      var sender = latestMessage.getFrom();
      var subject = thread.getFirstMessageSubject();
      var emailDate = latestMessage.getDate();

      // Archive the thread
      thread.moveToArchive();
      archivedCount++;

      // Log the action to the Sheet
      logArchiveAction(
        SPREADSHEET_ID,
        LABEL_NAME,
        sender,
        subject,
        emailDate,
        'Archived'
      );

    } catch (e) {
      Logger.log('Error processing thread ' + i + ': ' + e.message);
    }
  }

  Logger.log('Archived ' + archivedCount + ' newsletter thread(s).');
}

The thread.getFirstMessageSubject() method returns the subject of the first message in the thread, which is what Gmail displays in the inbox list. The latestMessage.getFrom() method returns the sender of the most recent reply, which is typically the most useful for audit purposes.

Keeping the log sheet manageable

A log sheet that captures every archival event will grow quickly. Add a periodic cleanup function that deletes rows older than 90 days, or simply create monthly-named log sheets and start a new one each month. For compliance-sensitive environments, consider keeping a permanent record by never deleting log entries — the Sheet will remain manageable as long as you are only logging archive events (not reading every email).

Script 3: Weekly Inbox Cleanup

This script combines all the techniques above into a single weekly cleanup function that runs a configurable set of archive rules and writes a summary to both the log and a weekly email report.

function weeklyInboxCleanup() {
  var SPREADSHEET_ID = 'YOUR_SPREADSHEET_ID_HERE';
  var REPORT_EMAIL = 'you@yourdomain.com.au';

  var rules = [
    {
      name:        'Old Newsletters',
      query:       'label:Newsletters older_than:7d in:inbox is:read',
      action:      'archive'
    },
    {
      name:        'Read Notifications',
      query:       'label:Notifications older_than:3d in:inbox is:read',
      action:      'archive'
    },
    {
      name:        'Shipping Updates',
      query:       'subject:"has been shipped" older_than:14d in:inbox is:read',
      action:      'archive'
    },
    {
      name:        'LinkedIn Notifications',
      query:       'from:notifications@linkedin.com older_than:5d in:inbox is:read',
      action:      'archive'
    },
    {
      name:        'Old Promotional Emails',
      query:       'category:promotions older_than:14d in:inbox is:read',
      action:      'archive'
    },
  ];

  var totalArchived = 0;
  var reportLines = ['=== Weekly Inbox Cleanup Report ===', ''];

  for (var r = 0; r < rules.length; r++) {
    var rule = rules[r];
    var ruleCount = 0;

    try {
      var threads = GmailApp.search(rule.query);

      for (var i = 0; i < threads.length; i++) {
        var thread = threads[i];

        try {
          var messages  = thread.getMessages();
          var latest    = messages[messages.length - 1];
          var sender    = latest.getFrom();
          var subject   = thread.getFirstMessageSubject();
          var emailDate = latest.getDate();

          if (rule.action === 'archive') {
            thread.moveToArchive();
          } else if (rule.action === 'trash') {
            thread.moveToTrash();
          }

          // Log each action
          logArchiveAction(
            SPREADSHEET_ID,
            rule.name,
            sender,
            subject,
            emailDate,
            rule.action === 'archive' ? 'Archived' : 'Trashed'
          );

          ruleCount++;
          totalArchived++;

        } catch (e) {
          Logger.log('Error on thread in rule "' + rule.name + '": ' + e.message);
        }
      }

    } catch (e) {
      Logger.log('Search failed for rule "' + rule.name + '": ' + e.message);
    }

    reportLines.push(rule.name + ': ' + ruleCount + ' thread(s) archived');
  }

  reportLines.push('');
  reportLines.push('Total threads archived this run: ' + totalArchived);
  reportLines.push('Log: https://docs.google.com/spreadsheets/d/' + SPREADSHEET_ID);

  var reportBody = reportLines.join('\n');
  Logger.log(reportBody);

  // Send a summary email if anything was archived
  if (totalArchived > 0) {
    GmailApp.sendEmail(
      REPORT_EMAIL,
      'Weekly Inbox Cleanup: ' + totalArchived + ' thread(s) archived',
      reportBody
    );
  }
}

Replace YOUR_SPREADSHEET_ID_HERE with your actual spreadsheet ID and you@yourdomain.com.au with the address where you want to receive the weekly summary. The summary email is only sent if at least one thread was archived — you will not receive a blank report on weeks when everything is already clean.

Scheduling with Time-Based Triggers

Scripts that run on a schedule are the difference between automation and manual work. Apps Script's trigger system lets any function run automatically on a recurring basis.

Setting up a trigger via the Apps Script editor:

1. In your Apps Script project, click the clock icon in the left sidebar (Triggers).
2. Click Add Trigger in the bottom right corner.
3. Configure the trigger settings:
4. Function to run: Select the function name from the dropdown (e.g. weeklyInboxCleanup)
5. Deployment: Head deployment
6. Event source: Time-driven
7. Time-based trigger type: Week timer (for weekly runs) or Day timer (for daily)
8. Day of week (if weekly): Sunday or Monday morning
9. Time of day: Choose an overnight window like 3am–4am, when your inbox is unlikely to be in active use
10. Click Save.

Recommended trigger schedules:

Setting up triggers programmatically:

If you want to deploy the trigger setup in code rather than through the UI — useful when setting up the same script across multiple Google accounts:

function createArchiveTriggers() {
  // Remove any existing triggers first to avoid duplicates
  var existingTriggers = ScriptApp.getProjectTriggers();
  for (var i = 0; i < existingTriggers.length; i++) {
    ScriptApp.deleteTrigger(existingTriggers[i]);
  }

  // Daily newsletter archive at 3am
  ScriptApp.newTrigger('archiveOldNewsletters')
    .timeBased()
    .everyDays(1)
    .atHour(3)
    .create();

  // Weekly full cleanup on Sunday at 4am
  ScriptApp.newTrigger('weeklyInboxCleanup')
    .timeBased()
    .onWeekDay(ScriptApp.WeekDay.SUNDAY)
    .atHour(4)
    .create();

  Logger.log('Triggers created successfully.');
}

Run createArchiveTriggers() once from the Apps Script editor and both triggers will be registered. Verify them by returning to the Triggers panel.

A note on execution time limits

Apps Script imposes a maximum execution time of six minutes per script run for standard Google Workspace accounts, and 30 minutes for Workspace Business plans. For inbox automation, this limit is rarely a concern — even a large batch of threads processes in seconds. If you are running a one-time catch-up archive on an inbox with tens of thousands of emails, split the operation across multiple trigger runs using time-bounded batches, or use the batched pagination approach shown earlier in this guide.

Practical Examples for Australian Businesses

Professional services firms — solicitors, accountants, and consultants — can apply a two-tier system: newsletters and marketing emails auto-archive after 7 days, while emails from known client domains remain untouched in the inbox. Use a -from:@clientdomain.com.au exclusion in your search queries to protect client correspondence from any automated rules.

Retail and e-commerce operators using Shopify, WooCommerce, or similar platforms receive a constant stream of order confirmations, shipping notifications, and payment receipts. A rule that archives from:shopify.com and from:sendle.com emails after 14 days keeps the operational inbox uncluttered while retaining the archive for records.

Marketing and agency teams dealing with high volumes of social media notifications, platform digest emails, and tool notifications can use the label-based archive approach to automatically clear social and notifications categories daily, while keeping all client-related email and creative brief threads in the inbox.

Small business owners managing their own inbox benefit most from the weekly cleanup script — a single Sunday morning run that clears the previous week's accumulation of automated emails, receipts, and notifications, arriving on Monday morning with a meaningfully cleaner inbox.

Affiliate & Partner Programs

If you are using these scripts as part of a broader Google Workspace setup, or if your business is considering upgrading to access more automation features, the following may be useful:

• Google Workspace Referral Program: Google's official referral program for Workspace plans, which may include introductory credits for new customers. All plans — including Business Starter from approximately AUD $10.80 per user per month — include full Apps Script access with no additional cost. Generate your referral link at https://referworkspace.app.goo.gl/

This link supports our ability to produce independent, practical guides like this one at no additional cost to you.

Wrapping Up: A Clean Inbox on Autopilot

Gmail inbox maintenance is a tax on your attention. Every minute spent manually archiving emails that serve no further purpose is a minute not spent on work that actually requires your judgement. The scripts in this guide eliminate that tax entirely by moving the decision-making to code and the execution to Google's servers.

The practical path forward is straightforward:

1. Start with one script — the newsletter archive is the most impactful starting point for most inboxes. Get it running and set a daily trigger.
2. Add a log Sheet — paste in the logArchiveAction function and connect it to your chosen script. Let it run for a week before you add more rules, so you can verify nothing is being caught unexpectedly.
3. Build your label-based rules — once you trust the basic archive logic, move to the multi-label approach and create Gmail filters that auto-label incoming email. The script and the filters work together.
4. Deploy the weekly cleanup — once you have the individual rules working, consolidate them into the weekly cleanup script with the email summary. This gives you visibility without requiring you to check the log Sheet manually.
5. Protect what matters — always test new query strings by running them in the Gmail search bar before putting them in a script. If a search returns threads you did not expect, refine the query. Use is:starred as a global exclusion (-is:starred) in any rule where you want to protect flagged emails unconditionally.

Your inbox is not a storage system. It is a task list. Automated archiving gives it back that function.

Need help with your Google Workspace setup? Contact our team for a free consultation.