Gmail + NAS automation

Save invoice and receipt attachments from Gmail to your NAS automatically.

A fast, focused Python tool to fetch matching emails, store attachments in structured folders, and optionally delete processed messages.

View Repository Get Started

PyPI

What it does

Search Gmail with filters and queries
Save attachments by sender and date
Optional content filtering
Convert attachments to txt, png, jpeg
Reliable, retry-backed uploads

Python 3.12+ SMB/NAS ready

Features

Query-driven selection

Define Gmail queries and attachment filters per rule. Keep it narrow and precise.

Structured storage

Attachments are saved by sender and date, making retrieval predictable.

Content filters

Scan PDF or text attachments for required phrases before saving.

Attachment conversion

Automatically convert saved PDFs to txt, png, or jpeg in a separate output folder.

Operational safety

Retries, logging, and optional delete-after-save keep runs clean.

Quick Start

pip install -r requirements.txt
python -m build
pip install .

export-gmail-attachments-to-nas \
  --username YOUR_NAS_USER \
  --password YOUR_NAS_PASSWORD \
  --credentials /path/to/credentials.json \
  --criteria /path/to/criteria.json

Criteria Configuration

Create a criteria.json file to define your email processing rules. Each entry in criteria is evaluated independently.

{
  "smb_server": "homenas.home.lan",
  "criteria": [
    {
      "enabled": true,
      "query": "{subject:Invoice subject:Receipt} filename:.pdf",
      "smb_folder": "\\documents\\invoices",
      "filters": [".pdf"],
      "attachment_content_filter": ["Invoice", "Total"],
      "delete_after_save": false,
      "convert": {
        "to": "txt",
        "output_folder": "\\documents\\invoices-txt",
        "extension_filter": [".pdf"],
        "filename_filter": "invoice.*"
      }
    }
  ]
}

Criteria fields

Field	Required	Description
`enabled`	❌	Set to `false` to skip this rule. Defaults to `true`.
`query`	✅	Gmail search query (supports all Gmail search operators).
`smb_folder`	✅	Destination folder on the SMB share.
`filters`	❌	Optional list of file extensions to save (e.g. `[".pdf"]`). If omitted or empty, no attachments are saved for this rule.
`attachment_content_filter`	❌	Save only if the attachment contains at least one of these phrases (case-sensitive match).
`delete_after_save`	❌	Delete the source email after a successful save. Defaults to `false`.
`convert`	❌	Optional block to convert attachments. See Convert section.

Attachment Conversion

Each rule can include a convert block to automatically convert saved attachments to another format and store the result in a separate output folder. Omitting it leaves the rule's behaviour unchanged.

Supported conversions

PDF → txt — full text extraction
PDF → png — one image per page
PDF → jpeg / jpg — one image per page

"convert": {
  "to": "txt",
  "output_folder": "\\documents\\converted",
  "extension_filter": [".pdf"],
  "filename_filter": "invoice.*"
}

Convert fields

Field	Required	Description
`to`	✅	Target format: `txt`, `png`, `jpeg`, or `jpg`.
`output_folder`	✅	SMB folder path where converted files are saved.
`extension_filter`	❌	Restrict conversion to attachments with these extensions (e.g. `[".pdf"]`).
`filename_filter`	❌	Restrict conversion to filenames matching this regex (case-insensitive).

Google OAuth Setup

This tool requires Google OAuth credentials to access Gmail. Follow these steps to create them:

1. Create a Google Cloud Project

Go to Google Cloud Console
Click Select a Project → New Project
Enter a project name (e.g., "Gmail Attachments Export")
Click Create and wait for the project to initialize

2. Enable Gmail API

In the Cloud Console, navigate to APIs & Services → Library
Search for "Gmail API"
Click the Gmail API result
Click Enable

3. Create OAuth 2.0 Credentials

Go to APIs & Services → Credentials
Click + Create Credentials → OAuth client ID
If prompted, configure the OAuth consent screen first:
- Choose External user type
- Fill in the required fields (app name, user support email)
- Under scopes, add https://mail.google.com/
- Save and continue
Back to credentials, select Desktop application as the application type
Click Create

4. Download Credentials

In the Credentials page, find your newly created OAuth 2.0 Client ID
Click the download icon (↓) to download the JSON file
Save it as credentials.json in your project directory

5. First Run Authentication

Run the tool for the first time with your credentials
A browser window will open asking for Gmail access
Click Allow to grant permissions
The tool will create token.json automatically
Keep both files secure and don't commit them to version control

Security Notes

Credentials

Store NAS credentials in env vars or pass them at runtime.

Token hygiene

Gmail tokens are stored locally in token.json. Treat it as sensitive.

Scope control

Use minimal required Gmail scope. Delete requires mail.google.com.

NAS access

Limit SMB share permissions to a dedicated account when possible.

Contributors

Thanks to all the amazing people who have contributed to this project!

Loading contributors...