Our documentation is getting an overhaul! We would like your input! Click here to take a look at the beta launch of our new documentation site! Only cPanel & WHM version 82 documentation exists on our beta at this time. 84 will be added to the new site soon! Leave your feedback here: https://go.cpanel.net/docsfeedback
UAPI Functions - BoxTrapper::whitelist_messages - Developer Documentation - cPanel Documentation
Child pages
  • UAPI Functions - BoxTrapper::whitelist_messages
Skip to end of metadata
Go to start of metadata

Description

This function whitelists email message senders.

Important:

When you disable the MailReceive role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Note:

To retrieve email messages in the BoxTrapper queue from senders that you did not previously whitelist, use the UAPI BoxTrapper::deliver_messages function.


Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/BoxTrapper/whitelist_messages?email=user@example.com&queuefile=example.msg


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.
// Whitelist the messages in the BoxTrapper queue.
$whitelist_messages = $cpanel->uapi(
    'BoxTrapper', 'whitelist_messages',
    array(
        'email'     => 'user@example.com',
        'queuefile' => 'example.msg',
    )
);


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.
 
# Whitelist the messages in the BoxTrapper queue.
my $whitelist_messages = $cpliveapi->uapi(
    'BoxTrapper', 'whitelist_messages',
    {
        'email'     => 'user@example.com',
        'queuefile' => 'example.msg',
    }
);


Note:

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

 Command Line
uapi --user=username BoxTrapper whitelist_messages email=user@example.com queuefile=example.msg


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": [
         {
            "email" : "user@example.com",
            "operator" : "whitelist",
			"matches" : [
				"example.msg"
				]
         }
      ],
      "errors": null,
      "messages": null,
      "metadata": {
         "transformed": 1
      },
      "status": 1,
      "warnings": null
   }


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
email

string

Required

The email address from which to whitelist messages.

Warning:

If you call this function in Webmail, the system ignores this parameter and defaults to the currently-authenticated email address.

A valid email address on the cPanel account.user@example.com
queuefilestring

Required

The filename of the email message to whitelist.

Note:

To whitelist multiple email messages, duplicate this parameter.

A valid filename.

example.msg

Returns

ReturnTypeDescriptionPossible valuesExample

array of hashesAn array of hashes of whitelisted email information.This array of hashes contains the email, operator, and matches returns.

email

string

A whitelisted email address.

The function returns this value in the unnamed array of hashes.

A valid email address.user@example.com

operator

string

The action that the system performed.

The function returns this value in the unnamed array of hashes.

whitelist is the only possible value.whitelist

matches

array
An array of messages that the system whitelisted.

Note:

The function only returns this value if it doesn't whitelist the message.

The function returns this value in the unnamed array of hashes.

An array of whitelisted message files.example.msg

failed

string

Whether the function didn't whitelist the message.

Note:

The function only returns this value if it doesn't whitelist the message.

The function returns this value in the unnamed array of hashes.

1 is the only possible value.1

warning

Boolean

Whether the function skipped the message during whitelisting.

Note:

The function only returns this value if it doesn't whitelist the message.

The function returns this value in the unnamed array of hashes.

1 is the only possible value.1

reason

string

The reason the function skipped the message during whitelisting.

Note:

The function only returns this value if it doesn't whitelist the message.

The function returns this value in the unnamed array of hashes.

A valid string.The cPanel user, "user" does not own the requested account "user@example.com."