UAPI Functions - Email::set_default_address

Description

This function configures a default (catchall) email address.

Examples 

 cPanel or Webmail Session URL

https://hostname.example.com:2083/cpsess##########/execute/Email/set_default_address?domain=example.com&fwdopt=fwd&fwdemail=admin%40example.com

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// Send unroutable mail to admin@example.com
$default_address = $cpanel->uapi(
    'Email', 'set_default_address',
    array(
        'domain'     => 'example.com',
        'fwdopt'     => 'fwd',
        'fwdemail'   => 'admin@example.com',
         )
);
  
// Send unroutable mail to script.pl
$default_address = $cpanel->uapi(
    'Email', 'set_default_address',
    array(
        'domain'     => 'example.com',
        'fwdopt'     => 'pipe',
        'pipefwd'    => 'script.pl',
         )
);
 
// Delete unroutable mail.
$default_address = $cpanel->uapi(
    'Email', 'set_default_address',
    array(
        'domain'     => 'example.com',
        'fwdopt'     => 'blackhole',
         )
);
  
// Bounce unroutable mail.
$default_address = $cpanel->uapi(
    'Email', 'set_default_address',
    array(
        'domain'     => 'example.com',
        'fwdopt'     => 'fail',
        'failmsgs'   => 'Nobody\'s home.',
         )
);

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Send unroutable mail to admin@example.com
my $default_address = $cpliveapi->uapi(
    'Email', 'set_default_address',
    {
        'domain'     => 'example.com',
        'fwdopt'     => 'fwd',
        'fwdemail'   => 'admin@example.com',
    }
);
  
# Send unroutable mail to script.pl
my $default_address = $cpliveapi->uapi(
    'Email', 'set_default_address',
    {
        'domain'     => 'example.com',
        'fwdopt'     => 'pipe',
        'pipefwd'    => 'script.pl',
    }
);
 
# Delete unroutable mail.
my $default_address = $cpliveapi->uapi(
    'Email', 'set_default_address',
    {
        'domain'     => 'example.com',
        'fwdopt'     => 'blackhole',
    }
);
 
# Bounce unroutable mail.
my $default_address = $cpliveapi->uapi(
    'Email', 'set_default_address',
    {
        'domain'     => 'example.com',
        'fwdopt'     => 'fail',
        'failmsgs'   => 'Nobody\'s home.',
    }
);

 cPanel Template Toolkit
<!-- Send unroutable mail to admin@example.com -->
<!-- Get a hash of all the data, then display the dest value. -->
[% data = execute( 'Email', 'set_default_address', { 'domain' => 'example.com', 'fwdopt' => 'fwd', 'fwdemail' => 'admin@example.com', } ); %]
[% FOREACH q = data.dest %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'set_default_address', { 'domain' => 'example.com', 'fwdopt' => 'fwd', 'fwdemail' => 'admin@example.com', }).data.dest %]
  
 
 
<!-- Send unroutable mail to script.pl -->
<!-- Get a hash of all the data, then display the dest value. -->
[% data = execute( 'Email', 'set_default_address', { 'domain' => 'example.com', 'fwdopt' => 'pipe', 'pipefwd' => 'script.pl', } ); %]
[% FOREACH q = data.dest %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'set_default_address', { 'domain' => 'example.com', 'fwdopt' => 'pipe', 'pipefwd' => 'script.pl', }).data.dest %]
 
 
<!-- Delete unroutable mail. -->
<!-- Get a hash of all the data, then display the dest value. -->
[% data = execute( 'Email', 'set_default_address', { 'domain' => 'example.com', 'fwdopt' => 'blackhole' } ); %]
[% FOREACH q = data.dest %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'set_default_address', { 'domain' => 'example.com', 'fwdopt' => 'blackhole' }).data.dest %]
 
 
 
<!-- Bounce unroutable mail. -->
<!-- Get a hash of all the data, then display the dest value. -->
[% data = execute( 'Email', 'set_default_address', { 'domain' => 'example.com', 'fwdopt' => 'fail', 'failmsgs' => 'Nobody\'s home.' } ); %]
[% FOREACH q = data.dest %]
     <p>
         [% q %]
     </p>
[% END %]
  
<!-- Get only the forwarded address. -->
[% execute('Email', 'set_default_address', { 'domain' => 'example.com', 'fwdopt' => 'fail', 'failmsgs' => 'Nobo

 Command Line
uapi --user=username Email set_default_address domain=example.com fwdopt=fwd fwdemail=admin%40example.com
uapi --user=username Email set_default_address domain=example.com fwdopt=pipe pipefwd=script.pl
uapi --user=username Email set_default_address domain=example.com fwdopt=blackhole
uapi --user=username Email set_default_address domain=example.com fwdopt=fail failmsgs="Nobody is home."

 

Notes:

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

 Output (JSON)
{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": [
    {
      "domain": "example.com",
      "dest": "admin@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

The domain.

This parameter defaults to the cPanel account's main domain.

A valid domain on the account.

example.com 

fwdopt

string

Required

The method to use to handle unroutable mail.
  • fwd — Forward messages to the fwdemailparameter's address.
  • fail — Bounce messages back to the sender, and include the failmsgs parameter's failure message.
  • blackhole — Send messages to the/dev/null/ directory. This method does notgenerate a failure notice. 
  • pipe — Pipe mail to the pipefwd parameter's application.

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.

 admin@example.com 

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 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 pipe method 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

data

 array of hashes 

An array of hashes of forwarder information.

This array of hashes includes the domain and destreturns.

 

domain

string

The domain.

The function returns this value in the data hash.

A valid domain on the account.

example.com 

dest

string

 The destination to which the system sends unroutable mail. 

The function returns this value in the data hash.
  • 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.

 admin@example.com 

 

  • 10 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....