Email Piping

From WHMCS Documentation

Email piping automatically imports emails for an email address into the support ticket system. As a result, clients can open and reply to tickets via email without the need to log in to the client area first.

Department Setup

Before you can set up email piping, you must configure your support departments at Configuration () > System Settings > Support Departments or, prior to WHMCS 8.0, Setup > Support Departments. Add each of your departments and the email address that you assigned to them.

Email Piping Methods

Watch Video Tutorial

When you configure email piping, you can choose one of two options.

  • The Forwarder Method uses email forwarders to pipe messages to WHMCS. Use this method if you use cPanel or DirectAdmin and are piping in emails from the domain that WHMCS is installed on.
  • The Mail Importing Method pipes messages to WHMCS from individual email accounts. Use this method if you don't use cPanel or DirectAdmin or if you want to pipe email from multiple domains.

If you have customized the location of the crons directory, adjust the file path examples below accordingly.

Set Up the Forwarder Method

The forwarder configuration page

To set up email piping via forwarders, you must configure your server to pipe messages to WHMCS. To configure this, navigate to the Email Forwards section of your web hosting control panel and create a forwarder.

Sample Forwarder Command

| php -q /home/username/public_html/whmcs/crons/pipe.php

You can find a copy-and-paste-ready command with the specific path for your setup. Navigate to Configuration () > System Settings > Support Departments or, prior to WHMCS 8.0, Setup > Support Departments within your WHMCS installation and copy the command from the forwarder command field.

The pipe.php file requires 755 permissions to function properly.
If using DirectAdmin, you must enter the command enclosed in quotes ("") for the system to accept it.

Set Up Email Importing

Email importing is an alternative to email piping. For more information, see Email Importing.

Testing Email Piping

After you set up email piping, try sending a test email. If the piping is correctly configured, the system will open a new ticket. (It can take up to five minutes if you use the cron job method.) For testing purposes, do not use your admin email address to send the message. The system expects emails from admin email addresses to be replies to tickets only, and so it won't open new tickets.

If the system doesn't create a ticket when sending an email, check the Ticket Mail Import Log at Configuration () > System Logs (in WHMCS 7.x and earlier, Utilities > Logs). If WHMCS received the message, it will appear in this list with the reason why it failed to create a ticket. If the message you sent doesn't appear here, the forwarder you set up previously is not working correctly and WHMCS didn't receive the message.

If you get the error message The system could not find the ticket ID. (Ticket ID Not Found prior to WHMCS 8.3), you are trying to open a support ticket from your admin email address. Admins can only reply to tickets, not open new ones. Submit a ticket from any other email address and the system should accept it.

For other errors, see the following Common Problems and Troubleshooting sections.

Spam Control

When you use email piping, spam can become a problem. To help with this, WHMCS includes spam control filters. For more information, see Spam Control.

Common Problems

If the system didn't pipe an email into the ticket system, check the Ticket Mail Import Log at Configuration () > System Logs (in WHMCS 7.x and earlier, Utilities > Logs). This shows all the emails that WHMCS's email piping feature has processed and any errors that may have occurred. Below are the most common errors:

The system could not find the ticket ID.

This error message indicates that you are sending via an email address that you assigned to an administrator. Administrators can reply to tickets but cannot open new ones. To test this, you must send an email from an email address that doesn't belong to an admin in your WHMCS system.

Prior to WHMCS 8.3, this was Ticket ID Not Found.

The system blocked a potential email loop.

This error message indicates that WHMCS received a large number of emails from the same email address, indicating an auto-responder loop. To break the cycle, WHMCS did not import the email. By default, the system will block any new tickets from the offending address if it receives 10 emails from the same address within a 15 minute period. You can customize this in the General Settings.

Prior to WHMCS 8.3, this was Blocked Potential Email Loop.

The sender's email address is not registered.

This error message indicates that you have chosen to only allow registered clients to open tickets in this department. You must uncheck Clients Only for the support department at Configuration () > System Settings > Support Departments or, prior to WHMCS 8.0, Setup > Support > Support Departments.

Prior to WHMCS 8.3, this was Unregistered Email Address.

The system prevented an autoresponder from opening a ticket.

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.
  • Regardless of your settings, WHMCS will not accept email that email that contains the Auto-Submitted header via email piping or email importing.

