UAPI Functions - Email::add_forwarder

Description

This function creates an email forwarder.

Examples 

 cPanel or Webmail Session URL

https://hostname.example.com:2083/cpsess##########/execute/Email/add_forwarder?domain=example.com&email=user%40example.com&fwdopt=fwd&fwdemail=fwdtome%40example.com

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// Forward user@example.com's mail to fwdtome@example.com
$add_forwarder = $cpanel->uapi(
    'Email', 'add_forwarder',
    array(
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'fwd',
        'fwdemail'   => 'fwdtome@example.com',
         )
);
  
// Pipe user@example.com's mail to script.pl
$add_forwarder = $cpanel->uapi(
    'Email', 'add_forwarder',
    array(
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'pipe',
        'pipefwd'    => 'script.pl',
         )
);
 
// Forward user@example.com's mail to a system account.
$add_forwarder = $cpanel->uapi(
    'Email', 'add_forwarder',
    array(
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'system',
        'fwdsystem'  => 'user',
         )
);
 
 
// Delete user@example.com's mail.
$add_forwarder = $cpanel->uapi(
    'Email', 'add_forwarder',
    array(
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'blackhole',
         )
);
  
// Bounce user@example.com's mail.
$add_forwarder = $cpanel->uapi(
    'Email', 'add_forwarder',
    array(
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'fail',
        'failmsgs'   => 'Nobody home.',
         )
);

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Forward user@example.com's mail to fwdtome@example.com
my $add_forwarder = $cpliveapi->uapi(
    'Email', 'add_forwarder',
    {
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'fwd',
        'fwdemail'   => 'fwdtome@example.com',
    }
);
  
# Pipe user@example.com's mail to script.pl
my $add_forwarder = $cpliveapi->uapi(
    'Email', 'add_forwarder',
    {
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'pipe',
        'pipefwd'    => 'script.pl',
    }
);
 
# Forward user@example.com's mail to a system account.
my $add_forwarder = $cpliveapi->uapi(
    'Email', 'add_forwarder',
    {
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'system',
        'fwdsystem'  => 'user',
    }
);
 
# Delete user@example.com's mail.
my $add_forwarder = $cpliveapi->uapi(
    'Email', 'add_forwarder',
    {
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'blackhole',
    }
);
 
# Bounce user@example.com's mail.
my $add_forwarder = $cpliveapi->uapi(
    'Email', 'add_forwarder',
    {
        'domain'     => 'example.com',
        'email'      => 'user@example.com',
        'fwdopt'     => 'fail',
        'failmsgs'   => 'Nobody home.',
    }
);

 cPanel Template Toolkit
<!-- Forward user@example.com's mail to fwdtome@example.com -->
<!-- Get a hash of all the data, then display the forwarded email. -->
[% data = execute( 'Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'fwd', 'fwdemail' => 'fwdtome@example.com', } ); %]
[% FOREACH q = data.forward %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'fwd', 'fwdemail' => 'fwdtome@example.com', }).data.forward %]
  
 
 
<!-- Pipe user@example.com's mail to script.pl -->
<!-- Get a hash of all the data, then display the forwarded email. -->
[% data = execute( 'Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'pipe', 'pipefwd' => 'script.pl', } ); %]
[% FOREACH q = data.forward %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'pipe', 'pipefwd' => 'script.pl', }).data.forward %]
 
 
 
<!-- Forward user@example.com's mail to a system account. -->
<!-- Get a hash of all the data, then display the forwarded email. -->
[% data = execute( 'Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'system', 'fwdsystem' => 'user', } ); %]
[% FOREACH q = data.forward %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'system', 'fwdsystem' => 'user', }).data.forward %]
 
 
 
<!-- Delete user@example.com's mail. -->
<!-- Get a hash of all the data, then display the forwarded email. -->
[% data = execute( 'Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'blackhole' } ); %]
[% FOREACH q = data.forward %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'blackhole' }).data.forward %]
 
 
 
<!-- Bounce user@example.com's mail. -->
<!-- Get a hash of all the data, then display the forwarded email. -->
[% data = execute( 'Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'fail', 'failmsgs' => 'Nobody home.' } ); %]
[% FOREACH q = data.forward %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'add_forwarder', { 'domain' => 'example.com', 'email' => 'user@example.com', 'fwdopt' => 'fail', 'failmsgs' => 'Nobody home.' }).data.forward %]


 Command Line
uapi --user=username Email add_forwarder domain=example.com email=user%40example.com fwdopt=fwd fwdemail=fwdtome%40example.com

 

Notes:

  • You must URI-encode values.
  • username represents your account-level username.

 Output (JSON)
{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": [
    {
      "email": "user@example.com",
      "domain": "example.com",
      "forward": "fwdtome@example.com"
    }
  ],
  "metadata": {
    "transformed": 1
  }
}

 

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 

email

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 — Forward messages to the fwdemailparameter's address.
  • fail — Bounce messages back to the sender, and include the failmsgsparameter's failure message.
  • blackhole — Send messages to the/dev/null/ directory. This method doesnot generate a failure notice.
  • pipe — Pipe mail to the pipefwdparameter's application.
  • system — Forward messages to thefwdsystem system account.

fwd

fwdemail

string

The email address to which the system forwards messages.

Note:

Use this parameter if you used the fwd method 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 system method for the fwdopt parameter. 

An account on the system (for example, the reseller's account name or the cPanel account name).

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 fail method for the fwdopt parameter. 

A valid string.

Nobody home.

pipefwd

 string 

The application to which the system pipes messages.

Note:

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.

user@example.com

forward

string

 The method that the system will use to handle the address's mail. 
  • 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.

 fwdtome@example.com 

 

 

  • 0 Users Found This Useful
Was this answer helpful?

Related Articles

The cPanel Interface

For  cPanel  &  WHM  version  58 Overview The cPanel interface is...

User Preferences

For cPanel & WHM version 58 Overview This document outlines how to access your cPanel...

Manage External Authentications

For cPanel & WHM version 58 Overview Manage credentials Additional documentation...

What is cPanelID?

In This Article:  Overview ServicesHow to get a cPanelID cPanelID External...

Guide to cPanel Interface Customization - cPanel Style Development

Introduction You can develop custom styles that modify the appearance of the cPanel interface....