tuimail/MAIL_SERVER_SETUP.md

Mail Server Setup

Gmail Configuration

1. Enable 2-Step Verification

App Passwords require 2-Step Verification to be enabled on your Google account.

1. Go to https://myaccount.google.com/security
2. Under "How you sign in to Google", click 2-Step Verification
3. Follow the prompts to enable it

2. Create an App Password

1. Go to https://myaccount.google.com/apppasswords
2. Enter a name (e.g. "Mail TUI") and click Create
3. Google will display a 16-character password — copy it

3. Update config.toml

[imap]
host = "imap.gmail.com"
port = 993
username = "you@gmail.com"
password = "xxxx xxxx xxxx xxxx"
use_tls = true

Replace the password with the app password from step 2 (spaces are optional).

Important: Do not commit config.toml — it is listed in .gitignore.

Local Test Server (Docker)

Quick Start

1. Start the mail server:

   docker-compose up -d
   

2. Create a test user:

   docker exec -it mailserver setup email add test@example.com password123
   

3. Verify the server is running:

   docker-compose ps
   

IMAP Connection Details

• Host: localhost
• IMAP Port: 143 (unencrypted) or 993 (SSL/TLS)
• Username: test@example.com
• Password: password123

Useful Commands

# Stop the mail server
docker-compose down

# View logs
docker-compose logs -f mailserver

# List all email accounts
docker exec -it mailserver setup email list

# Add another user
docker exec -it mailserver setup email add user2@example.com pass456

# Delete a user
docker exec -it mailserver setup email del test@example.com

# Access the container shell
docker exec -it mailserver bash

Testing with telnet

You can test IMAP connectivity:

telnet localhost 143

Then try IMAP commands:

a1 LOGIN test@example.com password123
a2 LIST "" "*"
a3 SELECT INBOX
a4 LOGOUT

Send Test Email

# From within the container
docker exec -it mailserver bash
echo "Test email body" | mail -s "Test Subject" test@example.com

Or use SMTP (port 25/587) from your application.

Troubleshooting

• Gmail: if login fails, verify that 2-Step Verification is enabled and you're using an App Password (not your regular password)
• Docker: check logs with docker-compose logs mailserver
• Ensure ports aren't already in use
• Data persists in ./docker-data/ directory