Skip to content

Tutorial.md

Latest commit

 

History

History
100 lines (76 loc) · 4.32 KB

Tutorial.md

File metadata and controls

100 lines (76 loc) · 4.32 KB

Configuration Tutorial

This guide will walk you through setting up the "Automated Mail Bridge" for your repository. The process involves three main phases: Getting the Gmail Token, Configuring GitHub Secrets, and Enabling Actions.

Part 1: Obtain the Gmail Token

To interact with the Gmail API, we first need to create a project in Google Cloud, generate a credentials.json file, and run a local script to generate the access Token.

1.1 Create a Google Cloud Project

If you already have a project, skip to 1.2.

  1. Go to the Google Cloud Console.
  2. Click the project selector at the top of the page and select "New Project".
  3. Name your project (e.g., Mail-Bridge) and click "Create".

1.2 Enable Gmail API

  1. Ensure your newly created project is selected.
  2. In the left navigation menu, go to "APIs & Services".
  3. Type "Gmail API" into the search bar.
  4. Click on Gmail API in the results and click "Enable".

1.3 OAuth Consent Screen

  1. Go to "APIs & Services" > "OAuth consent screen".
  2. For User Type, select "External" (for personal Gmail) or "Internal" (for Workspace orgs), then click "Create".
  3. Fill in the required fields:
    • App name: Mail Bridge
    • User support email: Your Gmail address.
    • Developer contact info: Your Gmail address.
  4. Click "Save and Continue". On the Scopes page, simply click "Save and Continue" again.
  5. IMPORTANT (If you chose External): Under the "Test users" section, click "Add Users" and type in your own Gmail address.

1.4 Create Credentials and Download JSON

  1. Go to "APIs & Services" > "Credentials".
  2. Click "+ Create Credentials" at the top and select "OAuth client ID".
  3. For Application type, choose "Desktop App".
  4. Set any Name (e.g., My Python Script) and click "Create".
  5. A modal saying "OAuth client created" will appear. Click "Download JSON".
  6. Rename the file: Rename the downloaded file (which has a very long name) exactly to credentials.json.

1.5 Generate Token Locally

  1. Place credentials.json in the src/ directory of this repository (same folder as gen_token.py).
  2. Open your local terminal and install the dependencies first: 
    pip install -r requirements.txt
  3. Run the generation script: 
    python src/gen_token.py
  4. Your web browser will open automatically. Make sure to check all permission boxes (especially "Read your email", which is required for the Threading feature to work).
  5. Once authenticated, a token.json file will be generated in your directory. Keep this safe and NEVER commit it to a public repository!

Part 2: Configure GitHub Secrets

Next, we need to securely store your credentials in GitHub. Navigate to your GitHub repository, go to Settings -> Secrets and variables -> Actions, and click New repository secret.

2.1 Add GMAIL_TOKEN_JSON

Create a new secret:

  • Name: GMAIL_TOKEN_JSON
  • Secret: Open the token.json you generated in Part 1 with a text editor, copy its entire content, and paste it here.

2.2 Add ACCOUNTS_JSON

Create another secret named ACCOUNTS_JSON. This dictates which third-party accounts will be fetched. Format it strictly as a JSON array as shown below:

[
  {
    "name": "Tencent_Exmail",
    "imap_server": "imap.exmail.qq.com",
    "imap_port": 993,
    "email": "username@example_tencent.email",
    "password": "YOUR_TENCENT_PASSWORD"
  },
  {
    "name": "Aliyun_Exmail",
    "imap_server": "imap.qiye.aliyun.com",
    "imap_port": 993,
    "email": "username@example_ali.com",
    "password": "YOUR_ALIYUN_PASSWORD"
  }
]

Note: The password here is usually an "App Password / Authorization Code" generated by your third-party email provider, not your actual web login password.

Part 3: Run and Test

  1. Make sure .github/workflows/mail_bridge.yml is pushed to your default branch (main or master).
  2. Click the Actions tab at the top of your GitHub repository.
  3. Select IMAP to Gmail Bridge from the left sidebar.
  4. Click the Run workflow button on the right to trigger a manual test.
  5. Expand the logs. If you see [+] Successfully inserted message to Gmail, congratulations! GitHub will now fetch your emails automatically every 30 minutes.