Difference between revisions of "Email Piping"
m (→POP3 Import Method) |
|||
(30 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
− | Email piping | + | 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. |
− | |||
− | |||
<div class="docs-alert-info"> | <div class="docs-alert-info"> | ||
− | + | * For a tutorial on setting up email piping for cPanel, see [https://help.whmcs.com/m/setup/l/1112149-configuring-email-piping Configuring Email Piping]. | |
− | + | * For steps to configure email piping and Google Apps, see [[Email Piping: Google Apps]]. | |
</div> | </div> | ||
− | == | + | ==Department Setup== |
+ | |||
+ | Before you can set up email piping, you must configure your support departments at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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. | ||
− | [[File:Videotutorial.png|center|link=https:// | + | ==Email Piping Methods== |
+ | |||
+ | [[File:Videotutorial.png|center|link=https://youtu.be/uJLvEfLUXIc|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. | ||
− | <div class="docs-alert- | + | <div class="docs-alert-info"> |
+ | If you have customized the location of the crons directory, adjust the file path examples below accordingly. | ||
+ | </div> | ||
− | + | ===Set Up the Forwarder Method=== | |
− | To | + | [[File:Forwarder_config.png|thumb|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''' | '''Sample Forwarder Command''' | ||
Line 23: | Line 34: | ||
</nowiki></div> | </nowiki></div> | ||
− | You can find a copy | + | You can find a copy-and-paste-ready command with the specific path for your setup. Navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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. |
− | <div class="docs-alert-info">< | + | <div class="docs-alert-info"> |
+ | The <tt>pipe.php</tt> file requires <tt>755</tt> permissions to function properly. | ||
+ | <br /> | ||
+ | If using DirectAdmin, you must enter the command enclosed in quotes (<tt>""</tt>) for the system to accept it. | ||
+ | </div> | ||
− | == | + | ===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 (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[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|Common Problems]] and [[#Troubleshooting|Troubleshooting]] sections. | |
− | ==Testing | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | If you get the error message | ||
==Spam Control== | ==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== | ==Common Problems== | ||
− | If an email | + | If the system didn't pipe an email into the ticket system, check the '''Ticket Mail Import Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[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 [[Support_Tab#Ticket_Reply_Email_Limit|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 (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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.=== | ||
− | = | + | <div class="docs-alert-info"> |
− | + | <strong>RFC 3834</strong><br /> | |
− | + | In WHMCS 8.1 and later, the system sends support emails with RFC 3834-compliant headers by default. | |
− | == | + | * You can disable this at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' in the '''[[Mail Tab|Mail]]''' tab. |
− | + | * Regardless of your settings, WHMCS will not accept email that email that contains the <tt>Auto-Submitted</tt> header via email piping or email importing. | |
− | + | </div> | |
− | |||
− | |||
− | + | This error message indicates that an email contained the <tt>Auto-Submitted</tt> 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 [https://datatracker.ietf.org/doc/html/rfc3834 RFC 3834] email specification. | |
− | This | + | |
+ | Prior to WHMCS 8.3, this was ''Prevented an Auto Responder from Opening a Ticket''. | ||
==Troubleshooting== | ==Troubleshooting== | ||
− | If an email | + | 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==== | ====Unable to communicate with the WHMCS installation==== | ||
− | This error occurs when the cron.php file is 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 <tt>cron.php</tt> file will look for the WHMCS directory in the location in the <tt>/crons/config.php</tt> file. To resolve this error: |
− | + | # Open the <tt>/crons/config.php</tt> file. | |
− | + | # Uncomment the <tt>$whmcspath</tt> line by removing the preceding <tt>//</tt> characters. | |
− | + | # Ensure the <tt>$whmcspath</tt> path is the full system path to your WHMCS directory. This is the directory that contains the <tt>init.php</tt> and <tt>clientarea.php</tt> files. | |
− | + | ||
+ | An example of a correctly-completed file is [[Cron_Job_Issues#Unable_to_communicate_with_the_WHMCS_installation|available on this page]]. | ||
===Email Forwarder Method=== | ===Email Forwarder Method=== | ||
====Local Delivery Failed Error Message==== | ====Local Delivery Failed Error Message==== | ||
− | If | + | 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 <tt>pipe.php</tt> script. |
pipe to |/home/username/public_html/whmcs/crons/pipe.php | pipe to |/home/username/public_html/whmcs/crons/pipe.php | ||
− | generated by support@ | + | generated by support@example.com |
local delivery failed | local delivery failed | ||
− | To correct this, | + | To correct this, ensure the <tt>/crons/pipe.php</tt> file uses <tt>755</tt> permissions. Then, try the following variations of the email forwarder command: |
<div class="source-cli"><nowiki> | <div class="source-cli"><nowiki> | ||
Line 97: | Line 122: | ||
====Why is email piping with Direct Admin sending the email twice?==== | ====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. | + | To fix this problem you need to remove or comment out "unseen" from your <tt>exim.conf</tt> file. |
− | + | For example: | |
virtual_aliases_nostar: | virtual_aliases_nostar: | ||
Line 116: | Line 141: | ||
===Cron Piping Method=== | ===Cron Piping Method=== | ||
− | When using the Cron Piping | + | 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 <tt>configuration.php</tt> file: |
+ | |||
+ | <div class="source-cli"><nowiki> | ||
+ | $pop_cron_debug = true; | ||
+ | </nowiki></div> | ||
+ | |||
+ | Next, visit the <tt>pop.php</tt> file directly in your browser (for example, <tt>http://www.example.com/crons/pop.php</tt>). You may encounter the common errors below: | ||
====Could Not Authenticate==== | ====Could Not Authenticate==== | ||
− | This | + | 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: | |
− | |||
− | |||
− | + | # Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Support Departments]]''' or, prior to WHMCS 8.0, '''Setup > Support > Support Departments'''. | |
+ | # Edit the department that the notification email referenced. | ||
+ | # Verify that the POP3 settings use correct values (username (<tt>user@example.com</tt>), password, and port), | ||
+ | # 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. | ||
+ | # Click '''Save Changes'''. | ||
====Sender Verify Failed==== | ====Sender Verify Failed==== | ||
− | This | + | This error indicates that the SMTP server requires a valid account on the server to send from. |
− | Check that the | + | Check that the '''From Address''' in the '''[[Mail Tab|Mail]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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==== | ====Too Many Login Failures==== | ||
− | This | + | This error indicates that the mail server is blocking WHMCS because the email piping login details under '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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 [https://docs.cpanel.net/whm/security-center/cphulk-brute-force-protection/|cPanel's documentation]. | ||
+ | |||
+ | ====WHMCS Pop Cron Did Not Run==== | ||
+ | This error indicates a problem with the [[#POP3_Import_Method|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 [https://help.whmcs.com/m/support_tools/l/1103793-whmcs-pop-cron-did-not-run-email in this help guide]. | ||
− | + | After you have applied one of these resolutions, the system will stop sending the warning email. |
Latest revision as of 21:32, 1 March 2023
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.
- For a tutorial on setting up email piping for cPanel, see Configuring Email Piping.
- For steps to configure email piping and Google Apps, see Email Piping: Google Apps.
Contents
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
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
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
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:
- Open the /crons/config.php file.
- Uncomment the $whmcspath line by removing the preceding // characters.
- 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:
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:
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:
- Go to Configuration () > System Settings > Support Departments or, prior to WHMCS 8.0, Setup > Support > Support Departments.
- Edit the department that the notification email referenced.
- Verify that the POP3 settings use correct values (username (user@example.com), password, and port),
- 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.
- 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.