Page tree
Skip to end of metadata
Go to start of metadata

 

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

Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

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

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.
 
# 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.',
    }
);

Note:

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

 

 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' => 'Nobody\'s home.' }).data.dest %]

Note:

For more information, read our Guide to Template Toolkit documentation. 

 

 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.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • We introduced this functionality in cPanel & WHM version 56.

 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 (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

   

Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

The domain.

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

A valid domain on the account.

example.com
fwdoptstring

Required

The method to use to handle unroutable mail.

  • fwd — Forward messages to the fwdemail parameter'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 not generate a failure notice.
  • pipe — Pipe mail to the pipefwd parameter's application.
fwd
fwdemailstring

The email address to which the system forwards messages.

Note:

Use this parameter if you used the fwd method for the fwdopt parameter. 

A valid email address.admin@example.com
failmsgsstring

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\'s home.
pipefwdstring

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

ReturnTypeDescriptionPossible valuesExample
dataarray of hashesAn array of hashes of forwarder information.This array of hashes includes the domain and dest returns. 

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