Generic IMAP/SMTP Accounts

This guide covers setting up email accounts using standard IMAP and SMTP protocols. This method works with virtually any email provider that supports these protocols, including self-hosted mail servers, regional providers, and services not covered by specific OAuth2 integrations.

Overview

IMAP (Internet Message Access Protocol) and SMTP (Simple Mail Transfer Protocol) are the standard protocols for email:

• IMAP: Used for reading and managing emails
• SMTP: Used for sending emails

Unlike OAuth2-based setups, IMAP/SMTP accounts require direct credentials (username and password or app-specific passwords).

When to Use IMAP/SMTP

Best for:

• Email providers without OAuth2 support
• Self-hosted mail servers
• Regional email providers
• Quick testing and development
• Legacy systems

Advantages:

• Universal compatibility
• Immediate setup (no OAuth2 app configuration)
• Works with virtually any provider
• Simple authentication

Disadvantages:

• Requires storing passwords
• May not work with accounts that have 2FA without app passwords
• Some providers (Gmail, Outlook) may block standard authentication

Supported Providers

EmailEngine's IMAP/SMTP support works with hundreds of providers. Here are common examples:

Major Providers with App Passwords

Gmail:

• Requires app-specific password if 2FA is enabled
• See Gmail IMAP guide for OAuth2 alternative

Outlook.com / Hotmail.com / Live.com:

• OAuth2 required - Microsoft has disabled regular password authentication
• Use Outlook OAuth2 guide to set up OAuth2 for IMAP/SMTP

Yahoo Mail:

• Requires app-specific password
• Generate at Yahoo Account Security

iCloud Mail:

• Requires app-specific password
• Generate at Apple ID Account

Self-Hosted Servers

IMAP/SMTP works with any standard-compliant mail server:

• Postfix + Dovecot
• Microsoft Exchange
• Zimbra
• MDaemon
• MailEnable
• hMailServer
• etc.

Server Settings Auto-Detection

EmailEngine can automatically detect IMAP/SMTP server settings for most email providers.

Via Hosted Authentication Form

When users add accounts through the hosted authentication form, EmailEngine attempts to automatically detect the correct server settings based on the email address. In most cases, users only need to enter their email and password. For self-hosted servers or less common providers where auto-detection fails, manual server configuration is required.

Via API

Use the autoconfig endpoint to detect server settings programmatically:

curl "https://your-ee.com/v1/autoconfig?email=user@example.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response includes detected IMAP and SMTP settings:

{
  "imap": {
    "host": "imap.example.com",
    "port": 993,
    "secure": true
  },
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "secure": false
  }
}

You can then use these settings when registering an account.

Outlook.com / Hotmail.com / Live.com

Microsoft has disabled regular password authentication for consumer accounts. You must use OAuth2 authentication. See the Outlook OAuth2 guide for setup instructions.

Understanding the "secure" Setting

The secure setting controls how TLS is established:

• secure: true (ports 993/465) - TLS is used from the start of the connection (implicit TLS)
• secure: false (ports 143/587) - Connection starts unencrypted, then EmailEngine automatically upgrades to TLS using STARTTLS if the server supports it

Setting secure: false does not mean the connection is unencrypted. EmailEngine will use TLS in both cases - the difference is only in how TLS is negotiated.

Authentication Methods

Standard Password

For providers that allow it, use your regular account password.

{
  "account": "user123",
  "name": "John Doe",
  "email": "john@example.com",
  "imap": {
    "host": "imap.example.com",
    "port": 993,
    "secure": true,
    "auth": {
      "user": "john@example.com",
      "pass": "your-password"
    }
  },
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "secure": false,
    "auth": {
      "user": "john@example.com",
      "pass": "your-password"
    }
  }
}

App-Specific Passwords

For providers requiring app passwords (Gmail, Yahoo, iCloud, AOL):

1. Enable 2FA on your account if not already enabled
2. Generate an app-specific password from your account settings
3. Use this app password instead of your main password

{
  "account": "user123",
  "name": "John Doe",
  "email": "john@gmail.com",
  "imap": {
    "host": "imap.gmail.com",
    "port": 993,
    "secure": true,
    "auth": {
      "user": "john@gmail.com",
      "pass": "abcd efgh ijkl mnop" // App password
    }
  },
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "auth": {
      "user": "john@gmail.com",
      "pass": "abcd efgh ijkl mnop" // Same app password
    }
  }
}

Different IMAP and SMTP Credentials

Some providers use different credentials for IMAP and SMTP:

{
  "account": "user123",
  "imap": {
    "auth": {
      "user": "john@example.com",
      "pass": "imap-password"
    }
  },
  "smtp": {
    "auth": {
      "user": "john@example.com",
      "pass": "smtp-password"
    }
  }
}

SSL/TLS Configuration

Port and Security Options

Port 993 with SSL/TLS (IMAP):

{
  "imap": {
    "port": 993,
    "secure": true
  }
}

Port 143 with STARTTLS (IMAP):

{
  "imap": {
    "port": 143,
    "secure": false // STARTTLS will be used
  }
}

Port 465 with SSL/TLS (SMTP):

{
  "smtp": {
    "port": 465,
    "secure": true
  }
}

Port 587 with STARTTLS (SMTP):

{
  "smtp": {
    "port": 587,
    "secure": false // STARTTLS will be used
  }
}

Self-Signed Certificates

For development or self-hosted servers with self-signed certificates, you can disable certificate verification.

Per-account setting:

Set tls.rejectUnauthorized: false when registering the account:

