Skip to main content

Troubleshooting

If you're facing issues with connecting to your email account or syncing emails, follow this checklist to investigate and resolve common problems.

1. Check the Activity Logโ€‹

Go to Utilities โ†’ Activity Log inside Perfex CRM to view any error messages related to IMAP connection or syncing failures.

2. Enable Debug Modeโ€‹

To get more detailed error output:

  1. Open index.php in the root of your Perfex CRM installation
  2. Locate the line:
define('ENVIRONMENT', 'production');
  1. Change it to:
define('ENVIRONMENT', 'development');
  1. Save the file and reload the page to see raw error messages
warning

Don't forget to change it back to production after testing!

3. Inspect Your Hosting Error Logsโ€‹

If the screen goes blank or no errors appear in Perfex:

  1. Access your web hosting control panel (e.g., cPanel or Plesk)
  2. Look for "Error Log", usually under the "Metrics" or "Logs" section
  3. Scan for recent errors like "memory exhausted", "timeout", or IMAP-related issues

4. Double-Check Cron Setupโ€‹

Ensure your cron jobs are running. Without them, the Mailbox module cannot sync emails.

Refer to Perfex CRM's documentation or your server admin for cron troubleshooting.

5. OAuth vs Password Authenticationโ€‹

The Mailbox module supports two authentication methods:

For Gmail and Outlook users, OAuth2 is the recommended method. It's more secure and doesn't require storing passwords.

Common OAuth Issues:

IssueSolution
"OAuth connection failed"Verify OAuth credentials in Setup โ†’ Settings โ†’ Mailbox Settings. Check redirect URI configuration. Ensure OAuth app has required scopes.
"Token expired"OAuth tokens are automatically refreshed. Try disconnecting and reconnecting. For Gmail: tokens expire after 7 days for unverified apps.
"OAuth not available"OAuth is only available for Gmail and Outlook. Use password authentication for other providers.

Password Authenticationโ€‹

For email providers that don't support OAuth2, use password authentication.

Check if your email provider needs an App Password

Some email providers, such as Gmail, Yahoo, and Outlook, require you to use an App Password instead of your actual email account password - especially if 2FA (Two-Factor Authentication) is enabled.

Example: Gmail Users

  1. Go to https://myaccount.google.com/security
  2. Enable 2-Step Verification, if not already enabled
  3. Under "Signing in to Google", locate App Passwords
  4. Generate a new app password for "Mail"
  5. Use that password in Mailbox Config of the module instead of your normal Gmail password
warning

Failure to use an App Password when required will result in authentication errors or blocked login attempts.

tip

For Gmail and Outlook, we strongly recommend using OAuth2 instead of App Passwords for better security and ease of use. See Gmail OAuth Setup or Outlook OAuth Setup.

6. Per-Staff vs Global Settingsโ€‹

The module supports both per-staff and global IMAP settings:

  • Per-Staff Settings: Each staff member can configure their own IMAP server, port, encryption, and folder mappings
  • Global Settings: Fallback settings used when per-staff settings are not configured

If emails aren't syncing:

  1. Check your Mailbox Config page for per-staff settings
  2. Verify that IMAP server, port, and encryption are correct
  3. Check folder mappings (especially if using non-standard folder names)
  4. Review Activity Log for specific error messages

7. Read Status Sync Issuesโ€‹

If you've enabled "Sync Read Status to Email Server" but changes aren't reflecting in Gmail/Outlook:

  • Old emails: Emails imported before version 2.1.7 may not have UID stored. Only new emails will sync read status.
  • UID missing: Check Activity Log for "Email ID XXX has no UID stored" messages (this is normal for old emails).
  • OAuth required: Read status sync works best with OAuth authentication.
  • Manual sync: Use the Manual Sync button in Settings to test the connection.

Still Need Help?โ€‹

If you're stuck or unable to resolve an issue, our support team is here to help. Please open a ticket through the Themesic Support Portal, and we'll assist you as soon as possible.