website·Indexed 31 days ago
https://ahochsteger.github.io/gmail-processor/A tool for processing Gmail threads, messages, and attachments, featuring capabilities to store attachments to Google Drive, extract text, and decrypt PDFs. It supports a configurable system of global and attachment actions, string and date expressions, regular expressions, and environment placeholders for string substitution.
Actions in gmail-processor are triggered within specific processing scopes, which determine the context available to the action:
global.*: Globally available; can be placed anywhere in the configuration.thread.*: Runs in the context of a thread (includes message and attachment context).message.*: Runs in the context of a message (includes attachment context).attachment.*: Runs specifically in the context of an attachment.The ContextType enum identifies the type of context available for processing:
attachment: Contains attachment configuration and info about the current attachment.env: Contains environment information and references to environment objects.message: Contains message configuration and info about the current message.proc: Contains processing info (configuration, integration adapters, action registry, and timer).thread: Contains thread configuration and info about the current thread.| Key | Description | Example |
|---|---|---|
attachment.contentType | The content type of the attachment | "application/pdf" |
attachment.contentType.match.1 | Regex match group 1 from content type | "pdf" |
attachment.contentType.match.appType | Named regex match group appType from content type | "pdf" |
attachment.hash | SHA1 content hash of the attachment | "aa0b8cc192a5d8d5b5d8ecda24fd096..." |
attachment.index | 0-based index of the attachment | "0" |
attachment.isGoogleType | true if the attachment is a Google Workspace file | "false" |
attachment.matched | Overall matching result for all conditions in match config | "true" |
attachment.name | The name of the attachment | "attachment1.pdf" |
attachment.name.match.1 | Regex match group 1 from attachment name | "1" |
attachment.name.match.attNr | Named regex match group attNr from attachment name | "1" |
attachment.size | The size of the attachment | "18" |
attachmentConfig.index | 0-based index of the attachment configuration | "0" |
# 1. Clone the repository
git clone https://github.com/ahochsteger/gmail-processor.git
cd gmail-processor
# 2. Setup environment
# Option A: Using Devbox (Recommended)
devbox shell
# Option B: Traditional (Ensure Node.js 22+ is installed)
# 3. Install dependencies
npm run all:reinstallmatch.subject configuration to extract specific data from an email's subject line. Extracted values are accessible via the message.subject.match object. For example, a capture group defined as (?<school>...) will be available as {{message.subject.match.school}}.{
"messages": [
{
"name": "extract-message-fields-from-subject",
"match": {
"subject": "regularExpressions (?<school>[^-]+)-(?<reportType>[^-]+)-(?<reportSubType>[^-]+)-(?<date>[0-9-]+)"
},
"attachments": [
{
"actions": [
{
"name": "attachment.store",
"args": {
"location": "/Reports/{{message.subject.match.school}}/All Reports/{{message.subject.match.reportType}}/{{message.subject.match.reportSubType}}/{{message.subject.match.date}}-{{attachment.name}}"
}
}
]
}
]
}
]
}class-transformer and ajv to Zod v4. Developers should update any custom configuration schemas or validation logic to use Zod v4 syntax.// Example Zod v4 schema usage
import { z } from 'zod';
const ConfigSchema = z.object({
apiKey: z.string().min(1),
timeout: z.number().default(3000),
});
type Config = z.infer<typeof ConfigSchema>;{
"description": "Use this to get started with Gmail Processor. It stores an attachment to Google Drive.",
"settings": {
"markProcessedMethod": "mark-read"
},
"global": {
"thread": {
"match": {
"query": "has:attachment -in:trash -in:drafts -in:spam after:{{date.now|formatDate('yyyy-MM-dd')}} is:unread subject:\"[GmailProcessor-Test] simple\""
}
}
},
"threads": [
{
"match": {
"query": "from:${user.email}"
},
"messages": [
{
"attachments": [
{
"match": {
"name": "^invoice\\.pdf$"
},
"actions": [
{
"name": "attachment.store",
"args": {
"location": "/GmailProcessor-Tests/e2e/{{date.now|formatDate('yyyy-MM-dd')}}/basics/simple/{{message.subject}}-{{attachment.name}}",
"conflictStrategy": "keep"
}
}
]
}
]
}
]
}
]
}Gmail Processor provides several core capabilities for email automation:
For users who need full control over the execution or wish to modify the library code, the library can be copied directly into the project instead of using a reference:
GmailProcessorLib.gs).attachment.extractText action are stored in the attachment.extracted.match object. You can reference these named capture groups using double-curly brace syntax in later actions.{
"name": "attachment.store",
"args": {
"location": "/folder/{{attachment.name.match.basename}}-number-{{attachment.extracted.match.invoiceNumber}}.pdf",
"description": "Invoice number: {{attachment.extracted.match.invoiceNumber}}"
}
}