This error message indicates that an email contained the Auto-Submitted attribute in its headers. The system will not import these messages into the WHMCS support ticket system. This avoids sending an auto-reply in accordance with the RFC 3834 email specification.

Prior to WHMCS 8.3, this was Prevented an Auto Responder from Opening a Ticket.

Troubleshooting

If the system hasn't piped an email into the ticket system and it is not in the Ticket Mail Import Log (above), follow the steps below to identify the cause of the problem. There are different procedures depending upon whether you use the email forwarder or cron piping methods.

Unable to communicate with the WHMCS installation

This error occurs when the cron.php file is unable to communicate with the WHMCS installation. It typically occurs when you have customized the location of the /crons directory. The cron.php file will look for the WHMCS directory in the location in the /crons/config.php file. To resolve this error:

  1. Open the /crons/config.php file.
  2. Uncomment the $whmcspath line by removing the preceding // characters.
  3. Ensure the $whmcspath path is the full system path to your WHMCS directory. This is the directory that contains the init.php and clientarea.php files.

An example of a correctly-completed file is available on this page.

Email Forwarder Method

Local Delivery Failed Error Message

If a bounce email includes an error that states local delivery failed (like the error shown below) when sending an email in to your piped email address, the forwarder entry is not correct. The message will not go to the pipe.php script.

pipe to |/home/username/public_html/whmcs/crons/pipe.php
generated by support@example.com
local delivery failed

To correct this, ensure the /crons/pipe.php file uses 755 permissions. Then, try the following variations of the email forwarder command:

|/usr/bin/php -q /home/username/public_html/whmcs/crons/pipe.php
|/usr/local/bin/php -q /home/username/public_html/whmcs/crons/pipe.php

Why is email piping with Direct Admin sending the email twice?

To fix this problem you need to remove or comment out "unseen" from your exim.conf file.

For example:

virtual_aliases_nostar:
 driver = redirect
 allow_defer
 allow_fail
 data = ${if exists{/etc/virtual/${domain}/aliases}{${lookup{$local_part}lsearch{/etc/virtual/${domain}/aliases}}}}
 file_transport = address_file
 group = mail
 pipe_transport = virtual_address_pipe
 retry_use_local_part
 #unseen
 #include_domain = true

Reference: Directadmin forum thread

Cron Piping Method

When using the Cron Piping method, it is possible to see the error that has prevented importing emails. First, temporarily add the following variable to the configuration.php file:

$pop_cron_debug = true;

Next, visit the pop.php file directly in your browser (for example, http://www.example.com/crons/pop.php). You may encounter the common errors below:

Could Not Authenticate

This error indicates that the POP details in the required fields are incorrect. It could also be an intermittent issue between your WHMCS server and the mail server.

To troubleshoot this:

  1. Go to Configuration () > System Settings > Support Departments or, prior to WHMCS 8.0, Setup > Support > Support Departments.
  2. Edit the department that the notification email referenced.
  3. Verify that the POP3 settings use correct values (username (user@example.com), password, and port),
  4. Verify that the hostname is a FQDN and resolves. Alternately, check with your system administrator or hosting provider for the correct connection details to use for POP3.
  5. Click Save Changes.

Sender Verify Failed

This error indicates that the SMTP server requires a valid account on the server to send from.

Check that the From Address in the Mail tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings is not blank and you have entered a valid address that is authorized to send mail through the SMTP server. You may need to check with your hosting provider or mail server administrator.

Too Many Login Failures

This error indicates that the mail server is blocking WHMCS because the email piping login details under Configuration () > System Settings > Support Departments or, prior to WHMCS 8.0, Setup > Support > Support Departments are incorrect.

Check whether the details you entered are correct. After correcting them, you will need to wait out the block time. If you use a cPanel server, you can whitelist the WHMCS IP address in cPHulkd or remove the WHMCS IP address from the blacklist. For more information, see documentation.

WHMCS Pop Cron Did Not Run

This error indicates a problem with the POP3 Import Method feature, which imports emails into the WHMCS Support ticket system. It indicates that you have entered POP3 details for a support department, but you haven't configured the required cron job or finished importing the emails.

Step-by-step instructions to resolve this warning email are in this help guide.

After you have applied one of these resolutions, the system will stop sending the warning email.