# Gmail Processor: rule-based Gmail automation inside Google Apps Script

> Gmail Processor is an Apache-2.0 Apps Script library that matches Gmail threads, messages and attachments against a JSON configuration and runs actions such as saving files to Drive or logging to a spreadsheet. It suits people who want Gmail rules that go beyond filters, and it stops being the right tool once you need a server you control.

**ahochsteger/gmail-processor** — Project brief: Gmail Processor is a Google Apps Script library that automates the processing of Gmail messages and attachments and execute actions (e.g. store attachments in a GDrive folder, log information in a spreadsheet) depending on matching criteria.

- Repository: https://github.com/ahochsteger/gmail-processor
- Website: http://ahochsteger.github.io/gmail-processor/
- Stars: 587 · Forks: 143
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/ahochsteger-gmail-processor

## What Gmail Processor does that a Gmail filter cannot

Gmail's built-in filters match on sender, recipient, subject and a search query, then apply labels, forward, archive or delete. They cannot rename an attachment, decrypt a password-protected PDF, run OCR over an invoice image, or write a row into a spreadsheet. Gmail Processor exists for that gap. The README describes it as an open-source Google Apps Script library that automates the processing of Gmail messages and attachments by executing actions depending on matching criteria, with actions such as storing attachments in a Google Drive folder or logging information into a spreadsheet. The audience is therefore narrow and specific: someone who already receives structured mail (invoices, statements, reports) in a Google account and wants the handling to happen automatically without standing up a mail server. It is a library, not a hosted product. You install it into your own Apps Script project, so the configuration, the OAuth grants and the execution history all live in your Google account. That is the selling point and the constraint at the same time.

## Threads, messages and attachments: how the matching and action pipeline is layered

The configuration is the program. According to the README, Gmail Processor operates based on a JSON configuration that defines matching rules and specifies corresponding actions. The README's feature list names the levels it works at: threads, messages and attachments. That ordering matters, because a rule that matches a thread can fan out to the messages inside it, and a rule that matches a message can fan out to its attachments. Actions described in the README include storing files such as attachments, PDFs of messages, or entire threads into a location in Google Drive, decrypting password-protected PDFs and storing them, extracting text from attached documents (JPEG, PNG, GIF, PDF) for OCR purposes such as reading an invoice number, and logging processed threads, messages and attachments into a Google Spreadsheet. The project is written in TypeScript and is the successor of Gmail2GDrive, with a migration path documented for converting an old configuration to the new format. The dependency list in package.json is consistent with that description: zod for configuration validation, antlr4ng for parsing, @cantoo/pdf-lib for PDF work, crypto-js for decryption, addressparser for email addresses, and date-fns for date handling. Nothing in the repository suggests a background daemon. Execution happens when Apps Script runs, which in practice means a time-driven trigger you set up in the Apps Script editor.

## Setting up Gmail Processor in an Apps Script project

The README does not include installation commands, and no config example is published in the files that ship with the repository root either. The README points to the Getting Started Guide at ahochsteger.github.io/gmail-processor/docs/getting-started for setting up Gmail Processor in Google Apps Script, and to the Config Reference at /docs/reference/ for the configuration format. The repository's devDependencies include @google/clasp, which is the usual way to push Apps Script projects from a local checkout, and the project ships a rollup.config.mjs, so a build step produces the bundled script. Because no command or config snippet is published in the README or the repository files, the only honest instruction is to follow those two documents rather than copy anything from here. The one concrete thing the repository does tell you is that clasp is part of the toolchain, so if you already develop Apps Script locally you will recognise the workflow: authenticate, create or clone the script project, push, then open the Apps Script editor to run the entry function once manually and inspect the execution log before attaching a time-driven trigger. The Playground at ahochsteger.github.io/gmail-processor/playground is a schema-aware editor with a visual schema guide, which the README presents as the way to build a configuration without memorising every key. Treat the published reference as the authority on which keys exist and which values they accept, and validate your config there before running it, because a config that parses can still select the wrong messages.

## Where the design gets in your way

The library runs inside Apps Script, and that is the limitation that decides most adoption questions. Apps Script has execution quotas per account, and a run that OCRs a stack of PDFs or decrypts many attachments will consume them. There is no queue, no retry policy you configure, and no dead-letter store described in the README; a run that fails partway leaves whatever it already did in place. The README also does not document rollback. If an action moved a file into the wrong Drive folder, undoing it is a manual job. Configuration errors are the other failure mode: because matching happens over threads, messages and attachments, a rule that is slightly too broad will quietly process mail you meant to leave alone, and the only signal is the spreadsheet log if you configured one. The README's own framing of extensibility (adding new actions and integrations in the future) also tells you what exists today is a fixed set of actions, so a workflow that needs a step outside that set means writing Apps Script yourself. Finally, everything depends on the Google account: if the account is suspended, the password changes, or the OAuth grant is revoked, processing stops silently until someone notices.

