Child pages
  • UAPI Functions - BoxTrapper::deliver_messages
Skip to end of metadata
Go to start of metadata

Description

This function delivers 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/deliver_messages?email=user@example.com&queuefile=example.msg&all_like=1


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


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


Note:

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

 cPanel Template Toolkit
<!-- deliver the messages in the BoxTrapper queue. -->
[% SET result = execute( 'BoxTrapper', 'deliver_messages',
    {
        email     => 'user@example.com',
        queuefile => 'example.msg',
        all_like  => '1',
    });
%]
[% IF result.status %]
[%   FOREACH item IN result.data %]
     [% IF item.failed %]
     Failed to deliver the message with error: [% item.reason %].
     [% ELSIF item.warning %]
     Successfully delivered all messages with sender [% item.email %], but there were other non-critical failure: [% item.reason %].
     [% ELSE %]
     Successfully delivered all messages with sender: [% item.email %].
     [% END %]
[%   END %]
[% ELSE %]
     Failed: [% result.errors.join(', ') %]
[% END %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

 Command Line
uapi --user=username BoxTrapper deliver_messages email=user@example.com queuefile=example.msg all_like=1


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" : "marching@wall.tld",
            "matches" : [
               "Ou_qPb7Ckipq_fZabxsMM-1558374343"
            ],
            "operator" : "deliver"
         }
      ],
      "status" : 1,
      "warnings" : null,
      "errors" : null,
      "metadata" : {
         "transformed" : 1
      },
      "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 sender's email address of the messages to deliver.

Warning

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

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

Required

The filename of the email messages to deliver.

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

A valid filename.

example.msg
all_likeBoolean

Whether to deliver all messages that resemble the queuefile parameter's value.

This parameter's value defaults to 0.

  • 1 — Deliver all similar messages.
  • 0 — Don't deliver all similar messages.
1

Returns

ReturnTypeDescriptionPossible valuesExample

array of hashesAn array of hashes of delivered email message informationThis array of hashes contains the email, operator, matches, failed, warning, and reason returns.

email

string

The delivered email message's sender.

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

A valid email address.user@example.com

matches

array of strings

An array of delivered email messages.

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

An array of delivered email messages.example.msg

operator

string

The action that the function performed.

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

  • deliver
  • deliverall
deliverall

failed

Boolean

Whether the system could not deliver the message.

Note:

The function only returns this value if it doesn't deliver 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 delivered the message.

Note:

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

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

1 is the only possible value.1

reason

string

A message about the failure or the warning.

Note:

The function only returns this value if it doesn't delete the message or experiences issues when it deletes the message.

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

A valid string.This is a failure message.