Kind Reach

Send like a Human. Deliver like a Pro.

Send friendly, one-to-one emails from your own Gmail account to a list of contacts (for example, your yoga students or community), as multi-step campaigns that automatically stop following up with anyone who replies.

Kind Reach runs on your own computer, in your web browser. Your contacts and emails never leave your machine except to go through your own Gmail. It does not need to stay running — when you open it again, it picks up any campaign exactly where it left off.

This guide assumes no technical background. Follow it top to bottom. It takes about 20–30 minutes the first time (most of that is the one-time Google setup). After that, starting the app takes a few seconds.

---

Table of contents

1. What you need
2. Install Python
3. Get the Kind Reach files
4. One-time app setup
5. Connect your Gmail (one-time Google setup)
6. Starting and stopping the app
7. Using the app
8. Backups & restore
9. Recommended first run (safe rehearsal)
10. Good sending practice
11. Troubleshooting
12. Where your data lives
13. Frequently asked questions
14. Privacy & security
15. Contributing
16. License

---

1. What you need

• A Windows 10/11 PC or a Mac.
• A Gmail or Google Workspace account you want to send from.
• About 30 minutes for first-time setup.
• Internet access (for setup and for sending email).

Throughout this guide, "type this command" means: type it into a terminal window (explained below) and press Enter.

How to open a terminal

• Windows: press the Start button, type PowerShell, click Windows PowerShell.
• Mac: press Cmd + Space, type Terminal, press Enter.

A terminal is just a window where you type commands. Don't worry — you only need to copy/paste a handful of them.

---

2. Install Python

Python is the free software that runs Kind Reach. You install it once.

Windows

1. Go to https://www.python.org/downloads/.
2. Click the big Download Python 3.x button.
3. Run the downloaded file.
4. Very important: on the first screen, tick the box "Add python.exe to PATH" at the bottom, then click Install Now.
5. When it finishes, click Close.

To check it worked, open PowerShell and type:

python --version

You should see something like Python 3.12.x (any 3.11 or newer is fine).

Mac

1. Go to https://www.python.org/downloads/.
2. Click the big Download Python 3.x button.
3. Open the downloaded .pkg file and click through the installer (Continue → Agree → Install). Enter your Mac password if asked.

To check it worked, open Terminal and type:

python3 --version

You should see Python 3.12.x (any 3.11 or newer is fine).

Mac note: on Mac you type python3 and pip3 everywhere this guide says python and pip. On Windows you use python and pip as written.

---

3. Get the Kind Reach files

Put the KindReach folder somewhere easy to find, for example:

• Windows: C:\KindReach
• Mac: your Documents folder, e.g. ~/Documents/KindReach

If you downloaded the project as a .zip, right-click it and choose Extract All (Windows) or double-click it (Mac), then move the resulting KindReach folder to the location above.

You should end up with a folder that contains files named run.py, requirements.txt, a README.md, and an app folder.

Point the terminal at that folder

In your terminal, type cd (the letters c, d, then a space) and then drag the KindReach folder from your file explorer into the terminal window and press Enter. For example:

• Windows: cd C:\KindReach
• Mac: cd ~/Documents/KindReach

Everything in the next sections is typed in this same terminal window.

---

4. One-time app setup

This creates a private, self-contained environment for the app and installs the pieces it needs. You only do this once.

Windows (PowerShell):

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

Mac (Terminal):

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

The last command downloads the required components and takes a minute or two. When it finishes without red error text, setup is done.

Windows: "running scripts is disabled" error? Run this once, then try the Activate.ps1 line again:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Answer Y if prompted.

You do not need to repeat Section 4 next time — see Section 6.

---

5. Connect your Gmail (one-time Google setup)

Kind Reach sends through your own Gmail using Google's official, secure sign-in. Google requires a one-time setup so the app is allowed to send on your behalf. It's free. Follow these steps carefully.

You can do Section 6 (start the app) first if you like, and come back here — the app's Settings page also shows these steps and the exact address you'll need in step E.

A. Create a Google project

1. Go to https://console.cloud.google.com/. Sign in with the Gmail you'll send from.
2. At the top, click the project dropdown → New Project.
3. Name it Kind Reach and click Create. Wait a few seconds, then make sure that new project is selected in the top dropdown.

