You can find our user documentation at docs.cpanel.net.

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

Description

This function restores an account's email forwarders.

Important:

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

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Backup/restore_email_forwarders?backup=alias-example.com.gz&verbose=1&timeout=3600


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


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


Note:

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


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

    /usr/local/cpanel/bin/uapi


 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 alias-example.com.gz.",
		"The system is extracting the archive /home/cpuser/alias-example.com.gz.",
		"The system successfully restored the email forwarders from the alias-example.com.gz backup."
	],
	"warnings": null,
	"metadata": {}
}


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
backup string

Required

The email forwarder file to upload or restore. 

Important:

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

Note:

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:

  • alias-example.com
  • alias-example.com.gz

    Note:

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

alias-example.com.gz

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.
1 
timeout integer

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

This parameter defaults 7200.

An integer value. 3600 

Returns

ReturnTypeDescriptionPossible valuesExample
log_idstring

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.

2019-08-13T15:10:07Z.1

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

/home/cpuser/.cpanel/logs/restore-email-filters/2019-09-11T18:30:49Z.1.log

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 'aliases-example.com.gz' backup.