Description
This function creates an email forwarder.
Warning:
We strongly recommend that you use the following UAPI function instead of this function:
-
Email::add_forwarder— This function creates an email forwarder.
Examples
https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=addforward&domain=
$cpanel = new CPANEL(); // Connect to cPanel - only do this once. // Forward mail from forwardme@example.com to fwdtome@example.com$add_mail_forwarder = $cpanel->api2( 'Email', 'addforward', array( 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'fwd', 'fwdemail' => 'fwdtome@example.com', ) ); // Bounce mail to forwardme@example.com with a message.$add_mail_forwarder = $cpanel->api2( 'Email', 'addforward', array( 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'fail', 'failmsgs' => 'Nobody's home.', ));// Delete mail that forwardme@example.com receives.$add_mail_forwarder = $cpanel->api2( 'Email', 'addforward', array( 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'blackhole', )); // Pipe forwardme@example.com's mail to script.pl$add_mail_forwarder = $cpanel->api2( 'Email', 'addforward', array( 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'pipe', 'pipefwd' => 'script.pl', )); // Forward forwardme@example.com's mail to a system account.$add_mail_forwarder = $cpanel->api2( 'Email', 'addforward', array( 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'system', 'fwdsystem' => 'user', ));my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once. # Forward mail from forwardme@example.com to fwdtome@example.commy $add_mail_forwarder = $cpliveapi->api2( 'Email', 'addforward', { 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'fwd', 'fwdemail' => 'fwdtome@example.com', }); # Bounce mail to forwardme@example.com with a message.my $add_mail_forwarder = $cpliveapi->api2( 'Email', 'addforward', { 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'fail', 'failmsgs' => 'Nobody's home.', });# Delete mail that forwardme@example.com receives.my $add_mail_forwarder = $cpliveapi->api2( 'Email', 'addforward', { 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'blackhole', }); # Pipe forwardme@example.com's mail to script.plmy $add_mail_forwarder = $cpliveapi->api2( 'Email', 'addforward', { 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'pipe', 'pipefwd' => 'script.pl', });# Forward forwardme@example.com's mail to a system account.my $add_mail_forwarder = $cpliveapi->api2( 'Email', 'addforward', { 'domain' => 'example.com', 'email' => 'forwardme@example.com', 'fwdopt' => 'system', 'fwdsystem' => 'user', });Warning:
In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs.
cPanel API 2 calls that use cPanel tags vary widely in code syntax and in their output. For more information, read our Deprecated cPanel Tag Usage documentation. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.
cpapi2 --user=username Email addforward domain=example.com email=forwardme%40example.com fwdopt=fwd fwdemail=fwdtome%40example.com
{ "cpanelresult": { "apiversion": 2, "func": "addforward", "data": [ { "email": "forwardme@example.com", "domain": "example.com", "forward": "fwdtome@example.com" } ], "event": { "result": 1 }, "module": "Email" }}Note:
Use cPanel's API Shell interface (Home >> Advanced >> API Shell) to directly test cPanel API calls.
Parameters
|
Parameter |
Type |
Description |
Possible values |
Example |
|
domain |
string |
Required The domain. |
A valid domain on the account. |
example.com |
|
|
string |
Required The email address to forward. |
An email address on the account. Note: You can pass multiple addresses to this parameter as a comma-separated list. |
forwardme@example.com |
|
fwdopt |
string |
Required The method to use to handle the email address's mail. |
|
fwd |
|
fwdemail |
string |
The email address to which the system forwards messages. Note: Use this parameter if you used the fwdmethod for thefwdopt parameter.
|
A valid email address. |
fwdtome@example.com |
|
fwdsystem |
string |
The system user to whom the system forwards messages. Note: Use this parameter if you used the systemmethod for thefwdopt parameter. |
An account on the system. |
user |
|
failmsgs |
string |
The failure message for the message's sender. This parameter defaults to No such person at this address. Note: Use this parameter if you used the failmethod for thefwdopt parameter. |
A valid string. |
Nobody's home. |
|
pipefwd |
string |
The application to which the system pipes messages. Note: Use this parameter if you used the pipemethod for thefwdopt parameter. |
The location of a program or script, relative to the account's home directory. |
mailscript.pl |
Returns
|
Return |
Type |
Description |
Possible values |
Example |
|
domain |
string |
The domain. |
A valid domain on the account. |
example.com |
|
|
string |
The email address. |
An email address on the account. |
forwardme@example.com |
|
forward |
string |
The method that the system will use to handle the address's email. |
|
forwardtome@example.com |
|
reason |
string |
A reason for failure. Note: This function only returns a reasonvalue if it failed. |
A string that describes the error. |
This is an error message. |
|
result |
Boolean |
Whether the function succeeded. |
|
1 |