cPanel API 2 Functions - Email::addforward

Warning:

The cPanel API 2 system is deprecated. We strongly recommend that you use UAPI instead of cPanel API 2.

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.

Important:

When you disable the Receive Mail role, the system disables this function.

Examples

WHM API (JSON)

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="example.com"&email="forwardme@example.com"&fwdopt="fwd"&fwdemail="fwdtome@example.com"

Note:

For more information, read our Calls from the WHM API documentation.

LiveAPI PHP Class

$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',
    )
);

Note:

For more information, read our Guide to the LiveAPI System.

LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# Forward mail from forwardme@example.com to fwdtome@example.com
my $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.pl
my $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',
    }
);

Note:

For more information, read our Guide to the LiveAPI System.

cPanel Tag System (deprecated)

Warnings:

cPanel tags are deprecated . We strongly recommend that you only use the LiveAPI system to call the cPanel APIs. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI .
cPanel API 2 calls that use cPanel tags vary in code syntax and in their output.
For more information, read our Deprecated cPanel Tag Usage documentation.

Command Line

cpapi2 --user=username Email addforward domain=example.com email=forwardme%40example.com fwdopt=fwd fwdemail=fwdtome%40example.com

Note:

For more information and additional output options, read our Guide to cPanel API 2 documentation or run the cpapi2 --help command.

Output (JSON)

{
  "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 (cPanel >> 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`
`email`	string	Required The email address to forward.	An email address on the account.	`forwardme@example.com`
`fwdopt`	string	Required The method to use to handle the email address's mail.	`fwd` — Forward messages to the addressed in the `fwdemail` parameter. `fail` — Bounce messages back to the sender. This parameter also uses the failure message defined in the `failmsgs` parameter. `blackhole` — Send messages to the `/dev/null/` directory. This method does not generate a failure notice. `pipe` — Pipe mail to the application defined by the `pipefwd` parameter. `system` — Forward messages to the `fwdsystem` system account.	`fwd`
`fwdemail`	string	The email address to which the system forwards messages. Note: You must use this parameter if you used the `fwd` method for the `fwdopt` parameter. You can pass multiple addresses to this parameter as a comma-separated list.	A valid email address.	`fwdtome@example.com`
`fwdsystem`	string	The system user to whom the system forwards messages. Note: You must use this parameter if you used the `system` method for the `fwdopt` parameter.	An account on the system. For example, a reseller or cPanel account's name.	`user`
`failmsgs`	string	The failure message for the message's sender. Note: Use this parameter if you used the `fail` method for the `fwdopt` parameter. This parameter defaults to `No such person at this address.`	A valid string.	`Nobody's home.`
`pipefwd`	string	The application to which the system pipes messages. Note: You must use this parameter if you used the `pipe` method for the `fwdopt` 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`
`email`	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.	An email address — The system forwards mail to this address. `:fail:` — The system bounces mail back to the sender and sends a failure message. `:blackhole:` — The system deletes mail without a failure message. The path to an application — The system pipes mail to this application. A username — The system forwards mail to this system account.	`forwardtome@example.com`
`reason`	string	A reason for failure. Note: This function only returns a `reason` value if it failed.	A string that describes the error.	`This is an error message.`
`result`	Boolean	Whether the function succeeded.	`1` — The function succeeded. `0` — The function failed.	`1`