Knowledge Base

How to forward incoming email messages to a script file

cPanel allows you to set up email forwarders that pipe an incoming email message to a script file. You can program the script file to automatically process the incoming message however you want.

Configuring a script

The following languages are currently supported for email 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. 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 SCRIPT with the script filename:

    chmod 755 SCRIPT

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 email forwarder!

Example PHP script

The following PHP code sample shows one way to read an incoming email 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 email 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.
  3. Click Add Forwarder.
  4. In the Address to Forward text box, type the account address.
  5. Click Advanced Options.
  6. 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.
  7. Click Add Forwarder. The forwarder activates immediately.
  8. You can test the forwarder by sending an email message to the email address. The corresponding script file should run.