Creating an email pipe using cPanel on the x3 theme is a little less intuitive than expected, however, once the tool is fully undertood making use of it is very simple.
Let's start by looking at what an email pipe is first. When an email comes into the server, the mail transit agent looks up the destination address to determine how to deliver the message. A majority of messages are simply delivered to the mail folder within your account for you to view via webmail or a standalone email client such as Outlook, ThunderBird, or Mac Mail. Piping follows the exact same process up until the last step, where the mail transit agent passes the contents of the email to a script for handling via a pipe rather than simply delivering the message to a folder within the account. The syntax for a pipe is simply, "|" followed by the script that you wish to handle the data.
A sample pipe may look as follows: "| /usr/bin/php -q /home/acctname/script-to-handle-pipe.php" and I will use this pipe as an example to illustrate how to use this information to create a piped forwarder in cPanel. In this article "acctname" will represent your account name.
cPanel, as of the x3 theme, unfortunately does not follow the standard syntax for pipe creation which can be confusing, especially for one not experienced with this feature. We'll first start by getting you to the Forwarders section of cPanel.
Accessing the "Forwarders" feature in your cPanel Account
- Log in to your cPanel. (How do I log into my cPanel?)
- On the left side of your Control Panel you will see a "Find" box which can make finding the utility you need to use very easy. You can simply type "Forwarders" into this box or you can browse to the "Mail" group and find the "Forwarders" feature.
- Once in the "Forwarders" section of cPanel you will see a list of the forwarders that you have already created and will have the option to add new forwarders as well.
Creating an Email Pipe via the "Forwarders" feature in your cPanel Account
- In the "Forwarders" section of your cPanel from step 3 above, click "Add Forwarder".
- Enter the email address that you wish to have piped and choose the pertinent domain. For example I am using "firstname.lastname@example.org" as seen here.
- Click "Advanced Options »" to view the option to create an email pipe instead of a standard forwarder.
- Select the second option "Pipe to a Program:".
cPanel chooses to handle creating the pipe for you and simply needs to know which script you would like the data handed to. Using the original example "| /usr/bin/php -q /home/acctname/script-to-handle-pipe.php" from above, we will show you how to create the appropriate pipe.
The script that you are going to have handle this pipe is "/home/acctname/script-to-handle-pipe.php" and cPanel only needs the information following your account name. cPanel uses a little house icon followed by a slash to represent "/home/youraccountname/" which indicates that all you need to enter into the box is the rest of the path from our example, "script-to-handle-pipe.php".
The pipe, when entered into the "Forwarders" section of your cPanel for this example would look like this.
There is one additional step that you must take, due to the way cPanel handles email pipe creation, to ensure that your pipe will work properly.
Checking and Modifying your PHP script for cPanel Piping
Due to cPanel handling the pipe creation itself, you do not have the option in the cPanel interface to specify which binary you would like to use to process your file. Fret not, as specifying which binary to use for processing your file requires only a simple one-line addition to the top of your php script. This is accomplished using what is called a "shebang".
The syntax for a shebang is simple, it's simply a pound sign and an exclamation mark followed by the binary you wish to handle the file and, for this specific example, would look like "#!/usr/bin/php -q".
Using your favorite editor or the built in cPanel File Manager you would simply open the script that you wish to pipe to, and check for a shebang. This is always going to be on the very first line, so if you do not see it - you can simply append it to the beginning of the file.
The following shebangs are valid on our servers for PHP:
For PHP 5.2.x the shebang would be "#!/usr/bin/php"
For PHP 5.3.x the shebang would be "#!/usr/bin/php53"
You may wish to pass additional options to the PHP interpreter, such as the "-q" option to suppress headers. You can see from the example in this article that we are using the "-q" option simply by appending a space followed by the option to the shebang: "#!/usr/bin/php -q"
Testing your new Piped Forwarder
After configuring a piped forwarder, it's always a good idea to test it to ensure it's working as expected. If the pipe is working properly you should not receive a return email containing an error message. Should you receive an error message, the first thing you should do is follow the steps from the above section "Checking and Modifying your PHP script for cPanel Piping".
If you've made sure that the file has a shebang and the pipe is still not working, feel free to contact our support department and we can give it a quick look. Keep in mind that your script and it's configuration is outside of our support scope so we cannot troubleshoot the issue further if it is determined the issue is with the script itself and not the forwarder or the server.