B. Turn on the Gmail API

1. In the search bar at the top, type Gmail API and click it.
2. Click Enable.

C. Set up the consent screen

1. In the left menu (☰) go to APIs & Services → OAuth consent screen (in newer Google interfaces this is called Google Auth Platform; click Get started).
2. Fill in:
   • App name: Kind Reach
   • User support email: your email
   • Audience: choose External
   • Contact information: your email
   • Tick the agreement box → Create / Continue.

D. Add yourself as a test user

1. Left menu → Audience (or "OAuth consent screen" → scroll down).
2. Find Test users → + Add users → type your own Gmail address → Save.

Leaving the app in "Testing" mode is correct and fine for personal use — no Google review is needed. If you skip this step, connecting will fail with an "access denied" message.

E. Create the credentials file

1. Left menu → Credentials (or Clients).

2. Click + Create credentials → OAuth client ID (or + Create client).

3. Application type: Web application.

4. Under Authorized redirect URIs, click + Add URI and paste this exactly:

   http://127.0.0.1:5000/settings/gmail/callback
   

5. Click Create.

6. In the dialog (or the ⬇ download button next to the client), click Download JSON.

F. Put the file in place

1. Rename the downloaded file to exactly:

   client_secret.json
   

2. Move it into the app's credentials folder:

   • Windows: C:\KindReach\data\credentials\client_secret.json
   • Mac: ~/Documents/KindReach/data/credentials/client_secret.json

   (The data and data/credentials folders are created automatically the first time you start the app — see Section 6. If you don't see them yet, start the app once, then come back and place the file.)

G. Connect

1. Start the app (Section 6) and open it in your browser.
2. Go to Settings → Connect Gmail.
3. Choose your Google account and approve. Google may warn the app is "unverified" because it's your own personal project — click Advanced → Go to Kind Reach (unsafe) to continue. (It's your own app sending from your own account; this warning is normal for personal projects.)
4. You'll return to Settings showing Connected as your@email. Done.

---

6. Starting and stopping the app

Start it

Open a terminal, go to the folder, activate the environment, and run:

Windows:

cd C:\KindReach
.\.venv\Scripts\Activate.ps1
python run.py

Mac:

cd ~/Documents/KindReach
source .venv/bin/activate
python3 run.py

Your web browser opens automatically at http://127.0.0.1:5000. If it doesn't, open that address in your browser yourself.

Stop it

Click the terminal window and press Ctrl + C (on Mac too). You can also just close the terminal window. It is safe to stop at any time — campaign progress is saved and resumes when you start it again.

Does it need to stay open? Only while you actually want emails going out. Campaigns are paced over hours/days; keep the app open during the times you want it sending, and reopen it later — it continues automatically.

---

7. Using the app

The menu at the top has six sections:

• Dashboard — overview: contacts, running campaigns, sent today, replies, running-campaign progress, and recent activity. The stat tiles are clickable. The page auto-refreshes about once a minute so the numbers stay current while the engine is running, and there's a Run engine now button to trigger an immediate pass. Times are shown in your timezone (set in Settings).
• Contacts — add/edit/delete people, tag them into groups, and import a CSV or Excel (.xlsx) file in bulk (it shows a preview and lets you match columns before saving). Mark anyone "do not email" to permanently exclude them from every campaign.
• Templates — write reusable emails with formatting, emojis, resizable inline images (click an image in the editor to set its width or add a link), and attachments. Use variables like {First Name} that get filled in per person. Set optional preview text (the grey snippet shown in the inbox). Preview on desktop/mobile and send yourself a test.
• Campaigns — build a sequence of one or more emails with a wait time (in hours) between them, choose recipients (by tag, individually, or all eligible), preview each step, and launch. Follow-ups only go out if the person hasn't replied. A stats bar shows how many recipients are in each state.
• History — every email actually sent, with the exact content, reply status, filters (campaign / status / search), plus per-campaign breakdowns.
• Settings — connect/disconnect Gmail, set the From name recipients see, your timezone, the daily send limit, ramp-up vs fixed-cap pacing, delay between sends, dry-run mode, and Backup & restore. Also includes a test-send tool.

