The functions within this module may or may not be governed by a feature list. The required feature list may vary from function to function, to review a total list of the available features sets on a cPanel server, please see "Feature Manager" in WHM.

BoxTrapper::statusbutton

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::statusbutton( )
Description:	Print the necessary HTML to create the BoxTrapper status change button (e.g. enable or disable). If BoxTrapper is enabled for the account, this function will generate the HTML code for the disable button. If BoxTrapper is disabled, the function will generate the HTML required for the enable button. Note: This function does not create necessary form elements for the button to work, just the HTML source for the button itself.
Returns:
	The output should resemble the following: <input type="hidden" name="action" value="Disable"> <input type="submit" class="input-button" name="submitaction" value="Disable">

BoxTrapper::showlog

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::showlog( date, account )
Description:	Print the BoxTrapper log for the given account. This function requires access to the 'boxtrapper' feature.
Parameters:
	date (string)
	The epochal time for which to view the logs. If this parameter is not specified, the function will display the current logs.
	account (string)
	The email address that owns the BoxTrapper logs to be viewed.
Returns:
	The output should resemble the following: Processing email with trusted transport method [esmtpa] test@example.com/Subject Searching for stale data files (1296000 seconds old)

BoxTrapper::messageaction

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::messageaction( account, logdate, queuefile, action )
Description:	Take an action on a single email message that currently resides in the BoxTrapper queue.
Parameters:
	account (string)
	The email account to receive the message in the queue.
	logdate (string)
	This parameter is not used. The value '' (or another value that will be ignored) should be entered here.
	queuefile (string)
	The filename of the email message on which to perform the action. (e.g. 940q7fnThXeTaITwx5x02Actb6NbYxuw.msg).
	action (string)
	The action to perform on the message. Acceptable values are: deliverall,whitelist - Whitelist and deliver all messages from the sender. deliver,whitelist - Whitelist the sender and deliver the message. deliverall - Deliver all messages from the sender. deliver - Deliver the message. delete - Delete the message from the queue. deleteall - Delete all messages from the sender. delete,blacklist - Delete the message and blacklist the sender. delete,ignorelist - Delete the message and add the sender to the ignore list.
Returns:
	This function does not produce any output.

BoxTrapper::status

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::status( account )
Description:	Retrieve the BoxTrapper status for a specific account (e.g. enabled or disabled). This function requires access to the 'boxtrapper' feature.
Parameters:
	account (string)
	The email account whose status will be retrieved.
Returns:
	The output should display either 'enabled' or 'disabled'.

BoxTrapper::showmessage

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::showmessage( account, logdate, queuefile )
Description:	Display (up to) the first 200 lines of an email in the BoxTrapper queue.
Parameters:
	account (string)
	The email account to query.
	logdate (string)
	This parameter is not functional. It should be filled with a placeholder such as ''.
	queuefile (string)
	The filename of the message to be viewed. (e.g. 940q7fnThXeTaITwx5x02Actb6NbYxuw.msg).
Returns:
	The output contains the email's text, including headers.

BoxTrapper::changestatus

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::changestatus( account, action )
Description:	Enable or disable BoxTrapper for an email account. This function requires access to the 'boxtrapper' feature.
Parameters:
	account (string)
	The email account for which to enable or disable BoxTrapper.
	action (string)
	Setting this parameter to 'enable' will enable BoxTrapper for the email address. Passing any other value to this parameter will disable BoxTrapper.
Returns:
	Output will display enabled, disabled, or a relevant error message.

BoxTrapper::resetmsg

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::resetmsg( account, message )
Description:	Set the selected BoxTrapper form letter back to its default.
Parameters:
	account (string)
	The email account corresponding to the form letter to be reset.
	message (string)
	The message ID of the file to reset in the BoxTrapper queue. Acceptable values are blacklist.txt, returnverify.txt, verifyreleased.txt, and verify.txt.
Returns:
	No output.

BoxTrapper::editmsg

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::editmsg( account, message )
Description:	Despite its name, this function does not edit any messages. Rather, it checks to see that verification and blacklist messages are present in an account's BoxTrapper configuration forms/ directory. If they are not present, the default version is copied from /usr/local/cpanel/etc/boxtrapper/forms.
Parameters:
	account (string)
	The email account whose files will be checked.
	message (string)
	The name of the file for which to be checked. Acceptable values are blacklist.txt, returnverify.txt, verifyreleased.txt, and verify.txt.
Returns:
	This function does not produce any output.

