Gmail Automation

📋 Prerequisites

• Node.js (v18+)
• Python (v3.8+)
• Gmail API credentials (client_id and client_secret)
• Google Cloud project with Pub/Sub API enabled
• Hugging Face API token
• Discord webhook URL (for daily summaries)

🚀 Quick Start

1. Clone this repository

   git clone https://github.com/yourusername/gmail-flow.git
   cd gmail-flow

2. Install Node.js dependencies

   pnpm install

3. Install Python dependencies

   pip install -r requirements.txt

4. Configure environment variables

   cp .env.example .env

   Then edit the .env file with your credentials (see setup sections below).

5. Start the development server

   pnpm dev

6. Open the Motia Workbench

   Navigate to http://localhost:3000 to access the workflow UI.

🔧 Detailed Setup

Setting up Google Cloud Project and Gmail API

Before you can use the Gmail Account Manager, you need to set up a Google Cloud project with the Gmail API and Pub/Sub:

1. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Click on "New Project" and follow the steps to create a new project
   • Note your project ID for later use

2. Enable the Gmail API:

   • In your project, go to "APIs & Services" > "Library"
   • Search for "Gmail API" and click on it
   • Click "Enable"

3. Enable the Pub/Sub API:

   • In your project, go to "APIs & Services" > "Library"
   • Search for "Cloud Pub/Sub API" and click on it
   • Click "Enable"

4. Create OAuth Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Set the application type to "Desktop app"
   • Click "Create"
   • Note your Client ID and Client Secret for your .env file:

     GOOGLE_CLIENT_ID=your_client_id
     GOOGLE_CLIENT_SECRET=your_client_secret

Setting up Google Pub/Sub for Gmail Notifications

To enable real-time email notifications, you need to set up a Google Cloud Pub/Sub topic and subscription:

1. Create a Pub/Sub Topic:

   • In your Google Cloud Console, go to "Pub/Sub" > "Topics"
   • Click "Create Topic"
   • Name your topic (e.g., gmail-notifications)
   • Add the service account gmail-api-push@system.gserviceaccount.com as a Topic Publisher to allow Gmail to publish notifications
   • Click "Create"
   • Note the full topic name (usually projects/your-project-id/topics/gmail-notifications) for your .env file:

     GOOGLE_PUBSUB_TOPIC=projects/your-project-id/topics/gmail-notifications

2. Create a Pub/Sub Subscription:

   • Once your topic is created, click "Create Subscription"
   • Name your subscription (e.g., gmail-notifications-push)
   • Set the Delivery Type to "Push"
   • Set the Endpoint URL to your webhook URL (e.g., https://your-domain.com/api/gmail-webhook)
     • For local development, you'll need to use a tool like ngrok to expose your local server
   • Click "Create"

3. Set up Domain Verification (if needed):

   • If you're using a custom domain for your webhook endpoint, you may need to verify domain ownership
   • Follow the instructions in Google Cloud Console for domain verification

Gmail API Authentication

This project includes a complete OAuth2 authentication flow for the Gmail API:

1. Start the development server: pnpm dev
2. Navigate to the authentication workflow in the Motia Workbench
3. The workflow will generate an authorization URL
4. Open the URL in your browser and authorize the application
5. The application will receive and store your authentication tokens

Discord Webhook Configuration

To receive daily email summaries in Discord, follow these steps to set up a webhook:

1. Create a Discord Server (skip if you already have one):

   • Open Discord and click the "+" icon on the left sidebar
   • Select "Create My Own" and follow the setup wizard

2. Create a Channel for Notifications:

   • Right-click on your server name and select "Server Settings"
   • Go to "Channels" and click "Create Channel"
   • Name it (e.g., "email-summaries") and click "Create"

3. Create a Webhook:

   • Right-click on your new channel and select "Edit Channel"
   • Go to "Integrations" tab
   • Click "Create Webhook"
   • Give it a name (e.g., "Gmail Summary Bot")
   • Optionally, customize the avatar
   • Click "Copy Webhook URL"

4. Add Webhook URL to Environment Variables:

   • Open your .env file
   • Add or update the Discord webhook URL:

     DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook-url

5. Test the Webhook:

   • You can test if your webhook is working correctly with this curl command:

     curl -X POST -H "Content-Type: application/json" \
     -d '{"content": "Testing Gmail Account Manager webhook"}' \
     https://discord.com/api/webhooks/your-webhook-url

   • You should see the message appear in your Discord channel

Hugging Face Setup

1. Create a Hugging Face Account:

   • Sign up at Hugging Face

2. Generate an API Token:

   • Go to your Hugging Face account settings
   • Create a new API token
   • Copy the token to your .env file:

     HUGGINGFACE_API_TOKEN=your_api_token