Email Importing

Email importing retrieves support ticket email replies for your support ticket system. It can import email from multiple domains.

  • Email piping and email importing use separate configurations and are distinct methods of retrieving email replies.
    • We recommend using email piping if you use cPanel & WHM and only receive email replies from one domain.
    • We recommend using email importing if you use other control panels or if you want to import email from multiple domains.
  • Your mail service provider is separate from your configuration for email importing. You can update this configuration at Configuration () > System Settings > General Settings in the Mail tab.

Service Providers

WHMCS can import email through several different service providers, including POP3 or IMAP, Google, and Microsoft®. If you use WHMCS’s Google or Microsoft integrations, you can get the full benefit of those services’ additional features, including OAuth2, which provides more security than traditional username-and-password authentication.

  • Microsoft email services are available in WHMCS 8.6 and later and support all Microsoft Entra® ID (formerly Microsoft Azure®) compatible email services.
  • Google supports email via Gmail™.

Configuring Email Importing

To configure email importing for a support department, you must set up the support department’s email account and then add that information to your support department configuration.

To do this:

  1. Set up your email accounts:
  2. In WHMCS, go to Configuration () > System Settings > Support Departments.
    The list of support departments in the Admin Area.
  3. Create a new department and enter the top section of information or, for existing departments, click Edit.
    Editing a support department in the Admin Area.
  4. Enter the email information for the department:
    1. Select a service provider.
    2. Enter the appropriate details for your service provider.
    3. If you selected OAuth2 as your authentication type for Google, enter your email address and the ClientID and Client Secret values that you generated. Then, click Connect.
  5. Set up a cron job to run the pop.php file using the Ticket Importing using Mail Importing (POP3/IMAP) command that displays at Configuration () > System Settings > Support Departments.
    Importing Cron Commands
    We recommend that you set this to run every five minutes.

The system will delete email in the source mailboxes upon successful import into WHMCS.

After you configure email importing, we recommend sending a test email to check your configuration. Do not use an admin’s email address to send this message.

Security and OAuth2

OAuth is a technology that authorizes apps or services like WHMCS to access another service, such as a Gmail account. It’s more secure than traditional username-and-password authentication. In addition to its security benefits, some mail providers require OAuth or have announced a requirement for it in the future.

  • WHMCS includes OAuth authentication support for email importing through Gmail in WHMCS 8.1 and later.
  • To use OAuth for Gmail email with WHMCS, you will need to both configure Gmail as your mail service provider and create an app for it in the Gmail Cloud console.
For steps to enable email importing using OAuth with Google, see Set Up Email Importing with Google.

RFC 3834

In WHMCS 8.1 and later, the system sends support emails with RFC 3834-compliant headers by default.

  • You can disable this at Configuration () > System Settings > General Settings in the Mail tab.
    Disabling RFC 3834 headers in General Settings
  • Regardless of your settings, WHMCS will not accept email that contains the Auto-Submitted header via email piping or email importing.

Blocked Support Email Replies

WHMCS may block email replies to existing support tickets for several reasons:

  • The sender is unregistered.
  • The sender is not a CC recipient.
  • The sender is not associated with the support ticket’s client account.

As of WHMCS 8.3, blocking only occurs if you have disabled Allow Insecure Imports in the Support tab at Configuration () > System Settings > General Settings. If this setting is disabled and blocking does occur, you can still view these replies and add them to support tickets manually.

Troubleshooting

Error or IssueCauseNext Steps
Argument 7 passed to processPoppedTicket()This issue is due to the presence of a pop.php file from an older version of WHMCS.Argument 7 Ticket Errors
The system prevented an autoresponder from opening a ticket. (WHMCS 8.4 and later) or Prevented an Auto Responder from Opening a Ticket (WHMCS 8.3 and earlier)An email ticket reply contained the Auto-Submitted attribute in its headers.Auto-Submitted Header Errors
Error: cannot connect to host ; error = stream_socket_client(): unable to connect to tls://mail.example.com:143 (php_network_getaddresses: getaddrinfo failed: Name or service not known) (errno = 0 )There is an invalid or unreachable Hostname value in the support department’s mail importing configuration.Cannot Connect to Host Errors
Connection refusedThe server’s firewall is blocking traffic to Google®.Connection Refused Errors
Department Not Found or Department Not Found. ExitingThe support department is a CC or BCC recipient.Department Not Found Errors
Email importing is importing the same email replies multiple times.You have configured multiple support departments in WHMCS to use the same mailbox.Duplicate Imported Replies
The system blocked a potential email loop. (WHMCS 8.4 and later) or Blocked Potential Email Loop (WHMCS 8.3 and earlier)WHMCS received a large number of emails from the same email address, indicating an auto-responder loop.Email Loop Errors
Can not authenticate to POP3 server or Logon failure: unknown user name or bad password or Password command failed or Too many login failuresYou entered an invalid username or password, your mailserver has blocked (blacklisted) you, or you are using an authentication method that your POP mailbox does not support.Logon Failure Errors
The Mail Import test failed: cannot select INBOX, is this a valid transport?The mail importing configuration is using the wrong port number.Mail Import Test Failed Errors
Connection unsuccessful. Please close this window and try again.Your Microsoft Entra® ID app credentials are invalid.Microsoft Connection Errors
Failed to Create $app_name application. Error detail URL may not contain a query string.Microsoft Entra apps do not support the redirect URI format in WHMCS if you have set Friendly URLs to Basic URLs.Microsoft Import Query Errors
WHMCS Pop Cron Did Not RunYou have configured POP3 details for a support department but the cron job does not run successfully.POP3 Cron Not Running
One or more POP3 connections failed or Error: read failed - connection closed?WHMCS cannot connect to the support department mailbox.POP3 Read Failed Errors
You experience timezone-related issues in WHMCS or while running WHMCS automation.There is a timezone misconfiguration or a mismatch between the webserver’s PHP configuration and the cron engine’s PHP configuration.System Timezone Issues
TypeError: Return value of WHMCS\File::guessFileExtension() must be of the type string, null returned in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/File.phpThe fileinfo function is missing or disabled in your server’s PHP configuration.TypeError guessFileExtension Errors
Unable to communicate with the WHMCS installationThe cron.php, pop.php, or pipe.php files cannot communicate with the WHMCS installation.Unable to Communicate Errors
The sender's email address is not registered. (WHMCS 8.4 and later) or Unregistered Email Address (WHMCS 8.3 and earlier)You have chosen to only allow registered clients to open tickets in this department.Unregistered Address Errors
email-importing support-tickets rfc-3834 google logs support-departments microsoft oauth

Last modified: January 13, 2025