Account Troubleshooting

This guide covers common issues when working with email accounts in EmailEngine and how to resolve them.

Quick Diagnostics

Check Account Status

First, check the account's current state using the Get Account API endpoint:

curl https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Look for:

state: Current account state
lastError: Recent error messages
syncTime: Last successful sync
Connection details

Check EmailEngine Logs

EmailEngine logs contain detailed error information:

# If running with systemd
journalctl -u emailengine -f

# If running with Docker
docker logs -f emailengine

# If running manually (logs go to stdout)
# EmailEngine uses pino for JSON logging to stdout

Common Account States and Solutions

State: authenticationError

What it means: Invalid or expired credentials.

For IMAP/SMTP Accounts

Common Causes:

Incorrect password

Password was changed on the email provider
Typo in password
Wrong username

Solution:

curl -X PUT https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imap": { "auth": { "pass": "correct-password" } },
    "smtp": { "auth": { "pass": "correct-password" } }
  }'

# Then reconnect using the Reconnect Account API endpoint
curl -X PUT https://your-ee.com/v1/account/user123/reconnect \
  -H "Authorization: Bearer YOUR_TOKEN"

App password required but not used
- Gmail: Account passwords completely disabled, app-specific passwords required for all accounts
- Yahoo, iCloud: App-specific passwords required if 2FA is enabled
Solution:
- Generate app-specific password from provider
- Update account with app password instead of main password
- Gmail app passwords (requires 2FA enabled)
- Yahoo app passwords
- iCloud app passwords
Password authentication disabled (Gmail)
- Gmail has completely disabled account password authentication for all accounts
- The "Less secure app access" feature is no longer available
Solution:
- Use app-specific passwords (requires 2FA): Gmail app passwords
- Or switch to OAuth2: Gmail OAuth2 guide
IMAP/SMTP disabled (Microsoft 365)
- Admin may have disabled IMAP/SMTP protocols
Solution:
- Enable in Microsoft 365 admin center
- Navigate to Users → Active users → Mail settings
- Enable IMAP and SMTP AUTH
- Or use MS Graph API: Outlook setup guide

For OAuth2 Accounts

Common Causes:

Access token expired and refresh failed

Refresh token may be invalid
OAuth2 app credentials changed
User revoked access

Solution:

Have user re-authenticate via hosted authentication form
Generate new authentication form URL:

curl -X POST https://your-ee.com/v1/authentication/form \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user123",
    "email": "user@gmail.com",
    "redirectUrl": "https://myapp.com/settings"
  }'

OAuth2 app misconfigured
- Client ID or secret incorrect
- Redirect URL mismatch
- Required scopes not configured
Solution:
- Check OAuth2 app settings in EmailEngine
- Verify against Google Cloud Console / Azure AD
- Look for error messages in OAuth2 app settings page
- Gmail OAuth2 setup guide
- Outlook OAuth2 setup guide
Insufficient permissions
- Account doesn't have required scopes
- For shared mailboxes: user doesn't have access
Solution:
- Update OAuth2 app scopes
- Have user re-authenticate to grant new scopes
- For shared mailboxes: verify user has permissions in Microsoft 365 admin

State: connectError

What it means: Cannot reach the mail server.

Common Causes:

Incorrect host or port
```
# Check current settings
curl https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" | jq '.imap'
```
Solution:
- Verify IMAP/SMTP settings with provider documentation
- Common Gmail settings: Gmail IMAP
- Common Outlook settings: Outlook IMAP

Firewall blocking connections

EmailEngine server firewall blocks outbound connections
Corporate firewall blocks email ports

Solution:

# Test connectivity from EmailEngine server
telnet imap.gmail.com 993
telnet smtp.gmail.com 587

If connection fails, check firewall rules:

