Popsicle

Write one email template, paste in a list of people, and send each person a personalized copy from your Gmail. Sent emails, contacts and companies are stored in Postgres, so the app knows who you've already emailed.

Part	Stack	Location
UI	Next.js 16 (App Router, Tailwind 4)	frontend/
API	FastAPI + SQLAlchemy 2	backend/
Database	Postgres 14, port 5442	~/Desktop/personal-projects/psqlConnections/cold-emailer-5442

Running it

./dev.sh

This starts Postgres if it isn't running, then the API on :8000 and the UI on http://localhost:3000 (landing page; the app itself is at /compose).

To start Postgres yourself instead, follow the same steps as your other clusters:

cd ~/Desktop/personal-projects/psqlConnections/cold-emailer-5442
pg_ctl -D ./pgdata -o "-p 5442" -l logfile start
psql -p 5442 -d cold_emailer

First-time setup

cd backend && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
cd ../frontend && npm install

Tables are created automatically when the API starts.

Connecting Gmail (once)

1. Go to https://console.cloud.google.com/ and create a project.
2. Go to APIs & Services → Library, then enable the Gmail API and the Google Calendar API (the Inbox tab uses Calendar to make Google Meet links).
3. Go to OAuth consent screen, choose External, and add your Gmail address under Test users.
4. Go to Credentials → Create credentials → OAuth client ID:
   • Type: Web application
   • Authorized redirect URI: http://localhost:8000/api/gmail/callback
5. Download the JSON and save it as backend/credentials.json.
6. In the app, click Connect Gmail in the compose card.

When connecting, tick every box on Google's screen:

• Send email on your behalf: needed to send batches.
• Read your email: lets the Inbox tab show replies. Popsicle only reads mail to and from people you've emailed.
• See and edit events on your calendars: lets the Inbox tab create Google Meet links.

Connected before the Inbox existed? The Inbox tab shows a Reconnect Gmail button. Click it once to grant the two new permissions.

While the Google app is in "Testing" mode, Google expires the login after 7 days. When that happens, click Connect Gmail again.

"Couldn't reach Google" (or a batch saying "Can't reach Gmail right now") means your internet dropped, not that the login expired, so there's no need to reconnect. A batch waits and carries on by itself once the connection is back, and never sends an email twice. For the Inbox or a Meet link, just try again.

Connecting Hunter.io (once, for Find people)

