This project implements a rule-based email processing system that integrates with Gmail API to automate email management tasks.
- Gmail API integration using OAuth2 authentication
- Email storage in SQLite database (stored locally in
gmail_processor.db) - Rule-based email processing with configurable conditions and actions
- Support for various email fields (From, Subject, Message, Received Date)
- Multiple predicate types for different field types
- Actions: Mark as read/unread, Move message
- Python 3.8+
- Google Cloud Project with Gmail API enabled
- OAuth 2.0 credentials
- Clone the repository:
git clone git@github.com:Pkfication/gmail-processor.git
cd gmail-rule-processor- Create and activate virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies and the package in development mode:
pip install -r requirements.txt-
Set up Google Cloud Project:
- Go to Google Cloud Console
- Create a new project
- Enable Gmail API
- Create OAuth 2.0 credentials
- Download credentials and save as
credentials.jsonin the project root directory
-
Set up environment variables: Create a
.envfile in the project root with the following variables:
GOOGLE_CREDENTIALS_FILE=credentials.json
- Initialize the database:
python -m scripts.init_db- First-time authentication:
python -m scripts.auth- Fetch emails:
python -m scripts.fetch_emails- Process emails with rules:
python -m scripts.process_emailsRules are defined in config/rules.json. Example:
{
"rules": [
{
"name": "Newsletter Processing",
"predicate": "all",
"conditions": [
{
"field": "subject",
"predicate": "contains",
"value": "newsletter"
},
{
"field": "from",
"predicate": "contains",
"value": "example.com"
}
],
"actions": [
{
"type": "mark_as_read"
},
{
"type": "move_to",
"value": "Newsletters"
}
]
}
]
}Run tests using pytest:
python -m pytest tests/ -vgmail-rule-processor/
├── config/
│ └── rules.json
├── scripts/
│ ├── auth.py
│ ├── fetch_emails.py
│ ├── init_db.py
│ └── process_emails.py
├── src/
│ ├── __init__.py
│ ├── database/
│ │ ├── __init__.py
│ │ ├── models.py
│ │ └── session.py
│ ├── gmail/
│ │ ├── __init__.py
│ │ ├── auth.py
│ │ └── client.py
│ └── rules/
│ ├── __init__.py
│ ├── engine.py
│ └── parser.py
├── tests/
│ ├── test_database.py
│ ├── test_gmail.py
│ └── test_rules.py
├── credentials.json # Place your Google OAuth credentials here
├── gmail_processor.db
├── .env
├── requirements.txt
└── README.md