Email Piping
Email piping allows emails sent to an email address to be automatically imported into the support ticket system. As a result clients can open and reply to tickets via email without the need to login to the client area first.
Begin by first configuring your support ticket departments. You do this by going to Setup > Support > Support Departments. Here you need to add each of your departments and the email address assigned to each.
Note:
If the location of the crons directory has been customised, be sure to adjust the file path examples shown on this page accordingly.
Contents
Forwarder Method
This method is recommended if you use cPanel or DirectAdmin and are piping in emails from the same domain your WHMCS is installed on.
To use this method, go to the forwarders section of your control panel and setup the forwarder using the command as given on the Support Departments page which will look something like this " | php -q /home/username/public_html/whmcs/crons/pipe.php" to forward each of your emails into the WHMCS file. If using DirectAdmin, you must enter the command enclosed in quotes "" for it to be accepted.
Note: The pipe.php file requires 755 permissions to function properly.
POP3 Import Method
This method is recommend if you use any control panel other than cPanel or if you are wanting to pipe emails from domains other than just where your WHMCS system is installed. If you wish to pipe emails in from a Gmail/Google Apps Mail account we have specific instructions at Email_Piping:_Google_Apps. To use this method:
- On your mail server create a unique email account for each support department. This must be a full inbox, an alias is not sufficient.
- In WHMCS navigate to Setup > Support > Support Departments > Edit and enter your pop email access details in for each department.
- Then setup a cron job to run the pop.php file using the "Ticket Importing using POP3 Import" command given on the Support Departments page to run every few minutes (every 5 minutes is recommended).
Your PHP build needs IMAP support for this method to function correctly.
Testing the Email Piping
Once the piping is setup, you should try sending a test email to it. If the piping has been setup correctly, then a new ticket should be opened (it can take up to 5 minutes if using the cron method). For testing purposes, you should not use your admin email address to send the message as emails from admin email addresses are expected to be replies to tickets only and won't open new tickets.
Should a ticket not be created when sending in an email, then check in Utilities > Ticket Mail Import Log. If the message was received by WHMCS it will be listed here with the reason why it failed to create a ticket. If the message you sent is not listed here, then the forwarder you setup previously is not working correctly and WHMCS didn't receive the message.
If you get the error message "Ticket ID Not Found" this means you are trying to open a support ticket from your admin email address. Admins can only reply to tickets, not open new ones so submit a ticket from any other email address and it should be accepted.
Spam Control
Email piping raises the problem of Spam sent via email so to combat this, WHMCS has spam control filters which you can use. See the Spam Control article for more info.
Common Problems
If an email has not been piped into the ticket system the first reference point is Utilities > Logs > Ticket Mail Import Log. This shows all the emails processed by the WHMCS email piping process and any errors that may have occurred, explanations of the three most common errors are below:
Ticket ID Not Found
This means you are using an email address assigned to an administrator to send your email. Administrators can only reply to tickets, and not open new ones, hence the Ticket ID not found error message. To test, you must send an email from an email address that is not assigned to an admin in your WHMCS system.
Blocked 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. So as to break the cycle WHMCS did not import the email. By default any new tickets from the offending address will be blocked if 10 emails are received from the same address within a 15 minute period, but this can be customised in the General Settings.
Unregistered Email Address
Seeing this error means you have selected to only allow registered clients to open tickets in this department. You must untick the Clients Only checkbox in Setup > Support Departments > Edit to allow the public to create tickets.
Only Replies Allowed by Email
This entry in the log means that an email was received to the department email address, but the subject did not contain a ticket ID, therefore represents a new ticket rather than a reply to an existing one. Due to the Pipe Replies Only option being enabled in the support department configuration, the email was rejected.
Troubleshooting
If an email has not been piped into the ticket system and it is not listed in the Ticket Mail Import Log (above) then these steps can be followed to identify the cause of the problem. There are different procedures depending upon whether the email forwarder or cron piping method is used.
Unable to communicate with the WHMCS installation
This error occurs when the cron.php file is unable to communicate with the WHMCS installation, its typically occurs when the location of the /crons directory has been customised. The cron.php file will look for the WHMCS directory in the location specified in the /crons/config.php file. So to To resolve this error:
- Open the /crons/config.php file
- Ensure the $whmcspath line is uncommented by removing the preceding // characters.
- Ensure the path specified on the $whmcspath is the full system path to your WHMCS directory. This is the directory which 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 you receive a bounce email containing an error that states local delivery failed like the error shown below when sending an email in to your piped email address then the forwarder entry is not correct and the message is not being sent to the pipe.php script.
pipe to |/home/username/public_html/whmcs/crons/pipe.php generated by support@yourdomain.com local delivery failed
To correct this, first ensure the /crons/pipe.php file is chmod to 755. 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.
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 preventing emails being imported by visiting the pop.php file directly in your browser. eg. http://www.yourdomain.com/crons/pop.php . Below are the explanations of common errors likely to appear:
Could Not Authenticate
This suggests that the SMTP details provided in the required fields are incorrect or possibly intermittent issue between the server on which WHMCS is installed and the mail server.
- First verify the settings under Setup > General Settings > Mail Tab:
- SMTP is chosen in the Mail Type drop down
- The related SMTP fields are correctly filled in with proper values; username (user@email.tld), password, port, connection type.
- Secondly check that the hostname is a FQDN and resolves or check with your system admin/hosting provider for the correct connection details to use for SMTP.
Sender Verify Failed
This is due to the SMTP server requiring a valid account on the server to send from.
Check that the "From Address" under Setup > General Settings > Mail Tab is not blank and a valid address authorised to send mail through the SMTP server is entered. You may need to check your your hosting provider/mail server admin.
Too Many Login Failures
This means WHMCS is being blocked by the mail server because the login details under Setup > Support > Support Departments > Edit (email piping) are incorrect
Double-check the details entered have been input correctly. Once they have been corrected you will need to wait out the block time or if cPanel server, you can whitelist the WHMCS IP in cPhulkd and/or remove the WHMCS IP from the blacklist: http://documentation.cpanel.net/display/ALD/cPHulk+Brute+Force+Protection