Variables you can use in subjects, preview text, and bodies: {First Name}, {Last Name}, {Email}, {Phone}.

Campaign recipient states (shown on the campaign page and its stats bar):

• Pending — added, but the campaign hasn't been started yet
• Waiting — campaign started, first email not sent to them yet
• Active — first email sent, more steps still to come
• Completed — all steps have been sent
• Replied — a reply was received (their sequence ends)
• Unsubscribed / Failed — excluded (do-not-email) or a send error

Pause / Stop / Reopen / Reply:

• Pause suspends a running campaign; Resume continues where it left off.
• Stop ends a campaign permanently and removes its recipients (the sent history is always kept).
• Reopen as draft on a completed/stopped campaign lets you reuse its steps and settings for a fresh run.
• If a contact replies to any email, the app automatically stops sending them further steps — even if their sequence had already finished.

---

8. Backups & restore

All your data lives in one folder on your computer; if that machine is lost or wiped, the data is gone. Keep regular backups.

Make a backup: Settings → Backup & restore → Download backup (.zip). The file contains your database, attachments, and Gmail OAuth token. Treat it like a password — anyone with it can read your data and send mail as you. Keep a copy in cloud storage (Google Drive, Dropbox) or on a USB drive.

Restore a backup: Settings → Backup & restore → choose the .zip and tick the confirmation → Restore from backup. The app:

1. Pauses the background scheduler.
2. Moves the current data aside into data/pre_restore_<timestamp>/ (a safety copy — nothing is destroyed if anything goes wrong).
3. Extracts the backup.
4. Applies schema migrations so older backups still load.
5. Flips any campaigns that were running/paused → completed (and their in_progress recipients → completed) so the engine doesn't unexpectedly resume sending on the restored machine.

After a restore on a new computer you may still want to Settings → Connect Gmail if Google considers the token invalid on the new device.

---

9. Recommended first run (safe rehearsal)

Do this once before emailing real people, so you can see exactly what happens with zero risk.

1. Contacts → Import your list (or add one or two contacts manually). Add a contact whose email is your own address.
2. Settings → turn Dry-run mode ON and Save settings. In dry-run, the app pretends to send: everything is logged but no email is sent.
3. Templates → create a simple template, e.g. subject Hi {First Name} and a short body. Use Save & preview to see it.
4. Campaigns → create a campaign, add one step using your template, add only yourself as the recipient, and Launch.
5. On the Dashboard, click Run engine now. Check History — you'll see a "dry_run" entry with the exact content.
6. Happy with it? Settings → turn Dry-run mode OFF, Save. Repeat a real test with just your own email and confirm it arrives in your inbox.
7. Now build the real campaign, add your real recipients, and launch. Leave the app open during the hours you want it to send.

---

10. Good sending practice

Kind Reach already follows email best practices, but a few habits keep your messages out of spam folders:

• Start small. Use the Conservative ramp-up sending mode for new campaigns. It begins with a small number of emails per day and increases gradually.
• Daily limits. Free Gmail allows roughly 500 emails/day total; the app's default limits are well under that. Don't raise them aggressively.
• Keep it personal. These are 1-to-1 emails — write the way you normally would. Avoid lots of links/images and "salesy" wording.
• Send window. Set each campaign to send during normal daytime hours and weekdays (in Settings → timezone), so it looks natural.
• Respect replies and opt-outs. Replies auto-stop a sequence. You can mark any contact "do not email", and enable an unsubscribe line per campaign.
• Set your From name. In Settings → From name, use a friendly name (e.g. Pavel — Yoga) so recipients see who it's from. Leave it blank to use your Gmail account's default name.

---

11. Troubleshooting

"python is not recognized" / "command not found" Python isn't installed or (Windows) the "Add to PATH" box wasn't ticked. Reinstall Python (Section 2) and tick that box. On Mac, use python3.

Windows: "running scripts is disabled on this system" Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once (answer Y), then retry.

The browser didn't open Manually visit http://127.0.0.1:5000 while the terminal shows the app running.

Connecting Gmail fails with "access denied" / "not a test user" Add your Gmail address under Audience → Test users (Section 5D).

