Fetch2Gmail
Self-hosted email fetcher: IMAP (ISP mailbox) → Gmail API import. Replaces Gmail’s deprecated POP3 fetch.
- Watches one or more ISP mailboxes via IMAPS (port 993), using IMAP IDLE for near-realtime delivery when the server supports it (falls back to polling otherwise).
- Imports messages with Gmail API (not SMTP); applies a Gmail label, preserves headers and date. By default uses
neverMarkSpamso Gmail’s spam classifier does not bury ISP→Gmail imports. - Supports multiple IMAP accounts in one process, with optional per-IMAP routing to one or more Gmail accounts.
- Deletes from ISP only after Gmail confirms import. Idempotent (UID + message hash).
Requirements: Python 3.11+, IMAP credentials, Google Cloud project with Gmail API and OAuth2 (Web application).
Use case 1: Headless Debian server
You use a computer with a browser (to get the token) and a Debian server (Odroid, Raspberry Pi, etc.) where the app runs. Follow the steps in order.
On a computer with a browser (Windows or Linux)
Step 1. Get credentials.json from Google Cloud
- Go to Google Cloud Console → create or select a project.
- APIs & Services → Library → search “Gmail API” → Enable.
- OAuth consent screen: External → add app name → Scopes → add
https://www.googleapis.com/auth/gmail.modify→ Test users → add the Gmail address that will receive the imported mail. - Credentials → Create credentials → OAuth client ID → Application type Web application.
- Authorized redirect URIs → add
http://127.0.0.1:8765/auth/gmail/callbackandhttp://localhost:8765/auth/gmail/callback. - Create → download the JSON. Save it as credentials.json in a folder (e.g. Desktop or
~/fetch2gmail-auth).
Step 2. Install Python 3.11+ and pipx
- Windows: Install Python 3.11+ (check “Add Python to PATH”). Open Command Prompt or PowerShell:
pip install pipxthenpipx ensurepath. Close and reopen the terminal. - Linux:
sudo apt install pipxthenpipx ensurepath. Reopen the terminal (or runsource ~/.bashrc) so~/.local/binis on PATH.
Step 3. Install fetch2gmail
pipx install fetch2gmail
Step 4. Get the token
In the same folder where credentials.json is, run:
fetch2gmail auth
A browser opens. Sign in with the Gmail account that will receive the imported mail and click Allow. token.json is saved in that folder. Press Ctrl+C to stop the auth server.
Step 5. Copy these two files to the server
Copy credentials.json and token.json to your Debian server. You will put them in the app data directory in the next section.
On the Debian server
Step 6. Create the data directory and add the files
Pick one directory for all app files (e.g. /opt/fetch2gmail or /home/odroid/fetch2gmail). Create it and put credentials.json and token.json there:
sudo mkdir -p /opt/fetch2gmail
sudo chown "$USER" /opt/fetch2gmail
# Copy credentials.json and token.json into /opt/fetch2gmail (from step 5)
Use the same path in the steps below (replace /opt/fetch2gmail and the username if you use something else).
Step 7. Install pipx and fetch2gmail on the server
Run these from any directory (you do not need to be in /opt/fetch2gmail):
sudo apt install pipx
pipx ensurepath
# Log out and back in (or source ~/.bashrc) so ~/.local/bin is on PATH
pipx install fetch2gmail
The app will find your token and files in /opt/fetch2gmail because in step 9 you install a single systemd service that sets WorkingDirectory and FETCH2GMAIL_CONFIG to that directory. If you set the UI password from the CLI (step 8), cd into /opt/fetch2gmail first so .ui_auth is created there.
Step 8. Set the UI username and password
The web UI is protected by a username and password (stored as a hash in .ui_auth). You can set it from the CLI or from the UI:
- From the CLI: Run
cd /opt/fetch2gmailthenfetch2gmail set-ui-passwordand enter username and password when prompted. - From the UI: If .ui_auth does not exist yet, open the web UI and you will see the Set UI password wizard. Set a username and password there; after that, the UI will require them (HTTP Basic Auth). You cannot create config or use the app until a UI password is set.
Step 9. Install and enable the systemd service (one service: web UI + background fetch)
One service runs the web UI and polls your ISP mailbox on a schedule (every 5 minutes by default). Generate the unit file and install it:
fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail -o /tmp/fetch2gmail.service
sudo mv /tmp/fetch2gmail.service /etc/systemd/system/fetch2gmail.service
sudo systemctl daemon-reload
sudo systemctl enable fetch2gmail
sudo systemctl start fetch2gmail
Replace YOUR_USER with the user that owns /opt/fetch2gmail (e.g. odroid). Replace /opt/fetch2gmail if you used a different data directory. The command finds fetch2gmail on your PATH; if it is elsewhere, add --exec /path/to/fetch2gmail.
Alternatively, print the unit file and pipe it into place:
fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
sudo systemctl daemon-reload
sudo systemctl enable fetch2gmail
sudo systemctl start fetch2gmail
Step 10. Configure ISP mail in the web UI
Open http://<server-ip>:8765 in your browser (e.g. http://192.168.1.10:8765). Log in with the UI username and password from step 8. You will see the initial setup form. Enter your IMAP host, username, password, mailbox, and Gmail label, then click Create config. The app stores your password securely and will poll your ISP mailbox on a schedule (every 5 minutes by default). You do not need to edit any config file by hand.
Done. To watch logs: journalctl -u fetch2gmail -f.
Use case 2: Device with a browser (one machine)
Everything runs on one machine (laptop or desktop) that has a browser. You get token.json via fetch2gmail auth (CLI); the web UI does not have "Sign in with Google". Then set a UI password and configure ISP mail in the UI. Follow the steps in order.
Step 1. Get credentials.json from Google Cloud
Same as Use case 1, step 1. Save credentials.json in a folder you will use as the app data directory (e.g. ~/fetch2gmail).
Step 2. Install Python 3.11+ and pipx
Same as Use case 1, step 2 (Windows or Linux).
Step 3. Install fetch2gmail
pipx install fetch2gmail
Step 4. Create the data directory and add credentials
Create the folder and put credentials.json there (you do not have a token yet):
mkdir -p ~/fetch2gmail
# Copy credentials.json into ~/fetch2gmail
Use the same path in the steps below (replace ~/fetch2gmail if you use something else).
Step 5. Get token.json (CLI)
cd into your data directory and run fetch2gmail auth. A browser opens; sign in with the Gmail account that will receive the imported mail and click Allow. token.json is saved in that folder. Press Ctrl+C to stop the auth server.
Step 6. Install and enable the systemd service
Same as Use case 1, step 9: one service (web UI + background fetch). Replace YOUR_USER and the path with yours:
fetch2gmail install-service --user YOUR_USER --dir /home/YOUR_USER/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
sudo systemctl daemon-reload
sudo systemctl enable fetch2gmail
sudo systemctl start fetch2gmail
Step 7. Set UI password and configure ISP mail
Open http://127.0.0.1:8765 in your browser. If .ui_auth does not exist yet, you will see the Set UI password wizard; set a username and password there (or run fetch2gmail set-ui-password from the CLI). Then use the initial setup form to enter your IMAP host, username, password, mailbox, and Gmail label, and click Create config. The app stores your password securely and the timer runs the fetch on the schedule you set (every 5 minutes by default).
Done.
Reference
OAuth redirect URI
Your Google OAuth client must use Web application (not Desktop) and have these Authorized redirect URIs:
http://127.0.0.1:8765/auth/gmail/callbackhttp://localhost:8765/auth/gmail/callback
Google does not allow redirect URIs that use an IP address. That is why the token must be obtained on a machine where the app can use localhost (Use case 1 steps 1–4 on a PC; Use case 2 on the same machine).
IMAP IDLE and poll interval
The background watcher in the web UI process prefers IMAP IDLE (RFC 2177) when the server advertises the IDLE capability. New mail can trigger an import immediately instead of waiting for the next poll.
imap.use_idle(defaulttrue): enable IDLE when supported. Disable to force polling.imap.idle_refresh_minutes(default25): leave IDLE, sendNOOP, and re-enter IDLE before the typical ~29-minute server timeout. Also enables TCPSO_KEEPALIVEand reconnects with exponential backoff on silent drops.poll_interval_minutes(default5): used when IDLE is missing or disabled.
All three can be changed in the web UI (Config) or in config.json.
Manual smoke checks: with IDLE supported, send yourself mail and confirm an import in the UI logs within seconds (look for IDLE: mailbox update). Set use_idle to false (or use a server without IDLE) and confirm fetches still run on the poll interval.
Data directory
All app files live in one directory: config.json, credentials.json, token.json, and optionally .env (IMAP password; the UI can store it for you). The app creates state.db and .ui_auth there. Set WorkingDirectory and FETCH2GMAIL_CONFIG to this directory in systemd.
Security
- Do not commit credentials.json, token.json, or config.json with secrets. Restrict file permissions to the user running the service.
- The UI is protected by a username and password in .ui_auth (when set). Get token.json via
fetch2gmail auth(CLI only; there is no "Sign in with Google" in the UI). - The Gmail scope requested is gmail.modify (read and modify labels/messages only).
Multiple IMAP accounts (recommended: one process)
One Fetch2Gmail process can watch multiple IMAP mailboxes and import into one or more Gmail accounts. Configure this in the UI (IMAP accounts section) or in config.json via imap_accounts.
Example: 3 IMAP → 1 Gmail
{
"imap_accounts": [
{
"id": "isp1",
"host": "imap.isp1.example",
"port": 993,
"username": "you@isp1.example",
"password_env": "IMAP_PASSWORD_ISP1",
"mailbox": "INBOX",
"use_ssl": true,
"delete_after_import": true,
"gmail_token_paths": []
},
{
"id": "isp2",
"host": "imap.isp2.example",
"username": "you@isp2.example",
"password_env": "IMAP_PASSWORD_ISP2",
"mailbox": "INBOX"
},
{
"id": "isp3",
"host": "imap.isp3.example",
"username": "you@isp3.example",
"password_env": "IMAP_PASSWORD_ISP3",
"mailbox": "INBOX"
}
],
"gmail_accounts": [
{
"label": "ISP Mail",
"credentials_path": "credentials.json",
"token_path": "token.json"
}
]
}
- Leave
gmail_token_pathsempty (or omit it) so that IMAP account imports into all configured Gmail accounts. - To route one IMAP account to a subset of Gmail accounts, set
gmail_token_pathsto the matchingtoken_pathvalues (e.g.["token.json"]). - Passwords are stored encrypted in .env under each account’s
password_envkey (defaultIMAP_PASSWORDfor iddefault, otherwiseIMAP_PASSWORD_<ID>). - Legacy configs with a single top-level
"imap"object still work (treated as one account with iddefault).
In the UI you can add/remove IMAP accounts and pick Gmail destinations per account. One systemd service / one UI port is enough.
Multiple instances (optional isolation)
You can still run multiple processes (separate data directories and ports) when you want isolation across machines or fully separate configs. That is optional now that multi-IMAP works in one process.
Second instance (example):
- Create a second data directory (e.g.
/opt/fetch2gmail2) with its own config.json, credentials, and tokens. - Generate a second systemd unit and bind a different port:
fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail2 -o /tmp/fetch2gmail2.service sudo mv /tmp/fetch2gmail2.service /etc/systemd/system/fetch2gmail2.service
EditExecStart=to include--port 8766, then enable/startfetch2gmail2. - Open the first UI at http://server:8765 and the second at http://server:8766.
Troubleshooting
"Background fetch skipped: IMAP password could not be decrypted" — The encrypted IMAP password in .env was created with a different encryption key (e.g. different config directory or .cookie_secret). Re-enter the IMAP password in the UI (Config section) and Save to re-encrypt it.
To see what the service is doing (background poller, fetch results, errors), stream the logs:
journalctl -u fetch2gmail -f
You’ll see messages like "Poller: next fetch in Xs", "Poller: running fetch now", and "Background fetch: imported=...". Use Ctrl+C to stop following. For a second instance (e.g. fetch2gmail2), use journalctl -u fetch2gmail2 -f.
CLI
| Command | Purpose |
|---|---|
fetch2gmail --version |
Show installed version. |
fetch2gmail auth |
Get token.json on a machine with a browser (opens http://127.0.0.1:8765). |
fetch2gmail set-ui-password |
Set UI username and password (hash in .ui_auth). |
fetch2gmail install-service |
Generate systemd unit file (one service: web UI + background fetch). Use --user, --dir, and optionally --output or pipe to sudo tee. |
fetch2gmail serve |
Run the web UI. By default uses the current directory for config, credentials, and token; use --port and --host as needed. See below. |
fetch2gmail run |
Run one fetch cycle. |
fetch2gmail run --dry-run |
Connect to ISP and show what would be imported; no Gmail import, no delete. |
fetch2gmail serve — defaults and options
- Default: The app uses the current working directory as the data directory: it looks for config.json, credentials.json, token.json, and .env in the directory you run the command from. So from a folder that already has those (or at least credentials and token), run
fetch2gmail serveand open http://127.0.0.1:8765. - Options:
--port 8766— Use a different port (default 8765). Useful if 8765 is in use or you run multiple instances.--host 0.0.0.0— Bind to all interfaces (e.g. to reach the UI from another device on the LAN). Default is 127.0.0.1 (localhost only).FETCH2GMAIL_CONFIG=/path/to/config.json— Use a different data directory. The path must be the full path to config.json inside that directory; the app will look for credentials, token, and .env in the same directory. Use this when you runfetch2gmail servefrom one place (e.g. your git clone) but want to use config and data from another (e.g./home/sarah/Desktop/config.json).
Updating
To check your installed version: fetch2gmail --version.
If you installed with pipx, upgrade to the latest release with:
pipx upgrade fetch2gmail
You do not need to stop the service, remove the systemd unit, or uninstall first. The service will use the new version the next time it runs (e.g. after a reboot), or restart it now to pick up the update:
sudo systemctl restart fetch2gmail
Your config, token, and data directory are unchanged.
Uninstall
Machine used only to get the token (no system service): After copying credentials.json and token.json to the server, remove the app: pipx uninstall fetch2gmail. Reinstall with pipx install fetch2gmail if you need to run fetch2gmail auth again later.
Machine where the app runs (system service + app): To remove everything so you can reinstall or run from source and see your changes:
-
Stop and disable the systemd service, then remove the unit file:
sudo systemctl stop fetch2gmail sudo systemctl disable fetch2gmail sudo rm /etc/systemd/system/fetch2gmail.service sudo systemctl daemon-reload
(To confirm the service is gone:
systemctl status fetch2gmailshould report "not found".) -
Uninstall the app:
- If you installed with pipx:
pipx uninstall fetch2gmail - If you installed from source in a venv: deactivate the venv (
deactivate) and delete the project directory (e.g.rm -rf ~/fetch2gmail), or just use a different terminal and run from your dev clone withpip install -e .so the installed copy is no longer used.
- If you installed with pipx:
-
Optionally remove the data directory (config, credentials, token, state, UI password file):
rm -rf /opt/fetch2gmail
Use the path you used as the data directory (e.g.
/opt/fetch2gmailor~/fetch2gmail). Only do this if you no longer need the config or token; back them up first if you might reuse them.
To test local changes: Uninstall the system copy (steps 1 and 2 above), then from your git clone run python3 -m venv .venv, source .venv/bin/activate, pip install -e .. Use that terminal to run fetch2gmail serve (or reinstall the system service later with fetch2gmail install-service and point it at your data directory).
Development / testing from source
To run from a git clone (e.g. to test changes before pushing):
-
Clone and go into the repo:
git clone https://github.com/yourusername/fetch2gmail.git cd fetch2gmail
-
Create and activate a virtual environment:
- Linux / macOS:
python3 -m venv .venvthensource .venv/bin/activate - Windows (PowerShell):
python -m venv .venvthen.venv\Scripts\Activate.ps1 - Windows (Command Prompt):
python -m venv .venvthen.venv\Scripts\activate.bat
- Linux / macOS:
-
Install the package in editable mode (so changes in the repo are used when you run the app):
pip install -e .
Optional, for tests:
pip install -e ".[dev]" -
Run and test (use the same terminal with the venv active; no pipx needed—the editable install provides the
fetch2gmailcommand):fetch2gmail serve— Run the web UI. Default: uses the current directory for config, credentials, and token. So put credentials.json and token.json in your project directory (or any folder), cd there, runfetch2gmail serve, and open http://127.0.0.1:8765. Optionally add--port 8766to use another port. No need to setFETCH2GMAIL_CONFIGwhen you run from the directory that has your data.fetch2gmail auth— Get token. cd into the directory that has credentials.json (or pass--credentialsand--token), then run it; a browser opens for Google sign-in and token.json is written there. Use--port 8766if 8765 is in use.fetch2gmail runorfetch2gmail run --dry-run— If you have config.json and secrets set up (again, run from the data directory or setFETCH2GMAIL_CONFIG).
Using a different data directory: If you want to run fetch2gmail serve from your git clone but use config and data from another folder (e.g. credentials.json and token.json on your Desktop), set FETCH2GMAIL_CONFIG to the full path to config.json in that folder (e.g. FETCH2GMAIL_CONFIG=/home/sarah/Desktop/config.json). config.json does not need to exist yet—the UI creates it when you complete the setup form.
- Before pushing: test the build so the package still builds and you catch errors:
pip install build python -m build
This createsdist/with the sdist and wheel. See docs/PUBLISHING.md for Test PyPI and release steps.
License
MIT. See LICENSE.
Metadata
Release files for fetch2gmail 1.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fetch2gmail-1.3.0.tar.gz | 77.1 kB | With provenance | Details for fetch2gmail-1.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fetch2gmail-1.3.0-py3-none-any.whl | Python 3 | none | any | Details for fetch2gmail-1.3.0-py3-none-any.whl |
Total release size: 148.1 kB
Release files / fetch2gmail-1.3.0.tar.gz
| Download URL | fetch2gmail-1.3.0.tar.gz |
|---|---|
| Size | 77.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
da957b7c1abc25f5f103b165584f8283c80c74761cf616d89e65618d84139c7a
|
|
BLAKE2b-256 checksum How to use checksums |
00940852c876f70e10299b5fc58f672e90472a693bb69f5b08492f068a7c880d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / fetch2gmail-1.3.0-py3-none-any.whl
| Download URL | fetch2gmail-1.3.0-py3-none-any.whl |
|---|---|
| Size | 71.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c5a194aac6198ae6742549cddcacc80bc5cf9cbfac6f0619e8ff25ee3dd1f999
|
|
BLAKE2b-256 checksum How to use checksums |
f64087f9c2142ab2bbc39279280f6f79fd7808017f607fa679ddf67d305d136e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for fetch2gmail 1.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for fetch2gmail-1.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.