## Gmail Processor against a self-hosted mail automation stack

The obvious alternative for a developer is running an IMAP-based automation on a machine you control, using something like a Python script with imaplib plus a scheduler, or a workflow tool that speaks IMAP and SMTP. The difference is not features, it is where the trust boundary sits. A self-hosted script talks to Gmail over IMAP with an app password or OAuth token, stores its state in a database you own, and can be restarted, debugged and versioned like any other service. Gmail Processor does the opposite: it runs on Google's infrastructure, uses Apps Script's own authorization model, and keeps state in Drive and Sheets. You get no server to patch, and you also get no shell, no arbitrary dependencies and no way to run a step that Apps Script cannot express. Choose the self-hosted route when the processing logic is complex, when you need retries and observability, or when the mail comes from a provider other than Gmail. Choose Gmail Processor when the logic is a set of match-and-act rules and you would rather not operate anything.

## Maintenance, licensing and what upgrading costs

The repository is not archived, and the last push was on 2026-05-17, which is the same date as the v2.17.4 release. Two earlier releases, v2.17.3 and v2.17.2, landed on 2026-05-14 and 2026-05-01. That is a project with a single dominant maintainer, as the contributors table in the README shows, and a release cadence that clusters rather than runs continuously. For an Apps Script library this is normal and not alarming, but it does mean you should pin the version you install rather than tracking the default branch. The licence is Apache-2.0, which permits commercial use and modification and requires you to preserve the licence and attribution notices; it also includes an explicit patent grant. That is a permissive arrangement, but it is not legal advice, and if you redistribute the library inside a product you should read the LICENSE file and the NOTICE requirements yourself. Upgrade cost is low in the common case: the library is installed as a versioned Apps Script dependency, and the documented migration path exists precisely because the 1.x line (Gmail2GDrive) had a different configuration format. Expect configuration churn across major versions, not API churn in your own code.

## Reading the repository before you trust it with your inbox

The top-level layout tells you how the project is built. There is a src/ directory for the TypeScript sources, a docs/ directory that feeds the published site, an openspec/ directory, a benchmark.ts at the root, and a full lint and test setup (eslint.config.mjs, jest.config.js, jest.setup.ts, sonar-project.properties). The presence of a benchmark file and a Sonar configuration suggests performance and code quality are tracked internally, but the README publishes no performance numbers, so do not assume any. The devbox.json and .envrc files indicate the maintainer develops in a reproducible environment, which is a good sign for anyone trying to reproduce a bug. What the repository does not give you is a statement about which Apps Script quotas the library is designed to stay under, or guidance on how large a mailbox it has been run against. Those are the questions to ask in an issue before you point it at years of archived mail.

## Conclusion

Adopt Gmail Processor if your mail already lives in a Google account, your rules can be expressed as a JSON config, and you are comfortable running the whole thing inside Apps Script. Do not adopt it if you need a self-hosted service, a scheduler you control, or processing that must not touch Google's servers. Before committing, verify three things in your own account: that the manifest requests only the OAuth scopes your config actually needs, that a dry run of your matching criteria selects the messages you expect, and that the Apps Script execution quota for your account covers the volume of mail you plan to process.

## FAQ

### Is Gmail Processor a replacement for Gmail itself?

No. It is a Google Apps Script library that processes Gmail messages and attachments, so it runs on top of an existing Gmail account rather than replacing the mail service.

### How do I install Gmail Processor?

The README does not list install commands. It directs readers to the Getting Started Guide at ahochsteger.github.io/gmail-processor/docs/getting-started, which covers setting it up in Google Apps Script.

### What kind of configuration does Gmail Processor use?

It operates on a JSON configuration that defines matching rules and the corresponding actions. The Config Reference at ahochsteger.github.io/gmail-processor/docs/reference/ documents the available keys.

### Can Gmail Processor read text out of an attached invoice?

The README lists OCR text extraction from attached documents in JPEG, PNG, GIF and PDF formats, giving an invoice number as an example of the text it can pull out for organizing attachments.

### Can I migrate an existing Gmail2GDrive configuration?

Yes. Gmail Processor is described as the successor of Gmail2GDrive, and the README points to a migration page for converting an old configuration to the new format.

## Sources

- [Official documentation](http://ahochsteger.github.io/gmail-processor/)
- [Official README](https://github.com/ahochsteger/gmail-processor#readme)
- [Project repository](https://github.com/ahochsteger/gmail-processor)
- [Release notes](https://github.com/ahochsteger/gmail-processor/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ahochsteger-gmail-processor