How to forward incoming e-mail messages to a script file

cPanel allows you to set up e-mail forwarders that pipe incoming e-mail messages to a script file. You can then program a script file to automatically process the incoming messages however you want.Table of Contents

Configuring a script
Example PHP script
Adding an email forwarder in cPanel

Configuring a script

The following languages are currently supported for e-mail forwarder scripts:

• PHP
• Perl
• Python
• Ruby

When you set up a script, there are two things you must do to make sure the forwarder functions correctly:

1. Use the correct shebang: This depends on the language you are using to write the script. For example, a PHP script file should use the following shebang at the start of the file:#!/usr/bin/php -qThe -q option enables quiet mode, which suppresses HTTP header output. For information about the correct shebangs for other languages, please see this article.
2. Set the correct file permissions for the script: To do this, type the following command, replacing scriptfile with the script filename:
   Copychmod 755 scriptfile

If there are any configuration errors in the forwarder or in the script file, the message sender receives the following message:

Mail delivery failed: returning message to sender

Additionally, this return message may list errors that contain code fragments from the script file. Make sure you test your script file thoroughly before you use it with an active e-mail forwarder!

Example PHP script

The following PHP code sample shows one way to process an incoming e-mail message. The script simply reads the message from stdin, and then stores the message text in a variable named $message:

#!/usr/bin/php -q
<?php

$fd = fopen( "php://stdin", "r" );

$message = "";

while ( !feof( $fd ) )
{
    $message .= fread( $fd, 1024 );
}

fclose( $fd );

// The $message variable now holds the entire message text,
// which you can use for further processing.

?>

Adding an email forwarder in cPanel

To add an e-mail forwarder that redirects to a script file, follow these steps:

1. Log in to cPanel.If you do not know how to log in to your cPanel account, please see this article.
2. Open the Forwarders tool:
   • If you are using the Jupiter theme, on the Tools page, in the Email section, click Forwarders:
   • If you are using the Paper Lantern theme, in the EMAIL section of the cPanel home page, click Forwarders:
     
3. Click Add Forwarder.
4. In the Address to Forward text box, type the account username.
5. In the Domain list box, select the domain for the e-mail account.
6. Click Advanced Options.
7. Click Pipe to a Program, and then in the text box, type the path to the script relative to your home directory. For example, if your script is located at /home/username/scripts/process_mail.php, you would type scripts/process_mail.php.
8. Click Add Forwarder. The forwarder activates immediately.
9. You can test the forwarder by sending an e-mail message to the e-mail address. The corresponding script file should run.