1. Copy your API key from https://hunter.io/api-keys.
2. Add it to backend/.env (create the file if it doesn't exist; git ignores it):

   HUNTER_API_KEY=your-key
   

3. Restart ./dev.sh.

The free plan has 50 credits a month. Per Hunter's credit rules:

• Company search: 1 credit per 10 people found, so up to 10 people costs 1 credit and up to 25 costs up to 3.
• Nothing found: free.
• Repeating a search in the same month: free.
• Looking up one person: 1 credit, only if their email is found.

Your remaining credits show in the top nav and update after every search.

Accounts and login

Popsicle is invite-only: only the emails in ALLOWED_EMAILS can ever get in (for now, just yours). Accounts are created from the terminal, never from the website. From the backend/ folder:

.venv/bin/python -m app.manage new-password                  # a 64-character random password, saved to backend/.owner-password
.venv/bin/python -m app.manage create-user [email protected] --password-file .owner-password
.venv/bin/python -m app.manage create-user [email protected]   # or type a password yourself (twice, not shown)
.venv/bin/python -m app.manage list-users                    # also flags accounts not in ALLOWED_EMAILS
.venv/bin/python -m app.manage set-password [email protected] [--password-file .owner-password]
.venv/bin/python -m app.manage delete-user [email protected]

• Your password: new-password makes a long random one and saves it to backend/.owner-password. Git ignores that file, only your user can read it, and it's never printed or overwritten, so the password lives only on your machine (put a copy in your password manager too). Only its scrypt hash is stored in the database. Knowing your email isn't enough: logging in needs this password, and Sign up can't set a new one for an account that already has one.
• ALLOWED_EMAILS (comma-separated, e.g. [email protected]) is the last word, checked on the server:
  • Logging in with any other email fails exactly like a wrong password, even if that account exists in the database with the right password.
  • Taking an email off the list logs it out everywhere on its next request.
  • create-user refuses an email that isn't on the list.
  • Required when deployed (the backend won't start without it). Locally it's optional; unset, any account in the database can log in.
• Sign up is closed. The Sign up tab says so, and its form is disabled and never contacts the server. Underneath, the server's sign-up only accepts an email that is both on ALLOWED_EMAILS and invited from the terminal without a password yet; everyone else is told Popsicle is invite-only.
• Locally, anyone can use the app without logging in (AUTH_REQUIRED=false, the default). The login page still works if you want to try it.
• When deployed, login is always required and the session cookie is https-only; neither can be turned off.
• Security: passwords are stored hashed (scrypt). Sessions last 30 days in a cookie that JavaScript can't read. Five wrong passwords lock that email out for 15 minutes.

Using it

1. Company: type the company name. It becomes {{company}}.
2. Recipients: open the recipients table. Each column is a variable (full_name and email to start; email is required). Add a column with + variable and remove one with its ×.
3. Fill the table: one row per person.
   • Cells wrap their text and grow taller, so a whole paragraph is readable at once.
   • Enter moves to the same column in the next row, adding a row if needed. Shift+Enter starts a new line inside a cell.
   • You can paste rows copied from a spreadsheet into a cell; they fill the table from that cell. Pasted text with line breaks but no tabs, such as a paragraph, stays in that one cell.
   • Blank rows are ignored, and rows with a missing or invalid email are flagged.
4. Template: write the subject and body. Click a variable in the dark toolbar to insert {{variable}} at the cursor. Valid placeholders show in red; ones that don't match a variable get a wavy underline.
   • If you have a full_name variable, {{first_name}} and {{last_name}} are filled in automatically.
5. Send: you get a per-person preview first. Then emails go out one at a time, about 30 seconds apart (adjust with the clock icon). You can stop a batch partway through.
6. Or schedule it: Schedule on the review screen sends the batch later instead. Pick Tomorrow 9:00 AM, next Tuesday or Thursday at 9:00 AM, or any time up to 60 days ahead, in your own timezone. Morning emails get read and answered more.
   • A scheduled batch shows scheduled on the Sent page with the time it sends. Open it to Send now or Cancel.
   • It sends by itself even if the page is closed, and after a backend restart, as long as the backend is running at that time. The daily limit still applies.

Your draft is saved in the browser, so a refresh doesn't lose it.

Saving templates

The bar at the top of the email editor shows which template you're working on. A red dot marks unsaved changes ("Edited" for a saved template, "Not saved" for a new draft).

• Save draft: names an untitled draft (e.g. "Learning more about the industry") and saves it to the database.
• Save: updates the saved template you're editing. Save as new keeps the original and saves your version under a new name.
• Switch: the dropdown lists your saved templates. Pick one to load it, or choose New blank draft to start fresh. Each template can be deleted from the dropdown.
• Unsaved changes: if switching would lose your edits, Popsicle asks whether to save them first, discard them, or keep editing.

A template stores the subject and body. Loading one adds any variables it uses as columns in the recipients table, without removing yours.

Finding people

Open the Find people tab:

1. Companies: start typing a name and pick the company from the suggestions (logo, domain, and how many people Hunter has, biggest first). Picking one searches that exact domain, so "Harvey" means harvey.ai and not harvey.net. You can also type a name or domain and press Enter, or paste several at once.
2. Role and job titles: pick a Role to fill in its usual titles, or type your own (comma-separated, any seniority; leave empty for everyone). The default, Software & data, covers about 40 titles: software engineer and developer variants, frontend/backend/full stack, mobile, platform and infrastructure, DevOps and SRE, QA, security, plus data scientist, data engineer, data analyst, machine learning and AI engineer, research scientist and more. There are also presets for Recruiting, Engineering leaders, Product and Design, and any title works, e.g. barista. Hunter matches whole words, so engineer also finds "Engineering"; bare words like developer are left out of the presets because they'd also match business-development roles. Listing more titles doesn't cost more credits.
3. Location: defaults to Greater Toronto Area: people based in Toronto or the surrounding Peel, York, Halton and Durham cities. You can also choose anywhere in Canada, or anywhere. This filters on where each person lives and works, not the company's HQ.
4. People per company: choose how many to fetch, then click Search.
5. Pick people: results appear per company. Each person shows their title, Hunter's confidence in the email, and whether you've already emailed them; people already emailed start unticked.
6. Email them: click Email N people on a company. Compose opens with those people as recipients, the company filled in, and a role column from their job titles.

There's also a quicker Find people button inside Compose that searches one company and adds people to the current batch. Its Look them up section finds a single person's email from their name or LinkedIn URL.

Get new people. Already emailed the first 10 people at a company and want more? Click Get 10 new people on that company. Popsicle goes through Hunter's results from the top and skips everyone you've already emailed, until it has 10 people you haven't. Pages it has already fetched are saved, so going back over them is free; usually only the one page with new people uses a credit. Tick Hide people I've already seen to also skip anyone Find people has shown you before (whether or not you emailed them). When Hunter has nobody new left for that search, Popsicle says so and suggests a wider location or no job title.

Results are saved for 30 days, so repeating a search costs nothing. Use refresh on saved results to search Hunter again.

If a company search finds no one, Popsicle checks (for free) how many people Hunter has there in total and tells you whether the filters are the reason. It then offers one-click Search anywhere or Remove the job title retries.

Your target companies

The Companies tab is your list of companies to reach, with each one's logo (from Hunter, free).

• Add companies: type a name and pick it from the suggestions, or paste a whole list (one per line or comma-separated). Names and domains both work. Hunter's free company suggestions fill in the domain for an exact name match, or the name for a domain. Companies already on the list are skipped.
• Missing logos: a company with no domain shows a placeholder. Find N missing logos asks Hunter (free) for the domains of up to 30 at a time. Names Hunter doesn't recognise exactly are left for you to fill in, so a wrong company is never guessed.
• Status: each company is Not started, Emailed, Replied or Not a fit. It moves to Emailed by itself when the first email to it is sent; change it from the card any time. The filters at the top show how many are in each.
• Find people at several companies: tick companies (e.g. under Not started) and click Find people at N companies. Find people opens with them filled in, keeping your job title and location.
• Contacts: click a company's name to see everyone you have there.
• Search: the search box finds companies by name or domain.

Inbox: replies and Google Meet

The Inbox tab lists everyone you've emailed. Open someone to see the whole conversation with them, your emails and their replies, in order.

• Replies: Popsicle checks Gmail for new replies when you open the tab, and when you click the refresh icon. It reads only mail to or from people you've emailed, and only downloads conversations that changed since the last check. Quoted earlier messages are hidden so each reply is easy to read. Drafts you haven't sent yet aren't shown. Gmail only allows so many requests a minute, so a big check (for example the first one, with hundreds of people) is spaced out and can take several minutes; the Inbox shows how far it's got ("120 of 721 people") and replies appear as they're found. If Gmail still asks it to slow down, it waits and carries on; what's already checked is kept.
• Filters: Replied or No reply yet, plus search by name, email or company. A red dot marks people who replied.
• Company status: when someone replies, their company moves to Replied on the Companies tab, unless you set its status yourself.
• Send Meet link: pick a date, time and length (in your timezone), and edit the email if you like. {{meet_link}} becomes the link. Popsicle creates a Google Calendar event with a Google Meet link, then emails it as a reply in your conversation. By default they also get a Google Calendar invite; untick that to send only the email. Meetings show at the top of the conversation with the link, a copy button and a link to the calendar event.
• Replying in your own words: use Reply in Gmail at the bottom of a conversation.

Booking links: let them pick the time

Instead of choosing a time yourself, send someone a link to a page where they pick a 30-minute slot that suits them. The call is then set up exactly like Send Meet link.

1. Booking hours (top right of the Inbox): tick Take bookings, add your name (shown on the page), and choose your days, hours, time zone, how much notice you need, and how far ahead people can book.
2. Send the link, either way:
   • In a batch: put {{booking_link}} in your email. Each person gets their own link, made when you click Send. The preview shows where it goes.
   • In a conversation: click Booking link, edit the email if you like, and send it as a reply.
3. They open it: no account or login. They see your open times in their own time zone. Anything on your Google Calendar is left out, using the calendar permission Popsicle already has.
4. They pick a time: Popsicle checks it's still free, creates the Google Meet call, sends them the calendar invite, and replies in your conversation with the Meet link. The call shows in your Inbox like any other.

Each link works once and expires after 60 days. Anyone opening an old or made-up link just sees "This booking link doesn't work anymore", and the page is rate-limited. Booking-link emails sent from the Inbox count toward the daily limit, like Meet emails.

Looking up one person

The Look up tab finds a single person's email. Either paste their LinkedIn profile URL on its own (Hunter works out who they are and where they work), or enter their full name plus their company or website domain.

• Works beyond Hunter's lists: it works out the company's email pattern, so it finds people at companies Hunter has no people for. A website domain like tiny-startup.io is the most reliable input.
• Results: the email, Hunter's confidence, whether it's verified, and their title if known.
• What you can do with a result: Copy it, Email them (Compose opens with just them), or Add to batch (they join the recipients you're already writing to).
• Cost: 1 credit if an email is found. It's free if not, or if you've looked them up before.

Recent lookups stay on the page so you can come back to them.

Light and dark

The sun/moon button at the top right of the app switches between the light and dark palettes. Your choice is remembered in this browser and applied before the page is drawn, so there's no flash. The landing page is always dark: its light trails read best on a dark background. To change that, edit FIXED_THEME in frontend/src/lib/themeScript.ts.

Colours are defined once in frontend/src/app/globals.css, each with one job (paper for surfaces, cloud for the background, ink for text, steel for secondary text, night for dark accents, plus the brand reds); the dark palette swaps their values.

Long lists

Companies, Contacts, the Inbox and Sent load 30 at a time. The next 30 load by themselves as you scroll to the end of a list, or with Load more. Searches, filters and the counts on each tab cover everything, not only what's loaded.

Deploying

Popsicle is built to run as one site: the frontend (Vercel) forwards /api/* to the backend (Railway), so the browser only ever talks to the frontend's address and login cookies work in every browser.

Popsicle counts as local only when its addresses and its database are all on your machine; anything else gets the deployed rules: login always on, the session cookie https-only, the API docs hidden. The backend refuses to start if AUTH_REQUIRED=false, if ALLOWED_EMAILS, TOKEN_ENCRYPTION_KEY or PROXY_SECRET is missing, or if BACKEND_URL or FRONTEND_URL is still a localhost address.

1. Make two secrets

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"   # TOKEN_ENCRYPTION_KEY
python -c "import secrets; print(secrets.token_urlsafe(32))"                                 # PROXY_SECRET

Keep both somewhere safe. Losing TOKEN_ENCRYPTION_KEY means reconnecting Gmail.

2. Backend and database on Railway

1. Create a project (the Hobby plan: the backend has to stay on) and add Postgres to it.
2. Add a service from this GitHub repo. In its Settings:
   • Root Directory: backend
   • Railway Config File: /backend/railway.json (the config file doesn't follow the root directory). It sets the start command, the /api/health check, and exactly one always-on server: sending runs in background threads of that one process, so don't add replicas.
   • Networking → Generate Domain. This is the backend's own address, e.g. https://popsicle-production.up.railway.app.
3. Set its Variables:

Setting	Value
DATABASE_URL	${{Postgres.DATABASE_URL}} (Railway's postgresql:// address works as-is)
FRONTEND_URL, BACKEND_URL	Both the Vercel address, e.g. https://popsicle.vercel.app. Google returns to BACKEND_URL/api/gmail/callback, which the frontend forwards to the backend
ALLOWED_EMAILS	Your email: the only one that can log in (comma-separate more later)
TOKEN_ENCRYPTION_KEY, PROXY_SECRET	From step 1
HUNTER_API_KEY	Your Hunter key
GOOGLE_CLIENT_SECRETS_JSON	The whole contents of backend/credentials.json (Railway has no secret files). Locally the file is used instead

3. Frontend on Vercel

1. Import this repo with Root Directory frontend.
2. Before the first build, set BACKEND_ORIGIN (the Railway address from step 2) and PROXY_SECRET (the same value as the backend's). With BACKEND_ORIGIN set, the site calls its own /api; there's no need to set NEXT_PUBLIC_API_URL.
3. Deploy. Changing a setting later needs a redeploy.

4. Google

In the Google Cloud OAuth client, add https://<your-vercel-address>/api/gmail/callback to Authorized redirect URIs (keep the localhost one). Leaving the app in Testing mode is fine; the login still expires every 7 days.

5. Your data and account

1. Copy your local data across (optional):

   pg_dump -p 5442 -Fc cold_emailer > popsicle.dump
   pg_restore --no-owner --no-acl -d "<Railway Postgres public URL>" popsicle.dump
   

   Afterwards, cancel any batches still scheduled in your local database, or ./dev.sh would send them too.
2. Create your account. On your machine, make the password once with python -m app.manage new-password (in backend/) and copy it with pbcopy < .owner-password. Then in the backend service's shell on Railway (railway ssh), run python -m app.manage create-user [email protected] and paste it at both (hidden) prompts.
3. Open the Vercel address, log in and click Connect Gmail (the local connection doesn't carry over: it's encrypted with a different key).

6. Check it

• https://<railway-address>/api/health answers; any other path on the Railway address says "Use Popsicle through its website". That's the proxy secret working.
• Attachments go through Vercel on their way to the backend: try a large one with a test send to yourself before relying on it.

Good to know

Logging in. Wrong passwords are limited per visitor (5 per 15 minutes) and per account (20). A browser you've logged in from before isn't held to the per-account limit, so someone guessing your password can't lock you out of your own browser.

Long jobs. Checking Gmail for replies runs in the background (the Inbox shows it until it's done), and verifying addresses, pasting companies and finding missing logos are sent a few at a time, so no request runs long enough to be cut off by the hosting proxy.

Sending safely across restarts. Each batch is claimed in the database by the server process sending it, and the claim is renewed while it works. During a redeploy, when the old and new servers overlap, a batch is only ever sent by one of them. An email that was being handed to Gmail when a server stopped is marked failed ("may have gone out, check Gmail's Sent folder") rather than resent. Waiting and scheduled batches whose server stopped are picked up again within a minute. The daily limit holds even when several batches send at once (it's checked and taken in one locked step), and Google Meet link emails count toward it. A Gmail connection in progress is kept in the database, so it finishes even if a redeploy happens in the middle.

Security

Popsicle shows data it doesn't control: replies from strangers, Hunter's people data, pasted tables, Google's links. It's handled as follows:

• Shown as text, never as code. Every name, subject and reply is displayed as plain text (React escapes it). Replies' HTML is turned into text on the backend and never rendered. The one raw script on the page is a fixed snippet that applies your saved theme before the page is drawn; no data ever goes into it.
• Links are web addresses only. Links from data (LinkedIn, Meet, Calendar) are only made clickable if they're http(s); a javascript: or data: link is refused when saved and dropped when shown.
• One recipient per email. Addresses must be ordinary email addresses (no commas, quotes or brackets), so a value can't add hidden recipients. Subjects and meeting titles can't contain line breaks, so values can't add email headers.
• Gmail searches can't be changed by data. Only well-formed addresses go into the Inbox's Gmail search, each in quotes.
• Other websites can't act for you. The login cookie isn't sent to other sites, and changes coming from another website (by the browser's Origin) are refused.
• Pages can't be framed by other sites, and links out don't reveal which page you were on.
• Hostile emails can't stall the app. Reply bodies are capped in size and their HTML is turned into text by a single-pass parser, so a crafted email can't make processing take minutes (a "ReDoS").
• No SQL, command or template injection. Database queries always use parameters; Popsicle never runs shell commands, never evals or unpickles data, and fills {{placeholders}} in one pass (a value containing {{email}} isn't filled in again). The only outside service the backend calls is Hunter, at a fixed address, so it can't be made to fetch arbitrary URLs.
• Prompt injection: Popsicle has no AI features, so nothing it reads (replies, profiles, Hunter data) is ever given to a model as instructions. If an AI feature is added later, treat those as untrusted data.

Testing

None of the tests reach Hunter or Gmail: Hunter calls and sends are faked, so no credits are spent and no email goes out. Each suite fails if coverage drops below 90%. GitHub Actions runs all of them on every push (.github/workflows/test.yml).

Backend (pytest). The tests use a cold_emailer_test database on the 5442 cluster, which they create at the start and drop at the end, so your real data is never touched. Postgres must be running.

cd backend
.venv/bin/pip install -r requirements-dev.txt   # once
.venv/bin/pytest

To use another server, set TEST_DATABASE_URL. Its database name must end in _test.

Frontend (Vitest and React Testing Library). The backend is faked at the network level.

cd frontend
npm test                # watch mode
npm run test:coverage   # one run, with the coverage report

End-to-end (Playwright). Real browser runs of logging in, Find people, Look up and sending. The app is built into frontend/.next-e2e and talks to a fake API inside the browser, so it can run while ./dev.sh is up.

cd frontend
npx playwright install chromium   # once
npm run test:e2e

Protecting your Gmail account

Gmail flags accounts that suddenly send a lot, or whose emails bounce, and starts putting their mail in spam. Popsicle guards against both.

Daily send limit

• The limit: at most 40 emails per rolling 24 hours by default, and always at least 20 seconds between emails. Each batch's own randomised spacing comes on top of that.
• When a batch reaches the limit, it shows waiting for daily limit and carries on by itself once there's room again, even after a restart. You can still stop it.
• Before you send, the review screen tells you how many emails go out now and when the rest will follow.
• To check or change the limit, use the Sending safety card on the Sent page. 30–50 a day is a safe range for cold email.

Checking addresses exist

• Verify N on the review screen checks unchecked recipients with Hunter's Email Verifier. It uses your monthly Hunter verifications, and the screen shows how many you have left.
• Each recipient gets a badge:
  • verified
  • risky: the company accepts any address, or Hunter couldn't tell. Risky addresses are still sent.
  • doesn't exist: skipped automatically, so they never bounce.
• Results are kept for 30 days, so checking the same address again is free.

Data model

companies 1─* contacts 1─* emails *─1 campaigns *─* attachments
                                       campaigns *─1 templates
gmail_accounts (the connected sender)
hunter_lookups (cached Hunter.io responses)
users, auth_sessions (invite-only accounts and their login sessions)
sending_settings (daily limit and minimum gap), email_verifications (Hunter verdicts, kept 30 days)
conversation_messages, mail_threads (Gmail conversations with people emailed), meetings (Google Meet calls set up)

• campaigns: one batch, e.g. "Stripe, 10 people". It keeps a copy of the exact subject and body used, so editing a template later doesn't change history.
• emails: one row per person per batch. It stores the rendered text, the variable values used, the status (pending/sent/failed/skipped/cancelled) and the Gmail message ID.
• companies: unique by name, with a status (not_started/emailed/replied/not_interested) for the target list.
• contacts: unique by email address. They're created or updated from the recipients table (full_name, role/title and linkedin are picked up automatically).
• Already emailed: someone counts as already emailed if any email to their address has status sent. They're skipped by default; you can change this with the person-check icon.

The schema is created with create_all. Columns added later (like campaigns.scheduled_for and companies.status) are added at startup by app/migrations.py, which never touches existing data. Switch to Alembic if migrations get more involved.

API docs are at http://localhost:8000/docs.