rick-infra/docs/gitea-email-troubleshooting.md

# Gitea Email Configuration Troubleshooting

## Summary

Attempted to configure Gitea email functionality using Titan Email (Hostinger) SMTP service. Email sending is currently **non-functional** due to SMTP authentication rejection by Titan Email servers.

## Configuration Details

### Email Provider
- **Provider:** Titan Email (by Hostinger)
- **Account:** hello@jnss.me
- **SMTP Server:** smtp.titan.email
- **Ports Tested:** 587 (STARTTLS), 465 (SSL/TLS)

### Gitea Configuration
```ini
[mailer]
ENABLED = true
PROTOCOL = smtp+starttls
SMTP_ADDR = smtp.titan.email
SMTP_PORT = 587
FROM = hello@jnss.me
USER = hello@jnss.me
PASSWD = <vault_gitea_smtp_password>
SUBJECT_PREFIX = [Gitea]
SEND_AS_PLAIN_TEXT = false
SMTP_AUTH = PLAIN
```

## Issue Description

Gitea fails to send emails with the following error:
```
Failed to send emails: failed to authenticate SMTP: 535 5.7.8 Error: authentication failed
```

## Troubleshooting Performed

### 1. Credential Verification
- ✅ **Webmail access:** Successfully logged into https://mail.titan.email/ with credentials
- ✅ **Send/Receive:** Can send and receive emails through webmail interface
- ✅ **Password confirmed:** Tested multiple times, credentials are correct

### 2. SMTP Connectivity Tests
- ✅ **Port 587 (STARTTLS):** Connection successful, TLS upgrade successful
- ✅ **Port 465 (SSL/TLS):** Connection successful with implicit TLS
- ✅ **DNS Resolution:** smtp.titan.email resolves correctly to multiple IPs

### 3. Authentication Method Testing

**Manual SMTP tests from VPS (69.62.119.31):**

```python
# Test Results:
AUTH PLAIN:  ❌ 535 5.7.8 Error: authentication failed
AUTH LOGIN:  ❌ 535 5.7.8 Error: authentication failed
```

**Both authentication methods rejected by server despite correct credentials.**

### 4. Configuration Iterations Tested

#### Iteration 1: Port 465 with smtps
```ini
PROTOCOL = smtps
SMTP_PORT = 465
```
**Result:** Authentication failed (535)

#### Iteration 2: Port 587 with smtp+starttls
```ini
PROTOCOL = smtp+starttls
SMTP_PORT = 587
```
**Result:** Authentication failed (535)

#### Iteration 3: Explicit AUTH PLAIN
```ini
PROTOCOL = smtp+starttls
SMTP_PORT = 587
SMTP_AUTH = PLAIN
```
**Result:** Authentication failed (535)

#### Iteration 4: Removed conflicting TLS settings
Removed:
- `ENABLE_TLS = true` (conflicted with PROTOCOL)
- `SKIP_VERIFY = false` (deprecated)

**Result:** Authentication still failed (535)

### 5. Debug Output Analysis

SMTP conversation debug output revealed:
```
send: 'AUTH PLAIN AGhlbGxvQGpuc3MubWUASGVsbG8xMjMh\r\n'
reply: b'535 5.7.8 Error: authentication failed: \r\n'

send: 'AUTH LOGIN aGVsbG8Aam5zcy5tZQ==\r\n'
reply: b'334 UGFzc3dvcmQ6\r\n'
send: 'SGVsbG8xMjMh\r\n'
reply: b'535 5.7.8 Error: authentication failed: UGFzc3dvcmQ6\r\n'
```

**Analysis:** Server accepts both AUTH PLAIN and AUTH LOGIN in EHLO response but rejects actual authentication attempts for both methods.

## Root Cause Analysis

### What Works
- ✅ SMTP server connectivity (both ports)
- ✅ TLS/STARTTLS negotiation
- ✅ Webmail authentication with same credentials
- ✅ Email sending through webmail

### What Doesn't Work
- ❌ SMTP AUTH PLAIN from VPS
- ❌ SMTP AUTH LOGIN from VPS
- ❌ Both fail with identical error: 535 5.7.8

### Conclusion

**The issue is NOT a Gitea configuration problem.** The SMTP server is actively rejecting authentication attempts despite:
- Correct credentials (verified in webmail)
- Proper TLS establishment
- Correct authentication protocol usage

## Possible Causes

1. **SMTP Access Disabled:** Titan Email may require SMTP/IMAP access to be explicitly enabled in Hostinger control panel or Titan settings
2. **IP-Based Restrictions:** VPS IP (69.62.119.31) may be blocked or require whitelisting
3. **Account Verification Required:** Account may need additional verification for SMTP access
4. **Service-Level Restriction:** Titan Email plan may not include SMTP access for external applications
5. **Missing Activation:** SMTP feature may require separate activation from webmail access

## Attempted Solutions

### Configuration Changes
- [x] Tested both port 587 (STARTTLS) and 465 (SSL/TLS)
- [x] Tried AUTH PLAIN and AUTH LOGIN methods
- [x] Removed conflicting TLS settings (ENABLE_TLS, SKIP_VERIFY)
- [x] Updated password in vault and redeployed
- [x] Verified minimal clean configuration

### External Tests
- [ ] Test SMTP from different IP (local machine vs VPS)
- [ ] Check Hostinger control panel for SMTP toggle
- [ ] Contact Hostinger/Titan support
- [ ] Verify account has SMTP privileges

## Recommendations

### Immediate Next Steps
1. **Check Hostinger Control Panel:**
   - Log into hpanel.hostinger.com
   - Navigate to Emails → hello@jnss.me
   - Look for SMTP/IMAP access toggle or settings

2. **Test from Different IP:**
   - Test SMTP authentication from local machine
   - If successful: IP blocking issue (request VPS IP whitelist)
   - If failed: Account-level restriction

3. **Contact Support:**
   - Provide error: "535 5.7.8 authentication failed"
   - Request SMTP access verification for hello@jnss.me
   - Ask if SMTP requires separate activation

### Alternative Email Solutions

If Titan Email SMTP cannot be resolved:

1. **Use Different Email Provider:**
   - Gmail (with App Passwords)
   - SendGrid (free tier: 100 emails/day)
   - Mailgun (free tier: 5,000 emails/month)
   - AWS SES (free tier: 62,000 emails/month)

2. **Use Local Mail Server:**
   - Install Postfix on VPS
   - Configure as relay
   - More complex but full control

3. **Disable Email Features:**
   - Set `ENABLED = false` in [mailer]
   - OAuth account linking won't work
   - Password reset requires admin intervention
   - No email notifications

## Current Status

**Email functionality: DISABLED**

Configuration is correct but non-functional due to SMTP authentication rejection by Titan Email servers.

## Files Modified

- `roles/gitea/defaults/main.yml` - Email configuration variables
- `roles/gitea/templates/app.ini.j2` - Mailer section configuration
- `host_vars/arch-vps/vault.yml` - SMTP password

## References

- Gitea Mailer Documentation: https://docs.gitea.com/administration/config-cheat-sheet#mailer-mailer
- SMTP Error Codes: https://www.greenend.org.uk/rjk/tech/smtpreplies.html
- Titan Email Settings: https://support.hostinger.com/en/collections/3363865-titan-email

---

**Date:** 2025-12-19  
**Investigated by:** OpenCode AI Assistant  
**Status:** Unresolved - Awaiting Titan Email SMTP access verification