Child pages
  • WHM API 1 Functions - expunge_mailbox_messages
Skip to end of metadata
Go to start of metadata

Description

This function removes mail messages from a cPanel account that you select with a query.

Important:

In cPanel & WHM version 76 and later, when you disable the MailReceive role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/expunge_mailbox_messages?api.version=1&account=example&mailbox=INBOX&query=savedbefore%2052w
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/expunge_mailbox_messages?api.version=1&account=example&mailbox=INBOX&query=savedbefore%2052w
 Command Line
whmapi1 expunge_mailbox_messages account=example mailbox=INBOX query="savedbefore%2052w"


Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{  
   "metadata":{  
      "reason":"OK",
      "command":"expunge_mailbox_messages",
      "version":1,
      "result":1
   },
   "data":{  

   }
}
 Output (XML)
<result>
    </data>
    <metadata>
        <reason>OK</reason>
        <version>1</version>
        <result>1</result>
        <command>expunge_mailbox_messages</command>
    </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
accountstring

Required

The email account's name.

  • A valid email account that exists on the server.
  • The cPanel user's account name.

    Note:

    _mainaccount is an alias that represents the cPanel user's mailbox (For example, _mainaccount@example.com represents the example mailbox).


user@example.com

example

_mainaccount@example.com

mailboxstring

Required

The mailbox's name.

A valid mailbox name on the account.

Note:

Because you cannot escape wildcard characters such as (*), we recommend that you use functions that use the mailbox_guid parameter instead. For example, the WHM API 1 expunge_messages_for_mailbox_guid function.

INBOX

querystring

Required

The query to select which messages you wish to remove from the mailbox.

A valid Dovecot® search query

For more information, read Dovecot's Search Query documentation.

savedbefore 52w

Returns

This function only returns metadata.