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

[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):

# 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

PROTOCOL = smtps
SMTP_PORT = 465

Result: Authentication failed (535)

Iteration 2: Port 587 with smtp+starttls

PROTOCOL = smtp+starttls
SMTP_PORT = 587

Result: Authentication failed (535)

Iteration 3: Explicit AUTH PLAIN

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

• Tested both port 587 (STARTTLS) and 465 (SSL/TLS)
• Tried AUTH PLAIN and AUTH LOGIN methods
• Removed conflicting TLS settings (ENABLE_TLS, SKIP_VERIFY)
• Updated password in vault and redeployed
• 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