PhoneMail

Email where your phone number is your address. Sign up with your mobile number and you have [email protected]: no username to invent, nothing to remember. You can sign up on the web, by texting JOIN, or by calling a number and pressing 1. Mail arrives as chats, like WhatsApp on your phone and like Gmail on a big screen, and it works with every other email provider.

The AlphaStack 7-day Buildathon submission of Team Node Nexus. Live at https://mail.phonemail.net. The code as delivered for the buildathon is tagged v1.0.0 (the original release); main is the current code, including the iPhone, Apple Watch, Android and Wear OS apps.

Website: phonemail.net · Open the app: mail.phonemail.net · User guide: phonemail.net/docs

Demo video

An 8-minute walkthrough of PhoneMail: https://youtu.be/CQClL0JOdA0

• Demo video
• Set it up and run it (start here)
• Tech stack
• Architecture
• Approach and design decisions
• Features
• Tests
• Documentation

---

Set it up and run it

Everything runs in Docker, so the only thing to install is Docker (Docker Desktop on Windows and macOS; Docker Engine with the Compose plugin on Linux). Nothing else: no Node, Go or PostgreSQL on the machine itself. It works on Windows, macOS and Linux, on Intel/AMD and ARM (it runs in production on a small ARM home server).

1. Get the code

git clone <this repository's URL> phonemail
cd phonemail

2. Settings: the .env file

All settings live in one file, .env, in the top folder. The repository has an empty .env as a placeholder.

• If you were given a .env file (for example, with the submission): put it in the top folder in place of the empty one. That's all.

• Otherwise, make one from the example and fill in the two required secrets:

  cp .env.example .env            # Windows PowerShell: copy .env.example .env
  

  Then open .env and set INTERNAL_TOKEN and POSTGRES_PASSWORD to two different long random values. On macOS or Linux, openssl rand -hex 32 makes one. On Windows PowerShell, use -join ((1..32) | % { '{0:x2}' -f (Get-Random -Max 256) }). PhoneMail refuses to start with an empty or short secret, on purpose.

The other settings all have working defaults (see comments in .env.example). Without Twilio keys, sign-in is phone number + password, the brief's own fallback, so no outside accounts are needed.

3. Start it

docker compose up -d --build

The first build takes a few minutes (it compiles the Go mail service and the React app). When docker compose ps shows every service as healthy, it's ready:

Open	What it is
http://localhost:8080	The web app (use a phone-sized window to see the phone layout)
http://localhost:8080/register/	The sign-up portal: phone number and code, clears itself after each account
http://localhost:8080/api/health	Health check: {"ok":true,...}

All ports are bound to this computer only (127.0.0.1).

4. Try it

1. Open http://localhost:8080, choose English, type any 10-digit number (e.g. 9876500001) and a password of 8+ characters, then press Next. A new number signs up; a known one signs in.
2. In a second browser (or a private window), sign up a second number, e.g. 9876500002.
3. From the first, Compose an email to 9876500002 and send it. It appears for the second person at once (no reload), with an unread badge.
4. Reply, and try replying to the same email twice: "You've already replied to this email." (each email can be answered once per person, as the brief asks).
5. Put two numbers in To: PhoneMail asks for a group name and starts a group chat.

Mail from outside ("SMTP local"). The postfix container is a real SMTP server on port 25. Mail sent to it for a PhoneMail number is checked, delivered and shown live:

# any SMTP client works; with swaks (https://jetmore.org/john/code/swaks/):
swaks --server 127.0.0.1:25 --from [email protected] --to [email protected] \
      --header "Subject: Hello from outside" --body "It works!"

Mail from PhoneMail to outside addresses goes out through the same Postfix. Home internet connections usually block outgoing port 25; set POSTFIX_RELAYHOST (and its login) in .env to send through any mail provider instead.

Sign-up by SMS and phone call need a Twilio number: put TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_VERIFY_SID and TWILIO_FROM_NUMBER in .env and PUBLIC_BASE_URL to the public https address Twilio can reach. Sign-in then uses one-time SMS codes; texting JOIN or calling and pressing 1 creates an account.

Stop, reset, troubleshoot

docker compose down        # stop (keeps all data)
docker compose down -v     # stop and delete all data
docker compose logs -f api mailsvc postfix   # watch what's happening

• "Set INTERNAL_TOKEN in .env" or "POSTGRES_PASSWORD": step 2 isn't done yet.
• A port is already in use (e.g. something else on port 25 or 8080): change POSTFIX_PORT, WEB_PORT, API_PORT, DB_PORT, MAILSVC_PORT or SMTP_PORT in .env and start again.
• Running without the Postfix container (a server with its own mail server): remove COMPOSE_PROFILES=postfix and SMTP_RELAY from .env.

Phone and watch apps

Native apps that talk to the same api (/api, with a bearer token instead of the browser cookie):

This is the beginning of the README. Read the rest at the original. Read the full README ↗