Mael - Gmail API Backend Handler

Flask-based backend application to retrieve and filter Gmail messages using the official Google Gmail API.

---

Prerequisites

Before running the application, you must set up the Google Cloud Console credentials and local environment.

1. Google Cloud Console Configuration

1. Open the Google Cloud Console.
2. Create a new project (e.g., Mael).
3. Navigate to APIs & Services > Library, search for Gmail API, and click Enable.
4. Go to APIs & Services > OAuth consent screen, select External, fill in required App information, and add the test user email address you intend to read. Under scopes, add .../auth/gmail.readonly or complete configuration.
5. Navigate to APIs & Services > Credentials > click Create Credentials > select OAuth client ID.
6. Select Application type: Desktop app, enter a name, and click Create.
7. Download the client secrets JSON file.
8. Rename the downloaded file to client_secret.json and place it in the root folder of this project.

2. Environment Setup

Configure the Python virtual environment and install the required dependencies:

Windows (PowerShell):

python -m venv env
.\env\Scripts\Activate.ps1
pip install -r requirements.txt

Linux / macOS:

python3 -m venv env
source env/bin/activate
pip install -r requirements.txt

Using Docker: If you prefer to run the application in a Docker container, ensure you have Docker and Docker Compose installed.

---

Usage

Using Local Python Environment

1. Start the Flask Server

Run the Flask application:

python app.py

The server will start running locally at http://localhost:5000.

---

Using Docker

1. Start the Container

Run the following command to build and start the server:

docker-compose up --build -d

The server will start running at http://localhost:5000. The container mounts client_secret.json and token.json from your host directory, meaning authentication will persist across container restarts.

---

2. First-Time Authorization (OAuth2)

Since client_secret.json only identifies the application, you must authenticate your Gmail account:

1. Open your web browser and go to http://localhost:5000/login.
2. Sign in with the Google Account you wish to fetch emails from.
3. Grant permission to the application.
4. Once completed, a token.json file will be generated in the root directory. You will not need to authenticate again unless token.json is deleted.

---

API Endpoints

Retrieve Emails

• Endpoint: POST /api/getEmail
• Content-Type: application/json
• Headers:
  • X-API-Key: your_secret_api_key_here (configured in .env)

Request Payload

All fields are optional. If no parameters are provided, it fetches the 5 latest messages:

{
  "from": "user@gmail.com",
  "to": "saya+abcd@gmail.com",
  "limit": 5
}

• from (string, optional): Filter emails sent from this sender.
• to (string, optional): Filter emails sent to this recipient.
• limit (integer, optional): Number of emails to retrieve (default: 5).

Example Curl Request

curl -X POST http://localhost:5000/api/getEmail \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_secret_api_key_here" \
  -d '{"limit": 3}'

Example Python Script (test_client.py)

import requests
import json

URL = "http://localhost:5000/api/getEmail"
HEADERS = {
    "X-API-Key": "your_secret_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "from": "user@gmail.com",
    "to": "saya+abcd@gmail.com",
    "limit": 5
}

response = requests.post(URL, json=payload, headers=HEADERS)
if response.status_code == 200:
    print(json.dumps(response.json(), indent=2))
else:
    print(f"Error {response.status_code}: {response.text}")