# Allow outbound connections to IMAP/SMTP ports
iptables -A OUTPUT -p tcp --dport 993 -j ACCEPT  # IMAP SSL
iptables -A OUTPUT -p tcp --dport 587 -j ACCEPT  # SMTP STARTTLS
iptables -A OUTPUT -p tcp --dport 465 -j ACCEPT  # SMTP SSL

DNS resolution failure
- Cannot resolve mail server hostname
Solution:
```
# Test DNS resolution
nslookup imap.gmail.com
dig imap.gmail.com
```
If DNS fails:
- Check /etc/resolv.conf
- Verify network configuration
- Try different DNS server (e.g., 8.8.8.8)
Server is down or unreachable
- Mail provider having outage
- Server maintenance
Solution:
- Check provider status page
- Wait and retry later
- EmailEngine will automatically retry

State: connecting

What it means: Connection in progress.

Normal Behavior:

Accounts usually stay in this state for 5-30 seconds
First connection may take longer (folder sync)

If Stuck:

Check logs for what's happening:

journalctl -u emailengine -f | grep user123

Possible issues:
- Slow server response
- Large mailbox syncing
- Network latency
Wait a few minutes before intervening

If stuck >5 minutes:

# Trigger reconnection
curl -X PUT https://your-ee.com/v1/account/user123/reconnect \
  -H "Authorization: Bearer YOUR_TOKEN"

State: unset

What it means: OAuth2 authentication not completed.

Occurs When:

Hosted authentication form URL was generated
User hasn't completed OAuth2 flow yet

Solution:

User needs to visit the authentication form URL
Complete OAuth2 consent
Account will automatically move to connecting then connected

If user says they completed it:

Check redirect URL is correct
Verify OAuth2 app is enabled in EmailEngine
Check for errors in OAuth2 app settings
Generate new authentication form URL

State: disconnected

What it means: Account is disconnected (manually disabled or closed).

Solution:

# Re-enable account if it was disabled
curl -X PUT https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "imap": { "disabled": false } }'

# Then reconnect
curl -X PUT https://your-ee.com/v1/account/user123/reconnect \
  -H "Authorization: Bearer YOUR_TOKEN"

Provider-Specific Issues

Gmail Issues

Account Password Authentication No Longer Supported

Error Message: "Please log in via your web browser" or "Invalid credentials"

Gmail Account Passwords Disabled

Gmail has completely disabled account password authentication. The "Less secure app access" feature is no longer available. You must use app passwords or OAuth2.

Solution:

App Passwords (for testing): Generate an app-specific password (requires 2FA enabled)
OAuth2 (recommended for production): Follow the Gmail OAuth2 guide

Rate Limits

Symptoms:

Intermittent connection failures
Slow syncing
Temporary authentication errors

Gmail Limits:

15 concurrent IMAP connections
2500 MB download/day
500 MB upload/day

Solution:

Reduce sub-connections
Implement path filtering
Consider Gmail API for high-volume: Gmail API guide
Spread operations over time

OAuth2 Scope Too Wide (Public Apps)

Error: Google rejects your OAuth2 app verification

Reason: https://mail.google.com/ scope too broad

Solution:

Use narrower scopes if possible
Justify why IMAP access is needed
Consider Internal app (organization only)
Consider app passwords as alternative

Outlook/Microsoft 365 Issues

IMAP Not Enabled

Error Message: "IMAP is disabled"

Solution:

Go to Microsoft 365 admin center
Users → Active users → Select user
Mail tab → Manage email apps
Enable IMAP
Wait 15-30 minutes for changes to propagate

OAuth2 redirect_uri Mismatch

Error Code: AADSTS50011

Solution:

Check redirect URI in Azure AD app registration
Must match exactly in EmailEngine OAuth2 settings
Check for:
- http vs https
- Trailing slashes
- Port numbers
- Case sensitivity

Error Message: Need admin approval

Solution:

Organization admin must grant consent
Or admin can pre-approve app for all users
In Azure AD → App registrations → API permissions → Grant admin consent

