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

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 -q
    The -q option enables quiet mode, which suppresses HTTP header output.
  2. Set the correct file permissions for the script: To do this, type the following command, replacing scriptfile with the script filename:
    chmod 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

$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.
  2. In the EMAIL section of the cPanel home screen, click Forwarders:cPanel - Email - Forwarders icon
  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.