BoxTrapper::getboxconfdir

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::getboxconfdir( account )
Description:	Print the directory path to the BoxTrapper configuration directory for a specified account.
Parameters:
	account (string)
	The account whose BoxTrapper configuration directory you wish to retrieve.
Returns:
	/home/user/etc/example.com/emailuser/.boxtrapper

BoxTrapper::multimessageaction

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::multimessageaction( )
Description:	Perform an action on multiple messages contained within the BoxTrapper queue. You must have access to the 'boxtrapper' feature to use this function.
Form Data:
	account (string)
	The email account that contains the messages on which an action will be performed.
	msgid* (string)
	The message IDs to manipulate. The form field name must adhere to the following pattern: msgid1, msgid2, msgid3, etc. The values should be the filenames of the mail messages in the BoxTrapper queue (e.g. 940q7fnThXeTaITwx5x02Actb6NbYxuw.msg).
	multimsg (string)
	Acceptable values are whitelistall* and deleteall. whitelistall will add all selected senders to the white list. deleteall will delete the all of the selected mail messages.*
Returns:
	The output should resemble the following: Deleted 940q7fnThXeTaITwx5x02Actb6NbYxuw.msg from test@example.com

BoxTrapper::cleancfgfilelist

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::cleancfgfilelist( account, filetype, cfgfile )
Description:	This function will remove duplicates and standardize regular expressions to overcome common user errors in a BoxTrapper configuration file. After the function finishes, the file is rewritten in the 'clean' state. This function requires access to the 'boxtrapper' feature.
Parameters:
	account (string)
	The email account that owns the BoxTrapper configuration file to be cleaned.
	filetype (string)
	This parameter must be set to list.
	cfgfile (string)
	The name of the configuration file to be cleaned. Acceptable values are black-list.txt, ignore-list.txt, and white-list.txt.
Returns:
	None.

BoxTrapper::showqueuetime

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::showqueuetime( account )
Description:	Retrieve the number of days messages are kept in an account's BoxTrapper queue.
Parameters:
	account (string)
	The email account to query.
Returns:
	The function will return an number such as: 15

BoxTrapper::saveconf

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::saveconf( account, froms, queuetime, autowhitelist, fromname )
Description:	Make changes to and save a specific Boxtrapper configuration file. This function requires access to the 'boxtrapper' feature.
Parameters:
	account (string)
	The email account that corresponds to the configuration file to be saved.
	froms (string)
	This parameter accepts a comma-separated list of email addresses that send mail to the email account.
	queuetime (integer)
	This parameter specifies how many days logs and messages should be kept in the queue.
	autowhitelist (boolean)
	Whether or not to allow automatic whitelisting. Passing this parameter 1 will enable whitelisting. Passing this parameter 0 will disable automatic whitelisting.
	fromname (string)
	The From:* name to appear on form emails sent from BoxTrapper.*
Returns:
	No output.

BoxTrapper::logcontrols

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::logcontrols( )
Description:	Print a date-selection interface that allows the user to select BoxTrapper logs to view. The links created by this function are relative to the HTML page from which the call was made.
Returns:
	The output should resemble: <td align="left"><a href="/frontend/x3/test.html?bxaction=&account=test@example.com&logdate=1266472871"><< 02-18-2010</a> </td><td align="center"> 02-19-2010</td><td align="right"> <a href="/frontend/x3/test.html?bxaction=&account=test@example.com&logdate=1266645671">02-20-2010 >></a> </td>

BoxTrapper::showfromname

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::showfromname( account )
Description:	Print the name used in the From: field for Boxtrapper form emails.
Parameters:
	account (string)
	The email account to query.
Returns:
	The output contains the name that will appear in the From: field. There will be no output if it is not configured in the user's boxtrapper.conf.

BoxTrapper::listmsgs

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::listmsgs( account, editfile, resetfile )
Description:	Generate a user interface for editing BoxTrapper form letters.
Parameters:
	account (string)
	The email account for which to generate the interface.
	editfile (string)
	This parameter defaults to editmsg.html. This parameter represents the target for the Edit* buttons in the interface.*
	resetfile (2)
	This parameter defaults to resetmsg.html. This parameter represents the target for the Reset to default* buttons in the interface.*