Shared Mailbox Access Denied

Symptoms:

Authentication succeeds but cannot access mailbox
"Mailbox not found" error

Solution:

Verify user has "Full Access" permission to shared mailbox
In Microsoft 365 admin:
- Recipients → Shared → Select mailbox
- Mailbox delegation → Full Access
- Add user
Wait 15-30 minutes for permissions to propagate

Yahoo/AOL/Verizon Issues

App Password Required

Error Message: "Invalid credentials"

Cause: 2FA enabled, app password needed

Solution:

Generate app password:
- Yahoo: Account Security
- AOL: Account Security settings
Use app password instead of main password
Update account in EmailEngine

iCloud Issues

App-Specific Password Required

Error Message: "Invalid credentials"

Solution:

Generate app-specific password:
- Visit appleid.apple.com
- Sign in → Security → App-Specific Passwords
- Generate password
Use app-specific password in EmailEngine

Two-Factor Authentication Must Be Enabled

iCloud requires 2FA enabled to generate app-specific passwords.

Solution:

Enable 2FA on Apple ID
Then generate app-specific password

Webhook Issues

Webhooks Not Firing

Check webhook configuration:

curl https://your-ee.com/v1/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  | jq '.webhooks'

Common Causes:

Webhook URL not set

curl -X POST https://your-ee.com/v1/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "webhooks": "https://myapp.com/webhooks" }'

Webhook URL unreachable

Test manually:

curl -X POST https://myapp.com/webhooks \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Check firewall allows EmailEngine IP
Verify SSL certificate is valid

Webhook endpoint returning errors
- Check your webhook handler logs
- Must return 2xx status code
- EmailEngine will retry on failures
For Gmail API/MS Graph accounts: Subscription not active
- Check account details for subscription status
- For Gmail API: Verify Cloud Pub/Sub is configured
- For MS Graph: Verify subscription is active

Debug webhooks:

Check webhook queue in Bull Board:

Navigate to EmailEngine dashboard → Bull Board
Check "webhooks" queue
Look for failed jobs and error messages

Webhook Delays

Cause: Webhook queue backed up

Solution:

Check Bull Board for queue status
Increase webhook workers (if needed)
Optimize your webhook endpoint response time
Implement idempotency (handle duplicate webhooks)

Connection Issues

Too Many Connections

Error Message: "Maximum number of connections reached"

Cause: Exceeding provider's concurrent connection limit

Solution:

# Check current subconnections
curl https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  | jq '.subconnections'

# Reduce sub-connections
curl -X PUT https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "subconnections": [] }'

Provider Limits:

Gmail: 15 concurrent connections
Outlook: 15 concurrent connections
Yahoo: 10 concurrent connections

SSL/TLS Certificate Errors

Error Message: "Certificate verification failed" or "CERT_HAS_EXPIRED"

For Provider Servers:

Usually indicates provider issue or misconfigured server.

For Self-Hosted Servers:

# Accept self-signed certificates (development only)
curl -X PUT https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imap": {
      "tls": {
        "rejectUnauthorized": false
      }
    }
  }'

Security

Only disable certificate verification for development/testing with self-signed certs. In production, use proper CA-signed certificates.

IDLE Timeout Issues

Symptoms:

Connection drops after period of inactivity
Frequent reconnections

Cause: Server doesn't support IMAP IDLE or closes IDLE after timeout

Solution: EmailEngine handles this automatically by:

Detecting IDLE timeout
Reconnecting automatically
Falling back to polling if IDLE not supported

No action needed from you. If issues persist, check logs for specific errors.

Performance Issues

Slow Initial Sync

Symptoms:

Account stuck in "connecting" for long time
First sync takes hours

Cause: Large mailbox with many messages

Solution:

Use path filtering to sync only needed folders:

curl -X PUT https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": ["INBOX", "\\Sent"]
  }'

