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::process_messages - Developer Documentation - cPanel Documentation
Child pages
  • UAPI Functions - BoxTrapper::process_messages
Skip to end of metadata
Go to start of metadata

Description

This function performs a specified action on messages in the BoxTrapper queue.

Important:

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

Examples 


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


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.
// Process the messages in the BoxTrapper queue.
$delete_messages = $cpanel->uapi(
    'BoxTrapper', 'process_messages',
    array(
        'email'     => 'user@example.com',
        'queuefile' => 'example.msg',
		'action-1'	=> 'blacklist',
		'action-2' 	=> 'deleteall',
    )
);


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.
 
# Process the messages in the BoxTrapper queue.
my $delete_messages = $cpliveapi->uapi(
    'BoxTrapper', 'process_messages',
    {
        'email'     => 'user@example.com',
        'queuefile' => 'example.msg',
		'action-1'	=> 'blacklist',
		'action-2'  => 'deleteall',
    }
);


Note:

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

 Command Line
uapi --user=username BoxTrapper process_messages email=user@example.com queuefile=example.msg action=blacklist action=deleteall


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)
	{
      "status" : 1,
      "metadata" : {
         "transformed" : 1
      },
      "data" : [
         {
            "matches" : [
               "Kt8Q6YE8MewrcMcyKi3Rn-1558466433"
            ],
            "operator" : "blacklist",
            "email" : "root@host-172-16-1-7"
         },
         {
            "matches" : [
               "Kt8Q6YE8MewrcMcyKi3Rn-1558466433"
            ],
            "operator" : "deleteall",
            "email" : "root@host-172-16-1-7"
         }
      ],
      "warnings" : null,
      "errors" : null,
      "messages" : 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 account's email address.

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

To process multiple email messages, pass this parameter multiple times.

A valid filename.

example.msg
actionstring

Required

The action to perform on the email message file.

To perform multiple actions on the specified email messages, pass this parameter multiple times.

Note:

The function performs the actions on the email messages files in the order that you pass each action.



  • deliver — Deliver a specific message.
  • deliverall — Deliver all messages from a sender.
  • delete — Delete a message.
  • deleteall — Delete all messages from a sender.
  • blacklist — Blacklist the sender of an email message.
  • whitelist — Whitelist the sender of an email message.
  • ignore — Ignore email messages from a sender.
1.

Returns

ReturnTypeDescriptionPossible valuesExample

array of hashesAn array of hashes of processed email message information.Each hash contains the matches, operator, email, failed, warning, and reason returns.

matches

array of strings

An array of email messages that the system processed.

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

An array of email message files.examplemsg

operator

string
The operation that the system performed.
The function returns this value in the unnamed array of hashes.
  • deliver — Deliver a specific message.
  • deliverall — Deliver all messages from a sender.
  • delete — Delete a message.
  • deleteall — Delete all messages from a sender.
  • blacklist — Blacklist the sender of an email message.
  • whitelist — Whitelist the sender of an email message.
  • ignore — Ignore email messages from a sender.
delete

email

string
The email address for which the system processed an email message.
The function returns this value in the unnamed array of hashes.
A valid email address.user@example.com

reason

string

A message about the failure or the warning.

Note:

The function only returns this value if it fails to processes the message or experiences issues when it processes the message.

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

A string that describes the failure or warning.
(XID d9myfd) The system failed to locate the requested message:

failure

Boolean

Whether the system failed to process the message.

Note:

The function only returns this value if it fails to processes the message.

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

1 is the only possible value.1

warning

Boolean
Whether the system experienced issues when it processed the message.

Note:

The function only returns this value if it experiences issues when it processes the message.

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

1 is the only possible value.
1