Returns:
	The output should resemble: <tr> <td>verify</td> <td> <form action="editmsg.html"> <input type="hidden" name="account" value="cptest@hello.com"> <input type="hidden" name="form" value="verify.txt"> <input type="hidden" name="emaildir" value="/home/pippin/etc/hello.com/cptest/.boxtrapper/forms"> <input type="submit" class="input-button" value="Edit"> </form> </td> <td> <form action="resetmsg.html"> <input type="hidden" name="account" value="cptest@hello.com"> <input type="hidden" name="form" value="verify.txt"> <input type="hidden" name="emaildir" value="/home/pippin/etc/hello.com/cptest/.boxtrapper/forms"> <input type="submit" class="input-button" value="Reset to default"> </form> </td> </tr> <tr> <td>verifyreleased</td> <td> <form action="editmsg.html"> <input type="hidden" name="account" value="cptest@hello.com"> <input type="hidden" name="form" value="verifyreleased.txt"> <input type="hidden" name="emaildir" value="/home/pippin/etc/hello.com/cptest/.boxtrapper/forms"> <input type="submit" class="input-button" value="Edit"> </form> </td> <td> <form action="resetmsg.html"> <input type="hidden" name="account" value="cptest@hello.com"> <input type="hidden" name="form" value="verifyreleased.txt"> <input type="hidden" name="emaildir" value="/home/pippin/etc/hello.com/cptest/.boxtrapper/forms"> <input type="submit" class="input-button" value="Reset to default"> </form> </td> </tr> <tr> <td>blacklist</td> <td> <form action="editmsg.html"> <input type="hidden" name="account" value="cptest@hello.com"> <input type="hidden" name="form" value="blacklist.txt"> <input type="hidden" name="emaildir" value="/home/pippin/etc/hello.com/cptest/.boxtrapper/forms"> <input type="submit" class="input-button" value="Edit"> </form> </td> <td> <form action="resetmsg.html"> <input type="hidden" name="account" value="cptest@hello.com"> <input type="hidden" name="form" value="blacklist.txt"> <input type="hidden" name="emaildir" value="/home/pippin/etc/hello.com/cptest/.boxtrapper/forms"> <input type="submit" class="input-button" value="Reset to default"> </form> </td> </tr> <tr> <td>returnverify</td> <td> <form action="editmsg.html"> <input type="hidden" name="account" value="cptest@hello.com"> <input type="hidden" name="form" value="returnverify.txt"> <input type="hidden" name="emaildir" value="/home/pippin/etc/hello.com/cptest/.boxtrapper/forms"> <input type="submit" class="input-button" value="Edit"> </form> </td> <td> <form action="resetmsg.html"> <input type="hidden" name="account" value="cptest@hello.com"> <input type="hidden" name="form" value="returnverify.txt"> <input type="hidden" name="emaildir" value="/home/pippin/etc/hello.com/cptest/.boxtrapper/forms"> <input type="submit" class="input-button" value="Reset to default"> </form> </td> </tr>

BoxTrapper::showautowhitelist

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::showautowhitelist( account )
Description:	Retrieve a string that indicates whether or not automatic whitelisting is enabled for the specified email account.
Parameters:
	account (string)
	The email account to query.
Returns:
	Returns 'checked="checked"' if autowhitelisting is enabled. Otherwise, returns nothing.

BoxTrapper::fetchcfgfile

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::fetchcfgfile( account, filetype, cfgfile )
Description:	Retrieve BoxTrapper lists and messages for a particular user.
Parameters:
	account (string)
	The email account to query.
	filetype (string)
	The type of configuration file to retrieve. Acceptable values are msg and list. list is used to retrieve black-list.txt, ignore-list.txt, and white-list.txt. Use msg to retrieve configuration files from the forms/ directory that include form letters for blacklist.txt, returnverify.txt, verifyreleased.txt, and verify.txt.
	cfgfile (string)
	The configuration file to retrieve. Acceptable values are black-list.txt, ignore-list.txt, white-list.txt, returnverify.txt, verifyreleased.txt, and verify.txt. You must select the proper value for $filetype.
Returns:
	Output will be the file selected.

BoxTrapper::showemails

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::showemails( account )
Description:	List email addresses that send email to a specific account.
Parameters:
	account (string)
	The email account to query.
Returns:
	The output is a list of email addresses, or nothing.

BoxTrapper::savecfgfile

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::savecfgfile( account, filetype, cfgfile, page )
Description:	Save a given string to a specific BoxTrapper configuration file. This function requires access to the 'boxtrapper' feature.
Parameters:
	account (string)
	The email account that owns the BoxTrapper configuration file to be modified.
	filetype (string)
	Acceptable values are list* and msg. list will save the file to the account's BoxTrapper config/ directory. msg will save the file to the forms/ subdirectory.*
	cfgfile (string)
	The name of the file to be modified.
	page (string)
	The text to be added to the configuration file.
