fetch2gmail 1.0.1__tar.gz → 1.0.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fetch2gmail-1.0.3/PKG-INFO +286 -0
- fetch2gmail-1.0.3/README.md +255 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/pyproject.toml +2 -1
- fetch2gmail-1.0.3/src/fetch2gmail.egg-info/PKG-INFO +286 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/SOURCES.txt +1 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/requires.txt +1 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/auth_server.py +1 -1
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/cli.py +93 -0
- fetch2gmail-1.0.3/src/fetcher/ui_auth.py +57 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/web_ui.py +54 -9
- fetch2gmail-1.0.1/PKG-INFO +0 -679
- fetch2gmail-1.0.1/README.md +0 -649
- fetch2gmail-1.0.1/src/fetch2gmail.egg-info/PKG-INFO +0 -679
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/LICENSE +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/setup.cfg +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/dependency_links.txt +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/entry_points.txt +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetch2gmail.egg-info/top_level.txt +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/__init__.py +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/auth_ui.py +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/config.py +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/env_file.py +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/gmail_client.py +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/imap_client.py +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/log_buffer.py +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/run.py +0 -0
- {fetch2gmail-1.0.1 → fetch2gmail-1.0.3}/src/fetcher/state.py +0 -0
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fetch2gmail
|
|
3
|
+
Version: 1.0.3
|
|
4
|
+
Summary: Self-hosted email fetcher: IMAP to Gmail API import with idempotent state tracking
|
|
5
|
+
Author: Fetch2Gmail Contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: email,imap,gmail,fetch,self-hosted
|
|
8
|
+
Classifier: Development Status :: 4 - Beta
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Topic :: Communications :: Email
|
|
15
|
+
Requires-Python: >=3.11
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Requires-Dist: google-auth>=2.23.0
|
|
19
|
+
Requires-Dist: google-auth-oauthlib>=1.1.0
|
|
20
|
+
Requires-Dist: google-api-python-client>=2.100.0
|
|
21
|
+
Requires-Dist: fastapi>=0.104.0
|
|
22
|
+
Requires-Dist: uvicorn[standard]>=0.24.0
|
|
23
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
24
|
+
Requires-Dist: python-multipart>=0.0.6
|
|
25
|
+
Requires-Dist: cryptography>=42.0.0
|
|
26
|
+
Requires-Dist: bcrypt>=4.0.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
29
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# Fetch2Gmail
|
|
33
|
+
|
|
34
|
+
Self-hosted email fetcher: **IMAP (ISP mailbox) → Gmail API import**. Replaces Gmail’s deprecated POP3 fetch.
|
|
35
|
+
|
|
36
|
+
- Polls an ISP mailbox via **IMAPS** (port 993).
|
|
37
|
+
- Imports messages with **Gmail API** (not SMTP); applies a Gmail label, preserves headers and date.
|
|
38
|
+
- Deletes from ISP only after Gmail confirms import. **Idempotent** (UID + message hash).
|
|
39
|
+
|
|
40
|
+
**Requirements:** Python 3.11+, IMAP credentials, Google Cloud project with Gmail API and OAuth2 (Web application).
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Use case 1: Headless Debian server
|
|
45
|
+
|
|
46
|
+
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.
|
|
47
|
+
|
|
48
|
+
### On a computer with a browser (Windows or Linux)
|
|
49
|
+
|
|
50
|
+
**Step 1. Get credentials.json from Google Cloud**
|
|
51
|
+
|
|
52
|
+
1. Go to [Google Cloud Console](https://console.cloud.google.com/) → create or select a project.
|
|
53
|
+
2. **APIs & Services → Library** → search “Gmail API” → **Enable**.
|
|
54
|
+
3. **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.
|
|
55
|
+
4. **Credentials → Create credentials → OAuth client ID** → Application type **Web application**.
|
|
56
|
+
5. **Authorized redirect URIs** → add `http://127.0.0.1:8765/auth/gmail/callback` and `http://localhost:8765/auth/gmail/callback`.
|
|
57
|
+
6. Create → download the JSON. Save it as **credentials.json** in a folder (e.g. Desktop or `~/fetch2gmail-auth`).
|
|
58
|
+
|
|
59
|
+
**Step 2. Install Python 3.11+ and pipx**
|
|
60
|
+
|
|
61
|
+
- **Windows:** Install [Python 3.11+](https://www.python.org/downloads/) (check “Add Python to PATH”). Open Command Prompt or PowerShell: `pip install pipx` then `pipx ensurepath`. Close and reopen the terminal.
|
|
62
|
+
- **Linux:** `sudo apt install pipx` then `pipx ensurepath`. Reopen the terminal (or run `source ~/.bashrc`) so `~/.local/bin` is on PATH.
|
|
63
|
+
|
|
64
|
+
**Step 3. Install fetch2gmail**
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pipx install fetch2gmail
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Step 4. Get the token**
|
|
71
|
+
|
|
72
|
+
In the **same folder** where **credentials.json** is, run:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
fetch2gmail auth
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
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.
|
|
79
|
+
|
|
80
|
+
**Step 5. Copy these two files to the server**
|
|
81
|
+
|
|
82
|
+
Copy **credentials.json** and **token.json** to your Debian server. You will put them in the app data directory in the next section.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
### On the Debian server
|
|
87
|
+
|
|
88
|
+
**Step 6. Create the data directory and add the files**
|
|
89
|
+
|
|
90
|
+
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:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
sudo mkdir -p /opt/fetch2gmail
|
|
94
|
+
sudo chown "$USER" /opt/fetch2gmail
|
|
95
|
+
# Copy credentials.json and token.json into /opt/fetch2gmail (from step 5)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Use the same path in the steps below (replace `/opt/fetch2gmail` and the username if you use something else).
|
|
99
|
+
|
|
100
|
+
**Step 7. Install pipx and fetch2gmail on the server**
|
|
101
|
+
|
|
102
|
+
Run these from **any directory** (you do not need to be in `/opt/fetch2gmail`):
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
sudo apt install pipx
|
|
106
|
+
pipx ensurepath
|
|
107
|
+
# Log out and back in (or source ~/.bashrc) so ~/.local/bin is on PATH
|
|
108
|
+
pipx install fetch2gmail
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
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. For step 8 you **cd** into `/opt/fetch2gmail` before running `set-ui-password` so the password file is stored there.
|
|
112
|
+
|
|
113
|
+
**Step 8. Set the UI username and password**
|
|
114
|
+
|
|
115
|
+
Run once so only you can access the web UI (username and hashed password are stored in **.ui_auth**):
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
cd /opt/fetch2gmail
|
|
119
|
+
fetch2gmail set-ui-password
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Enter a username and password when prompted.
|
|
123
|
+
|
|
124
|
+
**Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
|
|
125
|
+
|
|
126
|
+
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:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail -o /tmp/fetch2gmail.service
|
|
130
|
+
sudo mv /tmp/fetch2gmail.service /etc/systemd/system/fetch2gmail.service
|
|
131
|
+
sudo systemctl daemon-reload
|
|
132
|
+
sudo systemctl enable fetch2gmail
|
|
133
|
+
sudo systemctl start fetch2gmail
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
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`.
|
|
137
|
+
|
|
138
|
+
Alternatively, print the unit file and pipe it into place:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
|
|
142
|
+
sudo systemctl daemon-reload
|
|
143
|
+
sudo systemctl enable fetch2gmail
|
|
144
|
+
sudo systemctl start fetch2gmail
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
**Step 10. Configure ISP mail in the web UI**
|
|
148
|
+
|
|
149
|
+
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.
|
|
150
|
+
|
|
151
|
+
**Done.** To watch logs: `journalctl -u fetch2gmail -f`.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Use case 2: Device with a browser (one machine)
|
|
156
|
+
|
|
157
|
+
Everything runs on **one machine** (laptop or desktop) that has a browser. You sign in with Google in the web UI — the redirect works because you open the UI on localhost. You do **not** need to run `fetch2gmail auth` or set a UI password. Follow the steps in order.
|
|
158
|
+
|
|
159
|
+
**Step 1. Get credentials.json from Google Cloud**
|
|
160
|
+
|
|
161
|
+
Same as Use case 1, step 1. Save **credentials.json** in a folder you will use as the app data directory (e.g. `~/fetch2gmail`).
|
|
162
|
+
|
|
163
|
+
**Step 2. Install Python 3.11+ and pipx**
|
|
164
|
+
|
|
165
|
+
Same as Use case 1, step 2 (Windows or Linux).
|
|
166
|
+
|
|
167
|
+
**Step 3. Install fetch2gmail**
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
pipx install fetch2gmail
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
**Step 4. Create the data directory and add credentials**
|
|
174
|
+
|
|
175
|
+
Create the folder and put **credentials.json** there (you do not have a token yet):
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
mkdir -p ~/fetch2gmail
|
|
179
|
+
# Copy credentials.json into ~/fetch2gmail
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
|
|
183
|
+
|
|
184
|
+
**Step 5. Install and enable the systemd service**
|
|
185
|
+
|
|
186
|
+
Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
fetch2gmail install-service --user YOUR_USER --dir /home/YOUR_USER/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
|
|
190
|
+
sudo systemctl daemon-reload
|
|
191
|
+
sudo systemctl enable fetch2gmail
|
|
192
|
+
sudo systemctl start fetch2gmail
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
**Step 6. Sign in with Google in the web UI**
|
|
196
|
+
|
|
197
|
+
Open **http://127.0.0.1:8765** in your browser (**use localhost** so the Google OAuth redirect works). You will see **Sign in with Google** — click it, sign in with the Gmail account that will receive the imported mail, and click Allow. The app saves **token.json** in your data directory. You are now signed in.
|
|
198
|
+
|
|
199
|
+
**Step 7. Configure ISP mail in the web UI**
|
|
200
|
+
|
|
201
|
+
Use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, then 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).
|
|
202
|
+
|
|
203
|
+
**Done.**
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Reference
|
|
208
|
+
|
|
209
|
+
### OAuth redirect URI
|
|
210
|
+
|
|
211
|
+
Your Google OAuth client must use **Web application** (not Desktop) and have these **Authorized redirect URIs**:
|
|
212
|
+
|
|
213
|
+
- `http://127.0.0.1:8765/auth/gmail/callback`
|
|
214
|
+
- `http://localhost:8765/auth/gmail/callback`
|
|
215
|
+
|
|
216
|
+
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).
|
|
217
|
+
|
|
218
|
+
### Poll interval
|
|
219
|
+
|
|
220
|
+
The app runs the fetch every 5 minutes by default (background poller in the same process as the web UI). You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
|
|
221
|
+
|
|
222
|
+
### Data directory
|
|
223
|
+
|
|
224
|
+
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.
|
|
225
|
+
|
|
226
|
+
### Security
|
|
227
|
+
|
|
228
|
+
- Do not commit **credentials.json**, **token.json**, or **config.json** with secrets. Restrict file permissions to the user running the service.
|
|
229
|
+
- On the server, the UI is protected by the username and password you set with **`fetch2gmail set-ui-password`** (stored as a hash in **.ui_auth**). There is no Google sign-in on the server when **token.json** is already there.
|
|
230
|
+
- The Gmail scope requested is **gmail.modify** (read and modify labels/messages only).
|
|
231
|
+
|
|
232
|
+
### CLI
|
|
233
|
+
|
|
234
|
+
| Command | Purpose |
|
|
235
|
+
|--------|---------|
|
|
236
|
+
| `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
|
|
237
|
+
| `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
|
|
238
|
+
| `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
|
|
239
|
+
| `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
|
|
240
|
+
| `fetch2gmail run` | Run one fetch cycle. |
|
|
241
|
+
| `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
|
|
242
|
+
|
|
243
|
+
### Uninstall (computer used only for token)
|
|
244
|
+
|
|
245
|
+
After copying **credentials.json** and **token.json** to the server, you can remove fetch2gmail from that computer: `pipx uninstall fetch2gmail`. Reinstall with `pipx install fetch2gmail` if you need to run `fetch2gmail auth` again later.
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## Development / testing from source
|
|
250
|
+
|
|
251
|
+
To run from a git clone (e.g. to test changes before pushing):
|
|
252
|
+
|
|
253
|
+
1. **Clone and go into the repo:**
|
|
254
|
+
```bash
|
|
255
|
+
git clone https://github.com/yourusername/fetch2gmail.git
|
|
256
|
+
cd fetch2gmail
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
2. **Create and activate a virtual environment:**
|
|
260
|
+
- **Linux / macOS:** `python3 -m venv .venv` then `source .venv/bin/activate`
|
|
261
|
+
- **Windows (PowerShell):** `python -m venv .venv` then `.venv\Scripts\Activate.ps1`
|
|
262
|
+
- **Windows (Command Prompt):** `python -m venv .venv` then `.venv\Scripts\activate.bat`
|
|
263
|
+
|
|
264
|
+
3. **Install the package in editable mode** (so changes in the repo are used when you run the app):
|
|
265
|
+
```bash
|
|
266
|
+
pip install -e .
|
|
267
|
+
```
|
|
268
|
+
Optional, for tests: `pip install -e ".[dev]"`
|
|
269
|
+
|
|
270
|
+
4. **Run and test** (use the same terminal with the venv active):
|
|
271
|
+
- `fetch2gmail serve` — web UI at http://127.0.0.1:8765
|
|
272
|
+
- `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
|
|
273
|
+
- `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
|
|
274
|
+
|
|
275
|
+
5. **Before pushing: test the build** so the package still builds and you catch errors:
|
|
276
|
+
```bash
|
|
277
|
+
pip install build
|
|
278
|
+
python -m build
|
|
279
|
+
```
|
|
280
|
+
This creates `dist/` with the sdist and wheel. See **docs/PUBLISHING.md** for Test PyPI and release steps.
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
## License
|
|
285
|
+
|
|
286
|
+
MIT. See **LICENSE**.
|
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
# Fetch2Gmail
|
|
2
|
+
|
|
3
|
+
Self-hosted email fetcher: **IMAP (ISP mailbox) → Gmail API import**. Replaces Gmail’s deprecated POP3 fetch.
|
|
4
|
+
|
|
5
|
+
- Polls an ISP mailbox via **IMAPS** (port 993).
|
|
6
|
+
- Imports messages with **Gmail API** (not SMTP); applies a Gmail label, preserves headers and date.
|
|
7
|
+
- Deletes from ISP only after Gmail confirms import. **Idempotent** (UID + message hash).
|
|
8
|
+
|
|
9
|
+
**Requirements:** Python 3.11+, IMAP credentials, Google Cloud project with Gmail API and OAuth2 (Web application).
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Use case 1: Headless Debian server
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
### On a computer with a browser (Windows or Linux)
|
|
18
|
+
|
|
19
|
+
**Step 1. Get credentials.json from Google Cloud**
|
|
20
|
+
|
|
21
|
+
1. Go to [Google Cloud Console](https://console.cloud.google.com/) → create or select a project.
|
|
22
|
+
2. **APIs & Services → Library** → search “Gmail API” → **Enable**.
|
|
23
|
+
3. **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.
|
|
24
|
+
4. **Credentials → Create credentials → OAuth client ID** → Application type **Web application**.
|
|
25
|
+
5. **Authorized redirect URIs** → add `http://127.0.0.1:8765/auth/gmail/callback` and `http://localhost:8765/auth/gmail/callback`.
|
|
26
|
+
6. Create → download the JSON. Save it as **credentials.json** in a folder (e.g. Desktop or `~/fetch2gmail-auth`).
|
|
27
|
+
|
|
28
|
+
**Step 2. Install Python 3.11+ and pipx**
|
|
29
|
+
|
|
30
|
+
- **Windows:** Install [Python 3.11+](https://www.python.org/downloads/) (check “Add Python to PATH”). Open Command Prompt or PowerShell: `pip install pipx` then `pipx ensurepath`. Close and reopen the terminal.
|
|
31
|
+
- **Linux:** `sudo apt install pipx` then `pipx ensurepath`. Reopen the terminal (or run `source ~/.bashrc`) so `~/.local/bin` is on PATH.
|
|
32
|
+
|
|
33
|
+
**Step 3. Install fetch2gmail**
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pipx install fetch2gmail
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
**Step 4. Get the token**
|
|
40
|
+
|
|
41
|
+
In the **same folder** where **credentials.json** is, run:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
fetch2gmail auth
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
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.
|
|
48
|
+
|
|
49
|
+
**Step 5. Copy these two files to the server**
|
|
50
|
+
|
|
51
|
+
Copy **credentials.json** and **token.json** to your Debian server. You will put them in the app data directory in the next section.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
### On the Debian server
|
|
56
|
+
|
|
57
|
+
**Step 6. Create the data directory and add the files**
|
|
58
|
+
|
|
59
|
+
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:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
sudo mkdir -p /opt/fetch2gmail
|
|
63
|
+
sudo chown "$USER" /opt/fetch2gmail
|
|
64
|
+
# Copy credentials.json and token.json into /opt/fetch2gmail (from step 5)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Use the same path in the steps below (replace `/opt/fetch2gmail` and the username if you use something else).
|
|
68
|
+
|
|
69
|
+
**Step 7. Install pipx and fetch2gmail on the server**
|
|
70
|
+
|
|
71
|
+
Run these from **any directory** (you do not need to be in `/opt/fetch2gmail`):
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
sudo apt install pipx
|
|
75
|
+
pipx ensurepath
|
|
76
|
+
# Log out and back in (or source ~/.bashrc) so ~/.local/bin is on PATH
|
|
77
|
+
pipx install fetch2gmail
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
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. For step 8 you **cd** into `/opt/fetch2gmail` before running `set-ui-password` so the password file is stored there.
|
|
81
|
+
|
|
82
|
+
**Step 8. Set the UI username and password**
|
|
83
|
+
|
|
84
|
+
Run once so only you can access the web UI (username and hashed password are stored in **.ui_auth**):
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
cd /opt/fetch2gmail
|
|
88
|
+
fetch2gmail set-ui-password
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Enter a username and password when prompted.
|
|
92
|
+
|
|
93
|
+
**Step 9. Install and enable the systemd service (one service: web UI + background fetch)**
|
|
94
|
+
|
|
95
|
+
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:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail -o /tmp/fetch2gmail.service
|
|
99
|
+
sudo mv /tmp/fetch2gmail.service /etc/systemd/system/fetch2gmail.service
|
|
100
|
+
sudo systemctl daemon-reload
|
|
101
|
+
sudo systemctl enable fetch2gmail
|
|
102
|
+
sudo systemctl start fetch2gmail
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
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`.
|
|
106
|
+
|
|
107
|
+
Alternatively, print the unit file and pipe it into place:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
fetch2gmail install-service --user YOUR_USER --dir /opt/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
|
|
111
|
+
sudo systemctl daemon-reload
|
|
112
|
+
sudo systemctl enable fetch2gmail
|
|
113
|
+
sudo systemctl start fetch2gmail
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
**Step 10. Configure ISP mail in the web UI**
|
|
117
|
+
|
|
118
|
+
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.
|
|
119
|
+
|
|
120
|
+
**Done.** To watch logs: `journalctl -u fetch2gmail -f`.
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Use case 2: Device with a browser (one machine)
|
|
125
|
+
|
|
126
|
+
Everything runs on **one machine** (laptop or desktop) that has a browser. You sign in with Google in the web UI — the redirect works because you open the UI on localhost. You do **not** need to run `fetch2gmail auth` or set a UI password. Follow the steps in order.
|
|
127
|
+
|
|
128
|
+
**Step 1. Get credentials.json from Google Cloud**
|
|
129
|
+
|
|
130
|
+
Same as Use case 1, step 1. Save **credentials.json** in a folder you will use as the app data directory (e.g. `~/fetch2gmail`).
|
|
131
|
+
|
|
132
|
+
**Step 2. Install Python 3.11+ and pipx**
|
|
133
|
+
|
|
134
|
+
Same as Use case 1, step 2 (Windows or Linux).
|
|
135
|
+
|
|
136
|
+
**Step 3. Install fetch2gmail**
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
pipx install fetch2gmail
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
**Step 4. Create the data directory and add credentials**
|
|
143
|
+
|
|
144
|
+
Create the folder and put **credentials.json** there (you do not have a token yet):
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
mkdir -p ~/fetch2gmail
|
|
148
|
+
# Copy credentials.json into ~/fetch2gmail
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Use the same path in the steps below (replace `~/fetch2gmail` if you use something else).
|
|
152
|
+
|
|
153
|
+
**Step 5. Install and enable the systemd service**
|
|
154
|
+
|
|
155
|
+
Same as Use case 1, step 9: one service (web UI + background fetch). Replace **YOUR_USER** and the path with yours:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
fetch2gmail install-service --user YOUR_USER --dir /home/YOUR_USER/fetch2gmail | sudo tee /etc/systemd/system/fetch2gmail.service > /dev/null
|
|
159
|
+
sudo systemctl daemon-reload
|
|
160
|
+
sudo systemctl enable fetch2gmail
|
|
161
|
+
sudo systemctl start fetch2gmail
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**Step 6. Sign in with Google in the web UI**
|
|
165
|
+
|
|
166
|
+
Open **http://127.0.0.1:8765** in your browser (**use localhost** so the Google OAuth redirect works). You will see **Sign in with Google** — click it, sign in with the Gmail account that will receive the imported mail, and click Allow. The app saves **token.json** in your data directory. You are now signed in.
|
|
167
|
+
|
|
168
|
+
**Step 7. Configure ISP mail in the web UI**
|
|
169
|
+
|
|
170
|
+
Use the **initial setup** form to enter your IMAP host, username, password, mailbox, and Gmail label, then 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).
|
|
171
|
+
|
|
172
|
+
**Done.**
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## Reference
|
|
177
|
+
|
|
178
|
+
### OAuth redirect URI
|
|
179
|
+
|
|
180
|
+
Your Google OAuth client must use **Web application** (not Desktop) and have these **Authorized redirect URIs**:
|
|
181
|
+
|
|
182
|
+
- `http://127.0.0.1:8765/auth/gmail/callback`
|
|
183
|
+
- `http://localhost:8765/auth/gmail/callback`
|
|
184
|
+
|
|
185
|
+
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).
|
|
186
|
+
|
|
187
|
+
### Poll interval
|
|
188
|
+
|
|
189
|
+
The app runs the fetch every 5 minutes by default (background poller in the same process as the web UI). You can change the interval in the web UI (Config) or in **config.json** (`poll_interval_minutes`).
|
|
190
|
+
|
|
191
|
+
### Data directory
|
|
192
|
+
|
|
193
|
+
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.
|
|
194
|
+
|
|
195
|
+
### Security
|
|
196
|
+
|
|
197
|
+
- Do not commit **credentials.json**, **token.json**, or **config.json** with secrets. Restrict file permissions to the user running the service.
|
|
198
|
+
- On the server, the UI is protected by the username and password you set with **`fetch2gmail set-ui-password`** (stored as a hash in **.ui_auth**). There is no Google sign-in on the server when **token.json** is already there.
|
|
199
|
+
- The Gmail scope requested is **gmail.modify** (read and modify labels/messages only).
|
|
200
|
+
|
|
201
|
+
### CLI
|
|
202
|
+
|
|
203
|
+
| Command | Purpose |
|
|
204
|
+
|--------|---------|
|
|
205
|
+
| `fetch2gmail auth` | Get **token.json** on a machine with a browser (opens http://127.0.0.1:8765). |
|
|
206
|
+
| `fetch2gmail set-ui-password` | Set UI username and password (hash in **.ui_auth**). |
|
|
207
|
+
| `fetch2gmail install-service` | Generate systemd unit file (one service: web UI + background fetch). Use `--user`, `--dir`, and optionally `--output` or pipe to `sudo tee`. |
|
|
208
|
+
| `fetch2gmail serve` | Run the web UI (default: localhost only; use `--host 0.0.0.0` to bind to all interfaces). |
|
|
209
|
+
| `fetch2gmail run` | Run one fetch cycle. |
|
|
210
|
+
| `fetch2gmail run --dry-run` | Connect to ISP and show what would be imported; no Gmail import, no delete. |
|
|
211
|
+
|
|
212
|
+
### Uninstall (computer used only for token)
|
|
213
|
+
|
|
214
|
+
After copying **credentials.json** and **token.json** to the server, you can remove fetch2gmail from that computer: `pipx uninstall fetch2gmail`. Reinstall with `pipx install fetch2gmail` if you need to run `fetch2gmail auth` again later.
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## Development / testing from source
|
|
219
|
+
|
|
220
|
+
To run from a git clone (e.g. to test changes before pushing):
|
|
221
|
+
|
|
222
|
+
1. **Clone and go into the repo:**
|
|
223
|
+
```bash
|
|
224
|
+
git clone https://github.com/yourusername/fetch2gmail.git
|
|
225
|
+
cd fetch2gmail
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
2. **Create and activate a virtual environment:**
|
|
229
|
+
- **Linux / macOS:** `python3 -m venv .venv` then `source .venv/bin/activate`
|
|
230
|
+
- **Windows (PowerShell):** `python -m venv .venv` then `.venv\Scripts\Activate.ps1`
|
|
231
|
+
- **Windows (Command Prompt):** `python -m venv .venv` then `.venv\Scripts\activate.bat`
|
|
232
|
+
|
|
233
|
+
3. **Install the package in editable mode** (so changes in the repo are used when you run the app):
|
|
234
|
+
```bash
|
|
235
|
+
pip install -e .
|
|
236
|
+
```
|
|
237
|
+
Optional, for tests: `pip install -e ".[dev]"`
|
|
238
|
+
|
|
239
|
+
4. **Run and test** (use the same terminal with the venv active):
|
|
240
|
+
- `fetch2gmail serve` — web UI at http://127.0.0.1:8765
|
|
241
|
+
- `fetch2gmail auth` — get token (put **credentials.json** in the current directory first)
|
|
242
|
+
- `fetch2gmail run` or `fetch2gmail run --dry-run` — if you have **config.json** and secrets set up
|
|
243
|
+
|
|
244
|
+
5. **Before pushing: test the build** so the package still builds and you catch errors:
|
|
245
|
+
```bash
|
|
246
|
+
pip install build
|
|
247
|
+
python -m build
|
|
248
|
+
```
|
|
249
|
+
This creates `dist/` with the sdist and wheel. See **docs/PUBLISHING.md** for Test PyPI and release steps.
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## License
|
|
254
|
+
|
|
255
|
+
MIT. See **LICENSE**.
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "fetch2gmail"
|
|
7
|
-
version = "1.0.
|
|
7
|
+
version = "1.0.3"
|
|
8
8
|
description = "Self-hosted email fetcher: IMAP to Gmail API import with idempotent state tracking"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
@@ -30,6 +30,7 @@ dependencies = [
|
|
|
30
30
|
"python-dotenv>=1.0.0",
|
|
31
31
|
"python-multipart>=0.0.6",
|
|
32
32
|
"cryptography>=42.0.0",
|
|
33
|
+
"bcrypt>=4.0.0",
|
|
33
34
|
]
|
|
34
35
|
|
|
35
36
|
[project.optional-dependencies]
|