We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

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

Description

This function restores an account's email filters.

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_filters?backup=filter-info.username.yaml.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 filters from the backup file.
$Backup_restore_email_filters = $cpanel->uapi(
    'Backup', 'restore_email_filters',
    array(
		'backup'	=> 'filter-info.username.yaml.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 filters from the backup file.
my $Backup_restore_email_filters = $cpliveapi->uapi(
    'Backup', 'restore_email_filters',
    {
        'backup'   => 'filter-info.username.yaml.gz',	
		'verbose'  => '1',
        'timeout'  => '3600',
    }
);


Note:

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

 Command Line
uapi --user=username Backup restore_email_filters backup=filter-info.username.yaml.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-filters/2019-09-11T18:30:49Z.1.log"
	},
	"status": 1,
	"errors": null,
	"messages": [
		"No virus detected in upload “No virus detected in upload “filter_info.user.yaml.gz”.",
		"The system is extracting the archive “/home/cpuser/filter-info.user.yaml.gz”.",
		"The system successfully restored the email filters from the “filter-info.user.yaml.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 filter file to upload or restore. 

Important:

  • You can only restore email filter files that already exist on the server.
  • To upload an email filter 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 file in one of the following formats:

  • filter_info.username.yaml
  • filter_info.username.yaml.gz

    Note:

    username represents the cPanel user's username.

filter_info.username.yaml.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 filepath.

/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 “filter-info.user.yaml.gz' backup.