You can find our user documentation at

Check out our new API beta site!

Child pages
  • UAPI Functions - Backup::restore_email_forwarders
Skip to end of metadata
Go to start of metadata


This function restores an account's email forwarders.


In cPanel & WHM version 86 and later, when you disable the Receive Mail role, the system disables this function.


 cPanel or Webmail Session URL


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.
// Restore the user's email forwarders from the backup file.
$Backup_restore_email_forwarders = $cpanel->uapi(
    'Backup', 'restore_email_forwarders',
		'backup'	=> '',
        'verbose'   => '1',
        'timeout'   => '3600',


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.
# Restore the user's email forwarders from the backup file.
my $Backup_restore_email_forwarders = $cpliveapi->uapi(
    'Backup', 'restore_email_forwarders',
        'backup'   => '',	
		'verbose'  => '1',
        'timeout'  => '3600',


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

 Command Line
uapi --user=username Backup restore_email_forwarders backup=alias-domain.gz verbose=1 timeout=3600


  • 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. 
  • If you run CloudLinux™, you must use the full path of the uapi command:


 Output (JSON)
	"data": {
		"log_id": "2019-10-03T18:30:49Z.1",
		"log_path": "/home/cpuser/.cpanel/logs/restore-email-forwarders/2019-09-11T18:30:49Z.1.log"
	"status": 1,
	"errors": null,
	"messages": [
		"No virus detected in upload",
		"The system is extracting the archive /home/cpuser/",
		"The system successfully restored the email forwarders from the backup."
	"warnings": null,
	"metadata": {}


Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.


ParameterTypeDescriptionPossible valuesExample
backup string


The email forwarder file to upload or restore. 


  • You can only restore email forwarder files that already exist on the server.
  • To upload an email forwarder file, you must pass this parameter in a multipart form-data structure. For more information about this structure, read Mozilla's POST Method documentation.


To restore multiple email filter files, increment the parameter name. For example: backup-1 backup-2backup-3.

A valid file path, in one of the following formats:



    • represents the domain.
    • The cPanel user must own the domain.

verbose Boolean

Whether to return additional information from the /home/cpuser/.cpanel/logs/restore-email-filters log files.

This parameter defaults to 0.

  • 1 — Return.
  • 0  – Don't return.
timeout integer

The time to attempt to restore the filter, in seconds.

This parameter defaults 7200.

An integer value. 3600 


ReturnTypeDescriptionPossible valuesExample

The log file's restoration identification (ID). 

The system uses the backup restoration's date to create this ID.

The backup restoration date in YYYY-MM-DDTHH:mm:SS.rev human-readable format, where:

  • YYYY represents the year.
  • MM represents the month.
  • DD represents the date.
  • HH represents the hour.
  • mm represents the minute.
  • SS represents the second.
  • rev represents the log's revision during the current backup restoration.


log_pathstringThe log file where the system recorded the backup restoration.A valid file path.


messagesarray of stringsAn array of statements about the database's restoration.An array of strings that describe the restoration's status. 

The system successfully restored the email filters from the '' backup.