How to check email pipe issue

Issue

The email piping is not working properly

Environment

CloudLinux OS 6(h)/7(h)/8
cPanel/Plesk/DirectAdmin/No panel

Solution

The email piping is a technique of sending an email message as an input to a program rather than appending the message to the mailbox file, allowing for real-time email delivery and handling. Every mail server has its own rules and procedures for mail delivery, making it hard to provide common instructions for configuring an MTA. In this article, we will discuss common email pipe issues on cPanel and Exim as MTA.

Creating a script

While creating a script, in the very first line we have to specify what should be used to interpret it (the shebang line). Suitable values may be:

#!/usr/bin/php -q
#!/usr/local/bin/php -q

If you are using CageFS+PHP Selector, /usr/bin/php and /usr/local/bin/php are used for CGI/CLI binary versions appropriately.

# cat /etc/cl.selector/native.conf 
php=/usr/bin/php
php-cli=/usr/local/bin/php
php.ini=/usr/local/lib/php.ini
php-fpm=/usr/local/sbin/php-fpm

Note the '-q' parameter. This suppresses header output as sometimes php just has to output something. If anything is output by php, the sender will receive a bounceback message containing, among other things, whatever php chose to output. We don't really want this.

Setting up the correct permissions

For mail to be piped to scripts, both the script and the directory it is in should have permissions of 0755.

Settings up email piping

Use the "Pipe to a Program" option to pipe email information to your script:
cpanel user > Forwarders > Add Forwarder button > Advanced Options > choose "Pipe to a Program"
When you use the "Pipe to a Program" option, enter a path that is relative to your home directory. For example, to use the /home/user/script.php script,
enter script.php in the "Pipe to a Program" text box, where user represents your username.

After that, this user will have the following entry in /etc/valiases/domain.com file:

# cat /etc/valiases/domain.com 
[e-mail]: |/home/user/script.php

where domain.com represents your domain name.

Troubleshooting

If you've written your script correctly, set the permissions on it and it's directory fine and created your email filter correctly everything will work.

If in doubt, quickly check that all of the following are correct:
1. You have the correct shebang line
2. Your script reads data from STDIN
3. Your script has permissions of 0755
4. The directory in which your script lives has permissions of 0755
5. Your Forwarder is set up properly. Double check that the path to your script is correct.
6. You have no extraneous carriage returns

7. check the script encoding:

if you used Windows editor, for example, to edit the file with your script, then its LINE ENCODINGS is automatically set to DOS/Windows (\r\n)while the correct is: UNIX (\n)

To fix this, use dos2unix tool, like:

# yum install dos2unix
 # dos2unix my_script.php

Below is a simple php script, which can be used to test email piping:

#!/usr/local/bin/php -q
<?php
/* Read the message from STDIN */
$fd = fopen("php://stdin", "r");
$email = ""; // This will be the variable holding the data.
while (!feof($fd)) {
$email .= fread($fd, 1024);
}
fclose($fd);
/* Saves the data into a file */
$fdw = fopen("/tmp/pipemail.txt", "w+");
fwrite($fdw, $email);
fclose($fdw);
/* Script End */
?>

In order to setup this script, do the following:
1. Create php script with the content provided above inside user's home directory. For example:
/home/user/test.php

2. Make it executable:

# chmod 755 /home/user/test.php

3. Edit /etc/valiases/domain.com file:
[e-mail]: |/home/user/test.php

4. Tail exim_mainlog:

# tail -f /var/log/exim_mainlog

5. Sent an email to [e-mail] and check Exim log.

6. Check /home/user/.cagefs/tmp/pipemail.txt file. If pipemail.txt has email content, then email piping works properly.
If pipemail.txt is empty or you still have issues, please submit a ticket.