Mail Server Setup

Gmail Configuration

1. Enable 2-Step Verification

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

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

2. Create an App Password

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

3. Configure tuimail

Run the setup wizard:

cargo run -- --configure

When prompted for provider choose imap, then enter:

IMAP host: imap.gmail.com, port: 993, TLS: true
Username: your Gmail address
Password: the 16-character App Password from step 2 (spaces are optional)
SMTP host: smtp.gmail.com, port: 465, TLS mode: smtps

Passwords are stored securely in the OS keychain — they are never written to config.toml.

Local Test Server (Docker)

Quick Start

Start the mail server:
```
docker-compose up -d
```

Create a test user:

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

Verify the server is running:
```
docker-compose ps
```

Configure tuimail for the local server

cargo run -- --configure

Choose provider imap and enter:

IMAP host: localhost, port: 143, TLS: false
Username: test@example.com, password: password123
SMTP host: localhost, port: 25, TLS mode: none

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

2.8 KiB Raw Blame History