Returns:
	No output.

BoxTrapper::showqueue

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::showqueue( logdate , account, showfile, bxaction, skipcontrols )
Description:	Print an index of an account's BoxTrapper queue, filtered by date.
Parameters:
	logdate (integer (optional))
	The date to view, in Unix epochal time. This parameter defaults to the current time.
	account (string)
	The email account to query.
	showfile (string)
	The file to which requests to view emails should be directed. This parameter should be set to showmsg.html for best results. If the parameter is set to another value, the resulting page may contain broken links.
	bxaction (string)
	This parameter is not functional. It should be filled with a placeholder such as ''.
	skipcontrols (boolean)
	Setting this parameter to 1 causes the function to skip printing multi message functions.
Returns:
	The output should resemble the following: <input type="hidden" name="account" value="test@example.com"> <input type="hidden" name="bxaction" value="multimsgaction"> <tr class="tdshade1"> <td width="5%"><input type="checkbox" name="msgid0" value="qM3nKcgdNWKJQoJmzYxHtUfCHJYMMLki.msg"></td> <td class="truncate" truncate="25" width="15%"><a href="showmsg.html?account=test@example.com&q=qM3nKcgdNWKJQoJmzYxHtUfCHJYMMLki.msg&bxaction=">test@cpanel.net</a></td> <td class="truncate" truncate="75"><a href="showmsg.html?account=test@example.com&q=qM3nKcgdNWKJQoJmzYxHtUfCHJYMMLki.msg&bxaction=">Subject</a></td> <td width="15%"><a href="showmsg.html?account=test@example.com&q=qM3nKcgdNWKJQoJmzYxHtUfCHJYMMLki.msg&bxaction=">02/19 20:40:05</a></td> </tr> <tr class="tdshade2"> <td width="5%"><input type="checkbox" name="msgid1" value="TnOFsIHUb3EX19Wcqlc1DwAEqwSxaIUL.msg"></td> <td class="truncate" truncate="25" width="15%"><a href="showmsg.html?account=test@example.com&q=TnOFsIHUb3EX19Wcqlc1DwAEqwSxaIUL.msg&bxaction=">test@cpanel.net</a></td> <td class="truncate" truncate="75"><a href="showmsg.html?account=test@example.com&q=TnOFsIHUb3EX19Wcqlc1DwAEqwSxaIUL.msg&bxaction=">Subject</a></td> <td width="15%"><a href="showmsg.html?account=test@example.com&q=TnOFsIHUb3EX19Wcqlc1DwAEqwSxaIUL.msg&bxaction=">02/19 20:40:14</a></td> </tr>

BoxTrapper::showqueuesearch

API Version:	1 - Click here for documentation
Syntax:	BoxTrapper::showqueuesearch( field, string, account, showfile, bxaction, skipcontrols )
Description:	Search a BoxTrapper queue.
Parameters:
	field (string)
	The field to search. Acceptable values include sender, subject, and body.
	string (string)
	The string for which to search.
	account (string)
	The email account corresponding to the BoxTrapper queue to be searched.
	showfile (string)
	This parameter should be set to queuesearch.html. If it is not set to queuesearch.html, links in the output will be broken.
	bxaction (string)
	This parameter is not functional. It should be filled with a placeholder such as ''.
	skipcontrols (boolean)
	Passing 1 to this parameter causes the function to suppress some of the HTML output. This provides the user more options after the search is complete, such as multimsgaction* options.*
Returns:
	<input type="hidden" name="account" value="test@example.com"> <input type="hidden" name="bxaction" value="multimsgaction"> <tr class="tdshade2"> <td width="5%"><input type="checkbox" name="msgid0" value="qM3nKcgdNWKJQoJmzYxHtUfCHJYMMLki.msg"></td> <td class="truncate" truncate="25" width="15%"><a href="showmsg.html?account=test@example.com&q=qM3nKcgdNWKJQoJmzYxHtUfCHJYMMLki.msg&bxaction=1">lee@cpanel.net</a></td> <td class="truncate" truncate="75"><a href="showmsg.html?account=test@example.com&q=qM3nKcgdNWKJQoJmzYxHtUfCHJYMMLki.msg&bxaction=1">Subject</a></td> <td width="15%"><a href="showmsg.html?account=test@example&q=qM3nKcgdNWKJQoJmzYxHtUfCHJYMMLki.msg&bxaction=1">02/19 20:40:05</a></td> </tr>

Topic revision: r2 - 27 Mar 2012 - 17:27:07 - Main.JenniferDoubrava