Be patient - Initial sync can take time for large mailboxes
- 10,000 messages: ~5-10 minutes
- 50,000 messages: ~30-60 minutes
- 100,000+ messages: Hours
Consider Gmail API for very large Gmail accounts:
- Faster initial sync
- Better performance
- Gmail API guide

High Memory/CPU Usage

Symptoms:

EmailEngine using excessive resources
Server becomes slow

Solutions:

Reduce number of accounts
- Check account count: curl https://your-ee.com/v1/accounts | jq '.total'
- Scale vertically (increase server resources)
Reduce sub-connections
- Remove unnecessary sub-connections
- Only monitor critical folders in real-time
Implement path filtering
- Don't sync unnecessary folders
- Use wildcards carefully
Optimize webhook endpoint
- Slow webhook responses cause queue backup
- Implement async processing
- Return 200 immediately, process in background
Increase Redis memory
- EmailEngine stores data in Redis
- Ensure adequate Redis memory allocation

OAuth2-Specific Issues

Token Refresh Failures

Symptoms:

Account enters authenticationError periodically
"invalid_grant" errors in logs

Causes:

Refresh token expired (Microsoft)
- Microsoft refresh tokens expire after 90 days of inactivity
- EmailEngine keeps them active by regular use
- If expired, user must re-authenticate
OAuth2 app credentials changed
- Client secret rotated but not updated in EmailEngine
- Solution: Update OAuth2 app settings in EmailEngine with new credentials
User revoked access
- User manually revoked app permission
- Solution: User must re-authenticate
OAuth2 app disabled/deleted
- App deleted in Google Cloud Console / Azure AD
- Solution: Recreate app or update settings

"redirect_uri_mismatch" Error

Google Error Message: "The redirect URI in the request does not match..."

Microsoft Error Code: AADSTS50011

Solution:

Check redirect URI in OAuth2 app configuration (Google Cloud Console / Azure AD)
Check redirect URL in EmailEngine OAuth2 app settings
They must match exactly:
- Case-sensitive
- http vs https
- Trailing slashes matter
- Port numbers must match
- Domain must match

Example mismatch:

Provider: https://ee.company.com/oauth
EmailEngine: https://ee.company.com:3000/oauth
[NO] Port mismatch!

Insufficient Permissions

Error Message: "insufficient_scope" or "unauthorized_client"

Cause: Required scope not configured

Solution:

Check required scopes:
- Gmail IMAP: https://mail.google.com/
- Gmail API: gmail.modify
- Outlook IMAP: IMAP.AccessAsUser.All, SMTP.Send, offline_access
- Outlook Graph: Mail.ReadWrite, Mail.Send, offline_access
Update OAuth2 app in provider console:
- Google Cloud Console → APIs & Services → OAuth consent screen → Scopes
- Azure AD → App registrations → API permissions
Update EmailEngine OAuth2 app if using additional scopes
Have users re-authenticate to grant new permissions

Diagnostic Commands

Check Account Details

# Full account info
curl https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  | jq .

# Just the state
curl https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  | jq -r .state

# Subconnections info
curl https://your-ee.com/v1/account/user123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  | jq '.subconnections'

Test IMAP Connection

# From EmailEngine server
openssl s_client -connect imap.gmail.com:993 -crlf
# Type: A LOGIN user@gmail.com password
# Then: B LIST "" "*"

Test SMTP Connection

# From EmailEngine server
openssl s_client -connect smtp.gmail.com:587 -starttls smtp -crlf
# Type: EHLO example.com
# Then: AUTH LOGIN

Check Network Connectivity

# Test DNS
dig imap.gmail.com

# Test port connectivity
telnet imap.gmail.com 993
nc -zv imap.gmail.com 993

# Check firewall rules
iptables -L OUTPUT -n

# Trace route
traceroute imap.gmail.com

Verify OAuth2 Token

# Get current token
curl https://your-ee.com/v1/account/user123/oauth-token \
  -H "Authorization: Bearer YOUR_TOKEN"