{
  "imap": {
    "host": "mail.example.com",
    "port": 993,
    "secure": true,
    "tls": {
      "rejectUnauthorized": false
    }
  },
  "smtp": {
    "host": "mail.example.com",
    "port": 587,
    "secure": false,
    "tls": {
      "rejectUnauthorized": false
    }
  }
}

Global setting for all accounts:

To disable certificate verification for all IMAP/SMTP connections, set the ignoreMailCertErrors setting:

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

Or via environment variable: EENGINE_SETTINGS='{"ignoreMailCertErrors": true}'

Security Warning

Only disable certificate verification for development/testing. In production, use proper SSL/TLS certificates (e.g., from Let's Encrypt).

Adding Accounts via API

Basic IMAP/SMTP Account

Add accounts using the Register Account API endpoint:

curl -X POST https://your-ee.com/v1/account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user123",
    "name": "John Doe",
    "email": "john@example.com",
    "imap": {
      "host": "imap.example.com",
      "port": 993,
      "secure": true,
      "auth": {
        "user": "john@example.com",
        "pass": "password"
      }
    },
    "smtp": {
      "host": "smtp.example.com",
      "port": 587,
      "secure": false,
      "auth": {
        "user": "john@example.com",
        "pass": "password"
      }
    }
  }'

IMAP-Only Account

For read-only access without sending capability:

curl -X POST https://your-ee.com/v1/account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user123",
    "name": "John Doe",
    "email": "john@example.com",
    "imap": {
      "host": "imap.example.com",
      "port": 993,
      "secure": true,
      "auth": {
        "user": "john@example.com",
        "pass": "password"
      }
    }
  }'

SMTP-Only Account

For send-only access:

curl -X POST https://your-ee.com/v1/account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user123",
    "name": "John Doe",
    "email": "john@example.com",
    "smtp": {
      "host": "smtp.example.com",
      "port": 587,
      "secure": false,
      "auth": {
        "user": "john@example.com",
        "pass": "password"
      }
    }
  }'

Adding Accounts via Hosted Authentication Form

Users can add their own accounts through EmailEngine's web interface:

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

EmailEngine will generate a form URL where users can:

1. Enter their IMAP/SMTP settings
2. Test the connection
3. Complete setup

EmailEngine can auto-detect settings for many common providers.

Learn more about hosted authentication →

Testing Connection

Before adding an account, verify credentials work:

curl -X POST https://your-ee.com/v1/verifyAccount \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imap": {
      "host": "imap.example.com",
      "port": 993,
      "secure": true,
      "auth": {
        "user": "john@example.com",
        "pass": "password"
      }
    },
    "smtp": {
      "host": "smtp.example.com",
      "port": 587,
      "secure": false,
      "auth": {
        "user": "john@example.com",
        "pass": "password"
      }
    }
  }'

Response if successful:

{
  "imap": {
    "success": true
  },
  "smtp": {
    "success": true
  }
}

Advanced Configuration

Custom Sent Mail Path

Override the Sent folder path when EmailEngine's auto-detection fails. This can happen when:

• The server doesn't support the SPECIAL-USE extension and uses a folder name that EmailEngine's heuristics don't recognize
• The server uses localized folder names (e.g., Microsoft 365 over IMAP without SPECIAL-USE support may use language-specific names)
• A mail client created a Sent folder at a different path than the server default, and you want sent emails stored there

{
  "imap": {
    "sentMailPath": "Sent Items"
  }
}

Common folder name variations:

• Sent (most providers)
• Sent Messages (some providers)
• Sent Items (Microsoft Exchange)
• [Gmail]/Sent Mail (Gmail)

Learn more about custom special folder paths →

Path Filtering

Sync only specific folders:

{
  "path": ["INBOX", "\\Sent", "\\Drafts", "Important"]
}

Learn more about limiting indexed folders →

Sub-Connections

Monitor additional folders in real-time:

{
  "subconnections": ["\\Sent", "Important"]
}

Learn more about sub-connections →

Proxy Configuration

Route EmailEngine's outbound IMAP/SMTP connections through a SOCKS or HTTP proxy server.

Per-account proxy:

Set the proxy field at the account level (not inside imap/smtp objects):

{
  "account": "example",
  "proxy": "socks5://proxy.example.com:1080",
  "imap": {
    "host": "imap.example.com",
    "port": 993,
    "secure": true,
    "auth": {
      "user": "user@example.com",
      "pass": "password"
    }
  },
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "secure": false,
    "auth": {
      "user": "user@example.com",
      "pass": "password"
    }
  }
}

Global proxy for all accounts:

Configure a default proxy for all accounts via the settings API:

curl -X POST https://your-ee.com/v1/settings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "proxyEnabled": true,
    "proxyUrl": "socks5://proxy.example.com:1080"
  }'

Supported proxy protocols:

• socks5:// - SOCKS5 proxy (recommended)
• socks4:// - SOCKS4 proxy
• socks:// - Generic SOCKS proxy
• http:// - HTTP proxy
• https:// - HTTPS proxy

Per-account proxy settings override the global proxy setting.

IMAP and SMTP Only

Proxy settings apply only to IMAP and SMTP connections. HTTP requests made by EmailEngine (OAuth2 token exchange, Gmail API, Microsoft Graph API, license validation, etc.) are not routed through the proxy and will always use direct connections.

If your environment requires proxying HTTP traffic, configure a system-wide HTTP proxy using standard environment variables (HTTP_PROXY, HTTPS_PROXY) at the operating system level.

For environments with strict outbound firewalls, see Outbound Connection Whitelist for a list of domains that EmailEngine needs to reach.