"redirect_uri_mismatch" The redirect address in Google must be exactly http://127.0.0.1:5000/settings/gmail/callback, and you must open the app at 127.0.0.1 (not localhost). Fix it in Google (Credentials → your client) and try again.

Google says the app is "unverified" Expected for a personal project. Click Advanced → Go to Kind Reach (unsafe). It's your own app using your own account.

"Add client_secret.json" message in Settings The credentials file isn't in the right place or is misnamed. It must be exactly data/credentials/client_secret.json inside the app folder (Section 5F).

I changed something / it's behaving oddly Stop the app (Ctrl + C) and start it again (Section 6). The app does not auto-restart while running.

Emails aren't going out Check: Gmail connected (Settings)? Dry-run OFF (Settings)? Campaign Launched and not paused/stopped? Current time within the campaign's send window/days? Daily limit not already reached? Click Run engine now on the Dashboard to process immediately.

Nothing happens unless I click "Run engine now" While the app is open it also sends automatically every couple of minutes. "Run engine now" just makes it act immediately without waiting.

Could the same person get the same email twice? No. The app runs only one send pass at a time and records every send, so a given campaign step can't be delivered to the same address twice — even if you click "Run engine now" while it's already working, or restart mid-run.

What name and timezone do recipients / timestamps use? Recipients see the From name set in Settings (or your Gmail default if blank). All times shown in the app (History, Dashboard) are in the timezone you set in Settings; change it there and displays update.

Something's still not working. Re-read this section. Make sure you started the app from the KindReach folder with the environment activated (Section 6), and that Python is 3.11 or newer.

---

12. Where your data lives

Everything is stored only on your computer, inside the app's data folder:

KindReach/
  data/
    kindreach.db              ← all contacts, templates, campaigns, history
    attachments/              ← files/images you attached
    credentials/              ← your Google client secret + OAuth token

To back up: use the in-app Settings → Backup & restore (Section 8), or just copy the whole data folder somewhere safe.

To move to a new computer: install the app there (Sections 2–4), then use the in-app Restore from backup (or copy your data folder over).

To start completely fresh: close the app and delete data/kindreach.db (this erases all contacts/campaigns — be careful).

Keep the data/credentials/ folder private — it can send email as you.

Upgrading from a pre-rename install? If your folder still has data/simple_prospect.db, the app will automatically rename it to data/kindreach.db on first launch. Older backup zips made before the rename are still accepted by Restore.

---

13. Frequently asked questions

Is my contact list uploaded anywhere? No. It stays in the data folder on your computer. Emails are sent directly through your own Gmail.

Will it email people while my computer is off or the app is closed? No. It only sends while the app is open. It safely resumes when you reopen it.

What happens if someone replies? That person is automatically removed from the rest of that sequence — they won't get the remaining follow-ups.

Can follow-ups look like a reply in the same email thread? Yes — if a later step has the same subject as the first email, it's sent as a reply in that thread. If the subject is different, it's sent as a fresh email (no odd "Re:").

Can I send to several hundred people? Yes, over time. Use ramp-up and daily limits; spread a large list across several days. Keep the app open during sending hours.

Do I need to share my Gmail password with the app? No. You sign in through Google's official screen; the app never sees your password.

---

14. Privacy & security

• Kind Reach runs entirely on your machine. There is no remote server, no telemetry, and no analytics. The only outbound traffic is to Google (Gmail API + OAuth).
• Your data folder contains secrets — your Gmail OAuth token and your Google client secret. Anyone with that folder (or with a backup zip) can send email as you. Keep them private.
• Do not commit your data/ folder to any public repository. The included .gitignore excludes it by default.
• If you ever suspect your credentials have leaked, revoke them at https://myaccount.google.com/permissions and reconnect Gmail in Settings.

---

15. Contributing

Kind Reach is a small, opinionated, single-user tool. Bug reports and small, focused pull requests are welcome — see CONTRIBUTING.md for dev setup, how to run the test suite, and code-style notes. Security issues go through SECURITY.md, not public issues. All participation in this project is subject to the Code of Conduct.

---

16. License

Released under the MIT License. See the LICENSE file for details.