# Test token with provider API (Gmail example)
TOKEN="ya29.a0AWY7..."
curl https://www.googleapis.com/gmail/v1/users/me/profile \
  -H "Authorization: Bearer $TOKEN"

Getting Help

Information to Provide

When seeking help, include:

EmailEngine version: Check dashboard or package.json
Account state: From account details API
Error messages: From logs
Provider: Gmail, Outlook, Yahoo, etc.
Authentication method: IMAP/SMTP, OAuth2, service account
Reproduction steps: What leads to the issue

EmailEngine Logs

# Logs with account-specific filter
journalctl -u emailengine | grep user123

# Logs with OAuth2 filter
journalctl -u emailengine | grep -i oauth

# Logs with error filter
journalctl -u emailengine | grep -i error

# Follow logs in real-time
journalctl -u emailengine -f

Useful Resources

EmailEngine API Documentation
EmailEngine GitHub Issues
Support Contact
Provider-specific documentation:
- Gmail IMAP Settings
- Outlook IMAP Settings

Quick Diagnostics​

Check Account Status​

Check EmailEngine Logs​

Common Account States and Solutions​

State: authenticationError​

For IMAP/SMTP Accounts​

For OAuth2 Accounts​

State: connectError​

State: connecting​

State: unset​

State: disconnected​

Provider-Specific Issues​

Gmail Issues​

Account Password Authentication No Longer Supported​

Rate Limits​

OAuth2 Scope Too Wide (Public Apps)​

Outlook/Microsoft 365 Issues​

IMAP Not Enabled​

OAuth2 redirect_uri Mismatch​

Admin Consent Required​

Shared Mailbox Access Denied​

Yahoo/AOL/Verizon Issues​

App Password Required​

iCloud Issues​

App-Specific Password Required​

Two-Factor Authentication Must Be Enabled​

Webhook Issues​

Webhooks Not Firing​

Webhook Delays​

Connection Issues​

Too Many Connections​

SSL/TLS Certificate Errors​

IDLE Timeout Issues​

Performance Issues​

Slow Initial Sync​

High Memory/CPU Usage​

OAuth2-Specific Issues​

Token Refresh Failures​

"redirect_uri_mismatch" Error​

Insufficient Permissions​

Diagnostic Commands​

Check Account Details​

Test IMAP Connection​

Test SMTP Connection​

Check Network Connectivity​

Verify OAuth2 Token​

Getting Help​

Information to Provide​

EmailEngine Logs​

Useful Resources​

Quick Diagnostics

Check Account Status

Check EmailEngine Logs

Common Account States and Solutions

State: authenticationError

For IMAP/SMTP Accounts

For OAuth2 Accounts

State: connectError

State: connecting

State: unset

State: disconnected

Provider-Specific Issues

Gmail Issues

Account Password Authentication No Longer Supported

Rate Limits

OAuth2 Scope Too Wide (Public Apps)

Outlook/Microsoft 365 Issues

IMAP Not Enabled

OAuth2 redirect_uri Mismatch

Admin Consent Required

Shared Mailbox Access Denied

Yahoo/AOL/Verizon Issues

App Password Required

iCloud Issues

App-Specific Password Required

Two-Factor Authentication Must Be Enabled

Webhook Issues

Webhooks Not Firing

Webhook Delays

Connection Issues

Too Many Connections

SSL/TLS Certificate Errors

IDLE Timeout Issues

Performance Issues

Slow Initial Sync

High Memory/CPU Usage

OAuth2-Specific Issues

Token Refresh Failures

"redirect_uri_mismatch" Error

Insufficient Permissions

Diagnostic Commands

Check Account Details

Test IMAP Connection

Test SMTP Connection

Check Network Connectivity

Verify OAuth2 Token

Getting Help

Information to Provide

EmailEngine Logs

Useful Resources